Crate nodedb_mem 

nodedb-mem

Global NUMA-aware memory governor for NodeDB.

Prevents subsystem OOM and cache cannibalization by enforcing per-engine memory budgets backed by jemalloc’s introspection APIs.

Problem

If DataFusion does a massive GROUP BY, it allocates RAM until OOM kills the process — taking Glommio threads, HNSW caches, and open io_uring submissions down with it.

If the timeseries engine flushes 5 GB of Gorilla-encoded segments, it can evict the vector engine’s hot HNSW routing layers from the OS page cache.

Solution

A centralized memory governor that:

1. Tracks allocations per engine (Vector, Sparse, CRDT, Timeseries, Query).
2. Enforces hard limits — allocation requests beyond the budget are rejected with a deterministic error, forcing the caller to spill or backpressure.
3. Supports dynamic rebalancing — the governor can shift budget from idle engines to active ones within the global ceiling.
4. Exposes metrics for all budget states and breach events.

Validation target

Under a mixed workload (vector search + bulk timeseries ingest + SQL GROUP BY), no single engine should exceed its budget, and total RSS should stay within the configured global ceiling.

Re-exports

pub use arena::bind_thread_to_local_numa;

pub use arena::current_thread_arena;

pub use arena::pin_thread_arena;

pub use budget::Budget;

pub use collection_arena::CollectionArenaHandle;

pub use collection_arena::CollectionArenaRegistry;

pub use engine::EngineId;

pub use engine_limits::EngineLimits;

pub use error::MemError;

pub use error::Result;

pub use governor::GovernorConfig;

pub use governor::MemoryGovernor;

pub use over_release::Layer;

pub use over_release::OverRelease;

pub use pressure::PressureLevel;

pub use pressure::PressureThresholds;

pub use reservation_token::ReservationToken;

pub use scoped_memory::ScopedMemory;

pub use spill::SpillAction;

pub use spill::SpillConfig;

pub use spill::SpillController;

Modules

arena

Per-thread jemalloc arena pinning for Thread-per-Core isolation.

budget

Per-engine memory budget tracking.

collection_arena

Per-collection jemalloc arena registry.

engine

Engine identification for memory budget tracking.

engine_limits

Total per-engine byte limit map.

error

governor

Central memory governor.

metrics

Metrics export for the memory governor.

over_release

Over-release detection on the live reservation-release path.

pressure

Memory pressure levels for gradual backpressure.

reservation_token

RAII reservation token for the four-level memory hierarchy.

scoped_memory

Governor handle pre-bound to a database, tenant, and engine.

spill

Cooperative spill controller for per-core arena overflow.