Skip to main content

second_brain_core/
residency.rs

1//! Where a process's anonymous resident memory goes, per component: model
2//! sessions, vector and lexical indexes, SQLite, and what the allocator holds
3//! free. Every figure is per process, like the RSS it is compared against.
4
5use serde::Serialize;
6
7use crate::embedding::Embedder;
8use crate::retrieval::Reranker;
9
10#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
11pub struct AllocatorBytes {
12    /// Arena chunks handed out plus live mmapped allocations.
13    pub live: u64,
14    /// Bytes held free inside arenas, including chunks whose pages
15    /// `release_free_heap` has handed back to the kernel.
16    pub free: u64,
17    /// Everything the allocator has taken from the kernel.
18    pub system: u64,
19}
20
21/// glibc's figures summed over every arena, which covers Rust and the C/C++
22/// libraries that allocate through malloc (onnxruntime, SQLite); usearch maps
23/// its tapes itself, so `IndexMemory` counts those. Zeros on other allocators.
24#[cfg(target_env = "gnu")]
25pub fn allocator_bytes() -> AllocatorBytes {
26    // SAFETY: mallinfo2 takes no arguments, reads only allocator state behind
27    // its own locks, and returns a plain value type.
28    let info = unsafe { libc::mallinfo2() };
29    let mmapped = info.hblkhd as u64;
30    AllocatorBytes {
31        live: info.uordblks as u64 + mmapped,
32        free: info.fordblks as u64,
33        system: info.arena as u64 + mmapped,
34    }
35}
36
37#[cfg(not(target_env = "gnu"))]
38pub fn allocator_bytes() -> AllocatorBytes {
39    AllocatorBytes::default()
40}
41
42/// Hands the pages of free chunks in every arena back to the kernel. Freed
43/// memory otherwise stays charged to the process after a large pass, because
44/// glibc only returns an arena's top chunk on free. A no-op on other
45/// allocators.
46#[cfg(target_env = "gnu")]
47pub fn release_free_heap() {
48    // SAFETY: malloc_trim takes the allocator's own locks and touches only
49    // free chunks.
50    unsafe { libc::malloc_trim(0) };
51}
52
53#[cfg(not(target_env = "gnu"))]
54pub fn release_free_heap() {}
55
56/// The process's anonymous resident set, the figure a cgroup memory limit is
57/// enforced against; 0 where `/proc/self/status` is unreadable.
58pub fn rss_anon_bytes() -> u64 {
59    std::fs::read_to_string("/proc/self/status").map_or(0, |status| rss_anon_from_status(&status))
60}
61
62fn rss_anon_from_status(status: &str) -> u64 {
63    status
64        .lines()
65        .find_map(|line| line.strip_prefix("RssAnon:"))
66        .map_or(0, |rest| {
67            rest.trim()
68                .trim_end_matches("kB")
69                .trim()
70                .parse::<u64>()
71                .unwrap_or(0)
72                * 1024
73        })
74}
75
76/// Bytes SQLite has allocated across every connection in the process, page
77/// caches and statement caches included.
78pub fn sqlite_memory_used() -> u64 {
79    let mut current: i64 = 0;
80    let mut highwater: i64 = 0;
81    // SAFETY: sqlite3_status64 only writes the two out-params, and the
82    // bundled build keeps memory statistics on (SQLITE_DEFAULT_MEMSTATUS=1).
83    let rc = unsafe {
84        rusqlite::ffi::sqlite3_status64(
85            rusqlite::ffi::SQLITE_STATUS_MEMORY_USED,
86            &mut current,
87            &mut highwater,
88            0,
89        )
90    };
91    if rc == rusqlite::ffi::SQLITE_OK {
92        current.max(0) as u64
93    } else {
94        0
95    }
96}
97
98/// Anonymous memory one `Indexes` holds. Mapped files are file-backed and so
99/// not counted here.
100#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
101pub struct IndexMemory {
102    pub vectors: u64,
103    pub lexical: u64,
104}
105
106#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
107pub struct ComponentResidency {
108    pub embedder: u64,
109    pub reranker: u64,
110    pub vector_writer: u64,
111    pub vector_reader: u64,
112    pub lexical: u64,
113    pub sqlite: u64,
114    pub allocator_free: u64,
115}
116
117impl ComponentResidency {
118    pub fn total(&self) -> u64 {
119        self.embedder
120            + self.reranker
121            + self.vector_writer
122            + self.vector_reader
123            + self.lexical
124            + self.sqlite
125            + self.allocator_free
126    }
127}
128
129/// `writer` is `None` when no writer `Indexes` is open, as when the daemon's
130/// drain loop has released its copy.
131pub fn measure(
132    embedder: Option<&Embedder>,
133    reranker: Option<&Reranker>,
134    reader: Option<IndexMemory>,
135    writer: Option<IndexMemory>,
136) -> ComponentResidency {
137    let reader = reader.unwrap_or_default();
138    let writer = writer.unwrap_or_default();
139    ComponentResidency {
140        embedder: embedder.map_or(0, Embedder::resident_bytes),
141        reranker: reranker.map_or(0, Reranker::resident_bytes),
142        vector_writer: writer.vectors,
143        vector_reader: reader.vectors,
144        lexical: reader.lexical + writer.lexical,
145        sqlite: sqlite_memory_used(),
146        allocator_free: resident_free(
147            allocator_bytes(),
148            rss_anon_bytes(),
149            reader.vectors + writer.vectors,
150        ),
151    }
152}
153
154/// An estimate of the free allocator bytes still resident: the anonymous RSS
155/// that live allocations and the vector indexes leave unexplained, capped at
156/// what the allocator holds free. `malloc_trim` returns free pages without
157/// taking their chunks off the free lists, so `AllocatorBytes::free` keeps
158/// counting bytes that are no longer resident. Anonymous memory outside
159/// malloc, such as thread stacks, reads as free; live bytes that are not
160/// resident, and the vector indexes' malloc'd key tables (counted in both
161/// terms), hide free bytes.
162fn resident_free(allocator: AllocatorBytes, rss_anon: u64, mapped_vectors: u64) -> u64 {
163    rss_anon
164        .saturating_sub(allocator.live)
165        .saturating_sub(mapped_vectors)
166        .min(allocator.free)
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    #[test]
174    fn total_sums_every_component() {
175        let r = ComponentResidency {
176            embedder: 1,
177            reranker: 2,
178            vector_writer: 4,
179            vector_reader: 8,
180            lexical: 16,
181            sqlite: 32,
182            allocator_free: 64,
183        };
184        assert_eq!(r.total(), 127);
185    }
186
187    #[test]
188    fn measure_without_models_or_indexes_reports_only_process_wide_parts() {
189        let r = measure(None, None, None, None);
190        assert_eq!(
191            (
192                r.embedder,
193                r.reranker,
194                r.vector_writer,
195                r.vector_reader,
196                r.lexical
197            ),
198            (0, 0, 0, 0, 0)
199        );
200    }
201
202    #[test]
203    fn measure_splits_writer_and_reader_vectors_and_sums_lexical() {
204        let reader = IndexMemory {
205            vectors: 10,
206            lexical: 1,
207        };
208        let writer = IndexMemory {
209            vectors: 100,
210            lexical: 2,
211        };
212        let r = measure(None, None, Some(reader), Some(writer));
213        assert_eq!((r.vector_writer, r.vector_reader, r.lexical), (100, 10, 3));
214    }
215
216    #[test]
217    fn resident_free_is_rss_left_after_live_and_vectors_capped_at_free() {
218        let allocator = |live, free| AllocatorBytes {
219            live,
220            free,
221            system: live + free,
222        };
223        let cases = [
224            ((allocator(100, 500), 900, 50), 500),
225            ((allocator(100, 500), 400, 50), 250),
226            ((allocator(100, 500), 120, 50), 0),
227            ((allocator(100, 0), 900, 50), 0),
228            ((allocator(0, 0), 0, 0), 0),
229        ];
230        for ((allocator, rss_anon, vectors), expected) in cases {
231            assert_eq!(
232                resident_free(allocator, rss_anon, vectors),
233                expected,
234                "{allocator:?} rss_anon {rss_anon} vectors {vectors}"
235            );
236        }
237    }
238
239    #[test]
240    fn rss_anon_is_read_as_bytes_and_missing_reads_zero() {
241        let status = "Name:\tsb\nVmRSS:\t 1653472 kB\nRssAnon:\t 1626960 kB\nThreads:\t24\n";
242        assert_eq!(rss_anon_from_status(status), 1_626_960 * 1024);
243        assert_eq!(rss_anon_from_status("Name:\tsb\nThreads:\t24\n"), 0);
244    }
245
246    #[test]
247    fn sqlite_memory_covers_a_connection_holding_data() {
248        let conn = rusqlite::Connection::open_in_memory().unwrap();
249        conn.execute_batch("CREATE TABLE t(x); INSERT INTO t VALUES (randomblob(1000000));")
250            .unwrap();
251        assert!(sqlite_memory_used() >= 1_000_000);
252        drop(conn);
253    }
254
255    #[cfg(target_env = "gnu")]
256    #[test]
257    fn allocator_live_covers_a_large_allocation() {
258        let block = vec![1u8; 8 << 20];
259        let bytes = allocator_bytes();
260        assert!(bytes.live >= 8 << 20);
261        assert!(bytes.system >= bytes.live);
262        drop(block);
263    }
264}