Skip to main content

second_brain_api/
heap.rs

1//! Allocator residency accounting for `/v1/status`.
2//!
3//! The daemon runs under a hard `MemoryMax` and has twice been cgroup-OOM-
4//! killed on anonymous RSS with no retained structure anywhere near the size
5//! of the resident set: the store holds ~12k memories (~18 MB of embeddings)
6//! while RSS sits above 1.7 GB. Anonymous RSS alone cannot say whether those
7//! bytes are live data or memory the allocator has taken from the kernel and
8//! not given back, and that distinction picks the remedy: freed-but-retained
9//! bytes point at glibc's per-thread arenas, whose non-main arenas only ever
10//! trim their top chunk, while live bytes point at a working set that simply
11//! does not fit the cap.
12//!
13//! `mallinfo2` aggregates every arena, and glibc is where both the Rust side
14//! and the C/C++ side (onnxruntime, usearch, sqlite) get their memory, so a
15//! single reading covers the whole process.
16
17use std::path::Path;
18
19/// glibc's non-main arenas are 64 MiB mmaps aligned to their own size, so an
20/// anonymous mapping matching both is an arena rather than an ordinary large
21/// allocation. Counting them turns "how fragmented is this" into a number that
22/// can be watched over time.
23const ARENA_BYTES: u64 = 64 * 1024 * 1024;
24
25#[derive(Debug, Clone, Copy, Default, serde::Serialize)]
26pub struct HeapStats {
27    /// In-use bytes: arena chunks handed out, plus live mmapped allocations.
28    pub live_bytes: u64,
29    /// Bytes the allocator holds free inside arenas it has not returned.
30    pub free_bytes: u64,
31    /// Total bytes the allocator has taken from the kernel.
32    pub system_bytes: u64,
33    /// Anonymous resident set, the figure the cgroup limit is enforced against.
34    pub rss_anon_bytes: u64,
35    /// Count of mappings carrying glibc's non-main arena signature.
36    pub arena_mappings: usize,
37}
38
39impl HeapStats {
40    /// Share of the allocator's footprint that is free but still charged to
41    /// the process. A high value under a flat live figure is the signature of
42    /// arena retention rather than of a working set that outgrew its cap.
43    pub fn retained_fraction(&self) -> f64 {
44        if self.system_bytes == 0 {
45            return 0.0;
46        }
47        self.free_bytes as f64 / self.system_bytes as f64
48    }
49}
50
51#[cfg(target_env = "gnu")]
52fn allocator_bytes() -> (u64, u64, u64) {
53    // SAFETY: mallinfo2 takes no arguments, reads only allocator state behind
54    // its own locks, and returns a plain value type.
55    let info = unsafe { libc::mallinfo2() };
56    let arena = info.arena as u64;
57    let mmapped = info.hblkhd as u64;
58    let in_use = info.uordblks as u64;
59    let free = info.fordblks as u64;
60    (in_use + mmapped, free, arena + mmapped)
61}
62
63#[cfg(not(target_env = "gnu"))]
64fn allocator_bytes() -> (u64, u64, u64) {
65    (0, 0, 0)
66}
67
68pub fn rss_anon_bytes(status_path: &Path) -> u64 {
69    let Ok(status) = std::fs::read_to_string(status_path) else {
70        return 0;
71    };
72    rss_anon_from_status(&status)
73}
74
75fn rss_anon_from_status(status: &str) -> u64 {
76    for line in status.lines() {
77        if let Some(rest) = line.strip_prefix("RssAnon:") {
78            let kb: u64 = rest
79                .trim()
80                .trim_end_matches("kB")
81                .trim()
82                .parse()
83                .unwrap_or(0);
84            return kb * 1024;
85        }
86    }
87    0
88}
89
90pub fn arena_mappings(maps_path: &Path) -> usize {
91    let Ok(maps) = std::fs::read_to_string(maps_path) else {
92        return 0;
93    };
94    arena_mappings_from_maps(&maps)
95}
96
97fn arena_mappings_from_maps(maps: &str) -> usize {
98    maps.lines()
99        .filter(|line| {
100            let mut fields = line.split_whitespace();
101            let Some(range) = fields.next() else {
102                return false;
103            };
104            // A named mapping is a file, a stack or the main heap; only
105            // unnamed ones can be a non-main arena.
106            if fields.clone().count() >= 5 {
107                return false;
108            }
109            let Some((start, end)) = range.split_once('-') else {
110                return false;
111            };
112            let (Ok(start), Ok(end)) =
113                (u64::from_str_radix(start, 16), u64::from_str_radix(end, 16))
114            else {
115                return false;
116            };
117            end - start == ARENA_BYTES && start % ARENA_BYTES == 0
118        })
119        .count()
120}
121
122pub fn heap_stats() -> HeapStats {
123    let (live_bytes, free_bytes, system_bytes) = allocator_bytes();
124    HeapStats {
125        live_bytes,
126        free_bytes,
127        system_bytes,
128        rss_anon_bytes: rss_anon_bytes(Path::new("/proc/self/status")),
129        arena_mappings: arena_mappings(Path::new("/proc/self/maps")),
130    }
131}
132
133#[cfg(test)]
134mod tests {
135    use super::*;
136
137    #[test]
138    fn rss_anon_is_read_as_bytes() {
139        let status = "Name:\tsb\nVmRSS:\t 1653472 kB\nRssAnon:\t 1626960 kB\nThreads:\t24\n";
140        assert_eq!(rss_anon_from_status(status), 1_626_960 * 1024);
141    }
142
143    #[test]
144    fn rss_anon_missing_field_reads_zero() {
145        assert_eq!(rss_anon_from_status("Name:\tsb\nThreads:\t24\n"), 0);
146    }
147
148    #[test]
149    fn only_unnamed_64mib_aligned_mappings_count_as_arenas() {
150        let maps = concat!(
151            // An arena: unnamed, exactly 64 MiB, aligned to 64 MiB.
152            "7f0004000000-7f0008000000 rw-p 00000000 00:00 0\n",
153            // Same size and alignment but file-backed, so not an arena.
154            "7f0010000000-7f0014000000 rw-p 00000000 08:01 1234 /lib/libc.so.6\n",
155            // Unnamed and 64 MiB but not 64 MiB-aligned.
156            "7f0018100000-7f001c100000 rw-p 00000000 00:00 0\n",
157            // Unnamed and aligned but a 2 MiB thread stack.
158            "7f0020000000-7f0020200000 rw-p 00000000 00:00 0\n",
159            "555500000000-555500100000 rw-p 00000000 00:00 0 [heap]\n",
160        );
161        assert_eq!(arena_mappings_from_maps(maps), 1);
162    }
163
164    #[test]
165    fn retained_fraction_is_free_over_system_and_zero_when_empty() {
166        let stats = HeapStats {
167            free_bytes: 300,
168            system_bytes: 1200,
169            ..Default::default()
170        };
171        assert!((stats.retained_fraction() - 0.25).abs() < 1e-9);
172        assert_eq!(HeapStats::default().retained_fraction(), 0.0);
173    }
174}