nodedb_mem/lib.rs
1//! # nodedb-mem
2//!
3//! Global NUMA-aware memory governor for NodeDB.
4//!
5//! Prevents subsystem OOM and cache cannibalization by enforcing per-engine
6//! memory budgets backed by jemalloc's introspection APIs.
7//!
8//! ## Problem
9//!
10//! If DataFusion does a massive `GROUP BY`, it allocates RAM until OOM kills
11//! the process — taking Glommio threads, HNSW caches, and open io_uring
12//! submissions down with it.
13//!
14//! If the timeseries engine flushes 5 GB of Gorilla-encoded segments, it can
15//! evict the vector engine's hot HNSW routing layers from the OS page cache.
16//!
17//! ## Solution
18//!
19//! A centralized memory governor that:
20//!
21//! 1. Tracks allocations per engine (Vector, Sparse, CRDT, Timeseries, Query).
22//! 2. Enforces hard limits — allocation requests beyond the budget are rejected
23//! with a deterministic error, forcing the caller to spill or backpressure.
24//! 3. Supports dynamic rebalancing — the governor can shift budget from idle
25//! engines to active ones within the global ceiling.
26//! 4. Exposes metrics for all budget states and breach events.
27//!
28//! ## Validation target
29//!
30//! Under a mixed workload (vector search + bulk timeseries ingest + SQL GROUP BY),
31//! no single engine should exceed its budget, and total RSS should stay within
32//! the configured global ceiling.
33
34pub mod arena;
35pub mod budget;
36pub mod engine;
37pub mod error;
38pub mod governor;
39pub mod metrics;
40pub mod overflow;
41pub mod pressure;
42pub mod spill;
43
44pub use budget::Budget;
45pub use engine::EngineId;
46pub use error::{MemError, Result};
47pub use governor::MemoryGovernor;
48pub use overflow::OverflowRegion;
49pub use pressure::{PressureLevel, PressureThresholds};
50pub use spill::{SpillAction, SpillConfig, SpillController};