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