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