second-brain-api 0.13.1

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
//! The glibc arena cap the daemon starts under, and allocator residency
//! accounting for `/v1/status`.
//!
//! The daemon runs under a hard `MemoryMax` and has twice been cgroup-OOM-
//! killed on anonymous RSS with no retained structure anywhere near the size
//! of the resident set: the store holds ~12k memories (~18 MB of embeddings)
//! while RSS sits above 1.7 GB. Anonymous RSS alone cannot say whether those
//! bytes are live data or memory the allocator has taken from the kernel and
//! not given back, and that distinction picks the remedy: freed-but-retained
//! bytes point at glibc's per-thread arenas, whose non-main arenas only ever
//! trim their top chunk, while live bytes point at a working set that simply
//! does not fit the cap.
//!
//! `mallinfo2` aggregates every arena, and glibc is where both the Rust side
//! and the C/C++ libraries that use malloc (onnxruntime, sqlite) get their
//! memory; usearch maps its own tapes, which the component report counts.

use std::path::Path;
use std::sync::{Mutex, PoisonError};

use second_brain_core::residency::{self, ComponentResidency, IndexMemory};

use crate::AppState;

pub const ARENA_CAP: i32 = 2;

/// Caps glibc at `ARENA_CAP` malloc arenas unless `MALLOC_ARENA_MAX` is set.
/// With an arena per thread, anonymous RSS ratcheted with every recall until
/// the Pi's cgroup killed the daemon. Threads that already allocated keep
/// their arena, so call it before any thread starts.
pub fn cap_arenas() {
    if std::env::var_os("MALLOC_ARENA_MAX").is_some() {
        return;
    }
    set_arena_max(ARENA_CAP);
}

#[cfg(target_env = "gnu")]
fn set_arena_max(arenas: i32) {
    if unsafe { libc::mallopt(libc::M_ARENA_MAX, arenas) } == 0 {
        eprintln!("cannot cap glibc at {arenas} malloc arenas");
    }
}

#[cfg(not(target_env = "gnu"))]
fn set_arena_max(_arenas: i32) {}

/// glibc's non-main arenas are 64 MiB mmaps aligned to their own size, so an
/// anonymous mapping matching both is an arena rather than an ordinary large
/// allocation. Counting them turns "how fragmented is this" into a number that
/// can be watched over time.
const ARENA_BYTES: u64 = 64 * 1024 * 1024;

#[derive(Debug, Clone, Copy, Default, serde::Serialize)]
pub struct HeapStats {
    /// In-use bytes: arena chunks handed out, plus live mmapped allocations.
    pub live_bytes: u64,
    /// Bytes the allocator holds free inside arenas, resident or not; the
    /// `allocator_free` component counts only the resident part.
    pub free_bytes: u64,
    /// Total bytes the allocator has taken from the kernel.
    pub system_bytes: u64,
    /// Anonymous resident set, the figure the cgroup limit is enforced against.
    pub rss_anon_bytes: u64,
    /// Count of mappings carrying glibc's non-main arena signature.
    pub arena_mappings: usize,
}

/// `HeapStats` plus where the anonymous resident set goes, per component.
#[derive(Debug, Clone, Copy, serde::Serialize)]
pub struct HeapReport {
    #[serde(flatten)]
    pub stats: HeapStats,
    pub components: ComponentResidency,
    /// `rss_anon_bytes` minus the components' total; negative when a
    /// component counts bytes that are not resident.
    pub unattributed_bytes: i64,
}

static INDEX_WRITER: Mutex<Option<IndexMemory>> = Mutex::new(None);

/// What the drain loop's writer `Indexes` holds, or `None` while it is
/// released. Process-wide, like the RSS it is compared against.
pub fn record_index_writer(memory: Option<IndexMemory>) {
    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner) = memory;
}

fn recorded_index_writer() -> Option<IndexMemory> {
    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner)
}

pub fn component_residency(state: &AppState) -> ComponentResidency {
    let reader = state.indexes.as_ref().map(|indexes| {
        indexes
            .read()
            .unwrap_or_else(PoisonError::into_inner)
            .memory()
    });
    residency::measure(
        state.embedder.as_deref(),
        state.reranker.as_deref(),
        reader,
        recorded_index_writer(),
    )
}

/// Takes the reader index lock briefly, so call it off the async runtime.
pub fn heap_report(state: &AppState) -> HeapReport {
    let stats = heap_stats();
    let components = component_residency(state);
    HeapReport {
        stats,
        components,
        unattributed_bytes: stats.rss_anon_bytes as i64 - components.total() as i64,
    }
}

pub fn arena_mappings(maps_path: &Path) -> usize {
    let Ok(maps) = std::fs::read_to_string(maps_path) else {
        return 0;
    };
    arena_mappings_from_maps(&maps)
}

fn arena_mappings_from_maps(maps: &str) -> usize {
    maps.lines()
        .filter(|line| {
            let mut fields = line.split_whitespace();
            let Some(range) = fields.next() else {
                return false;
            };
            // A named mapping is a file, a stack or the main heap; only
            // unnamed ones can be a non-main arena.
            if fields.clone().count() >= 5 {
                return false;
            }
            let Some((start, end)) = range.split_once('-') else {
                return false;
            };
            let (Ok(start), Ok(end)) =
                (u64::from_str_radix(start, 16), u64::from_str_radix(end, 16))
            else {
                return false;
            };
            end - start == ARENA_BYTES && start % ARENA_BYTES == 0
        })
        .count()
}

pub fn heap_stats() -> HeapStats {
    let allocator = residency::allocator_bytes();
    HeapStats {
        live_bytes: allocator.live,
        free_bytes: allocator.free,
        system_bytes: allocator.system,
        rss_anon_bytes: residency::rss_anon_bytes(),
        arena_mappings: arena_mappings(Path::new("/proc/self/maps")),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn only_unnamed_64mib_aligned_mappings_count_as_arenas() {
        let maps = concat!(
            // An arena: unnamed, exactly 64 MiB, aligned to 64 MiB.
            "7f0004000000-7f0008000000 rw-p 00000000 00:00 0\n",
            // Same size and alignment but file-backed, so not an arena.
            "7f0010000000-7f0014000000 rw-p 00000000 08:01 1234 /lib/libc.so.6\n",
            // Unnamed and 64 MiB but not 64 MiB-aligned.
            "7f0018100000-7f001c100000 rw-p 00000000 00:00 0\n",
            // Unnamed and aligned but a 2 MiB thread stack.
            "7f0020000000-7f0020200000 rw-p 00000000 00:00 0\n",
            "555500000000-555500100000 rw-p 00000000 00:00 0 [heap]\n",
        );
        assert_eq!(arena_mappings_from_maps(maps), 1);
    }
}