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 budget_guard::BudgetGuard;

pub use collection_arena::CollectionArenaHandle;

pub use collection_arena::CollectionArenaRegistry;

pub use engine::EngineId;

pub use error::MemError;

pub use error::Result;

pub use governor::GovernorConfig;

pub use governor::MemoryGovernor;

pub use pressure::PressureLevel;

pub use pressure::PressureThresholds;

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.

budget_guard

RAII budget guard for the memory governor.

collection_arena

Per-collection jemalloc arena registry.

engine

Engine identification for memory budget tracking.

error

governor

Central memory governor.

metrics

Metrics export for the memory governor.

pressure

Memory pressure levels for gradual backpressure.

spill

Cooperative spill controller for per-core arena overflow.