nodedb_mem/lib.rs
1// SPDX-License-Identifier: Apache-2.0
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 collection_arena;
39pub mod engine;
40pub mod engine_limits;
41pub mod error;
42pub mod governor;
43pub mod metrics;
44pub mod over_release;
45pub mod pressure;
46pub mod reservation_token;
47mod reserve_scope;
48mod scoped_budget;
49pub mod scoped_memory;
50pub mod spill;
51
52pub use arena::{bind_thread_to_local_numa, current_thread_arena, pin_thread_arena};
53pub use budget::Budget;
54pub use collection_arena::{CollectionArenaHandle, CollectionArenaRegistry};
55pub use engine::EngineId;
56pub use engine_limits::EngineLimits;
57pub use error::{MemError, Result};
58pub use governor::{GovernorConfig, MemoryGovernor};
59pub use over_release::{Layer, OverRelease};
60pub use pressure::{PressureLevel, PressureThresholds};
61pub use reservation_token::ReservationToken;
62pub use scoped_memory::ScopedMemory;
63pub use spill::{SpillAction, SpillConfig, SpillController};