Skip to main content

second_brain_api/
heap.rs

1//! The glibc arena cap the daemon starts under, and allocator residency
2//! accounting for `/v1/status`.
3//!
4//! The daemon runs under a hard `MemoryMax` and has twice been cgroup-OOM-
5//! killed on anonymous RSS with no retained structure anywhere near the size
6//! of the resident set: the store holds ~12k memories (~18 MB of embeddings)
7//! while RSS sits above 1.7 GB. Anonymous RSS alone cannot say whether those
8//! bytes are live data or memory the allocator has taken from the kernel and
9//! not given back, and that distinction picks the remedy: freed-but-retained
10//! bytes point at glibc's per-thread arenas, whose non-main arenas only ever
11//! trim their top chunk, while live bytes point at a working set that simply
12//! does not fit the cap.
13//!
14//! `mallinfo2` aggregates every arena, and glibc is where both the Rust side
15//! and the C/C++ libraries that use malloc (onnxruntime, sqlite) get their
16//! memory; usearch maps its own tapes, which the component report counts.
17
18use std::path::Path;
19use std::sync::{Mutex, PoisonError};
20
21use second_brain_core::residency::{self, ComponentResidency, IndexMemory};
22
23use crate::AppState;
24
25pub const ARENA_CAP: i32 = 2;
26
27/// Caps glibc at `ARENA_CAP` malloc arenas unless `MALLOC_ARENA_MAX` is set.
28/// With an arena per thread, anonymous RSS ratcheted with every recall until
29/// the Pi's cgroup killed the daemon. Threads that already allocated keep
30/// their arena, so call it before any thread starts.
31pub fn cap_arenas() {
32    if std::env::var_os("MALLOC_ARENA_MAX").is_some() {
33        return;
34    }
35    set_arena_max(ARENA_CAP);
36}
37
38#[cfg(target_env = "gnu")]
39fn set_arena_max(arenas: i32) {
40    if unsafe { libc::mallopt(libc::M_ARENA_MAX, arenas) } == 0 {
41        eprintln!("cannot cap glibc at {arenas} malloc arenas");
42    }
43}
44
45#[cfg(not(target_env = "gnu"))]
46fn set_arena_max(_arenas: i32) {}
47
48/// glibc's non-main arenas are 64 MiB mmaps aligned to their own size, so an
49/// anonymous mapping matching both is an arena rather than an ordinary large
50/// allocation. Counting them turns "how fragmented is this" into a number that
51/// can be watched over time.
52const ARENA_BYTES: u64 = 64 * 1024 * 1024;
53
54#[derive(Debug, Clone, Copy, Default, serde::Serialize)]
55pub struct HeapStats {
56    /// In-use bytes: arena chunks handed out, plus live mmapped allocations.
57    pub live_bytes: u64,
58    /// Bytes the allocator holds free inside arenas, resident or not; the
59    /// `allocator_free` component counts only the resident part.
60    pub free_bytes: u64,
61    /// Total bytes the allocator has taken from the kernel.
62    pub system_bytes: u64,
63    /// Anonymous resident set, the figure the cgroup limit is enforced against.
64    pub rss_anon_bytes: u64,
65    /// Count of mappings carrying glibc's non-main arena signature.
66    pub arena_mappings: usize,
67}
68
69/// `HeapStats` plus where the anonymous resident set goes, per component.
70#[derive(Debug, Clone, Copy, serde::Serialize)]
71pub struct HeapReport {
72    #[serde(flatten)]
73    pub stats: HeapStats,
74    pub components: ComponentResidency,
75    /// `rss_anon_bytes` minus the components' total; negative when a
76    /// component counts bytes that are not resident.
77    pub unattributed_bytes: i64,
78}
79
80static INDEX_WRITER: Mutex<Option<IndexMemory>> = Mutex::new(None);
81
82/// What the drain loop's writer `Indexes` holds, or `None` while it is
83/// released. Process-wide, like the RSS it is compared against.
84pub fn record_index_writer(memory: Option<IndexMemory>) {
85    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner) = memory;
86}
87
88fn recorded_index_writer() -> Option<IndexMemory> {
89    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner)
90}
91
92pub fn component_residency(state: &AppState) -> ComponentResidency {
93    let reader = state.indexes.as_ref().map(|indexes| {
94        indexes
95            .read()
96            .unwrap_or_else(PoisonError::into_inner)
97            .memory()
98    });
99    residency::measure(
100        state.embedder.as_deref(),
101        state.reranker.as_deref(),
102        reader,
103        recorded_index_writer(),
104    )
105}
106
107/// Takes the reader index lock briefly, so call it off the async runtime.
108pub fn heap_report(state: &AppState) -> HeapReport {
109    let stats = heap_stats();
110    let components = component_residency(state);
111    HeapReport {
112        stats,
113        components,
114        unattributed_bytes: stats.rss_anon_bytes as i64 - components.total() as i64,
115    }
116}
117
118pub fn arena_mappings(maps_path: &Path) -> usize {
119    let Ok(maps) = std::fs::read_to_string(maps_path) else {
120        return 0;
121    };
122    arena_mappings_from_maps(&maps)
123}
124
125fn arena_mappings_from_maps(maps: &str) -> usize {
126    maps.lines()
127        .filter(|line| {
128            let mut fields = line.split_whitespace();
129            let Some(range) = fields.next() else {
130                return false;
131            };
132            // A named mapping is a file, a stack or the main heap; only
133            // unnamed ones can be a non-main arena.
134            if fields.clone().count() >= 5 {
135                return false;
136            }
137            let Some((start, end)) = range.split_once('-') else {
138                return false;
139            };
140            let (Ok(start), Ok(end)) =
141                (u64::from_str_radix(start, 16), u64::from_str_radix(end, 16))
142            else {
143                return false;
144            };
145            end - start == ARENA_BYTES && start % ARENA_BYTES == 0
146        })
147        .count()
148}
149
150pub fn heap_stats() -> HeapStats {
151    let allocator = residency::allocator_bytes();
152    HeapStats {
153        live_bytes: allocator.live,
154        free_bytes: allocator.free,
155        system_bytes: allocator.system,
156        rss_anon_bytes: residency::rss_anon_bytes(),
157        arena_mappings: arena_mappings(Path::new("/proc/self/maps")),
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    #[test]
166    fn only_unnamed_64mib_aligned_mappings_count_as_arenas() {
167        let maps = concat!(
168            // An arena: unnamed, exactly 64 MiB, aligned to 64 MiB.
169            "7f0004000000-7f0008000000 rw-p 00000000 00:00 0\n",
170            // Same size and alignment but file-backed, so not an arena.
171            "7f0010000000-7f0014000000 rw-p 00000000 08:01 1234 /lib/libc.so.6\n",
172            // Unnamed and 64 MiB but not 64 MiB-aligned.
173            "7f0018100000-7f001c100000 rw-p 00000000 00:00 0\n",
174            // Unnamed and aligned but a 2 MiB thread stack.
175            "7f0020000000-7f0020200000 rw-p 00000000 00:00 0\n",
176            "555500000000-555500100000 rw-p 00000000 00:00 0 [heap]\n",
177        );
178        assert_eq!(arena_mappings_from_maps(maps), 1);
179    }
180}