second-brain-core 0.13.5

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
//! Where a process's anonymous resident memory goes, per component: model
//! sessions, vector and lexical indexes, SQLite, and what the allocator holds
//! free. Every figure is per process, like the RSS it is compared against.

use serde::Serialize;

use crate::embedding::Embedder;
use crate::retrieval::Reranker;

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct AllocatorBytes {
    /// Arena chunks handed out plus live mmapped allocations.
    pub live: u64,
    /// Bytes held free inside arenas, including chunks whose pages
    /// `release_free_heap` has handed back to the kernel.
    pub free: u64,
    /// Everything the allocator has taken from the kernel.
    pub system: u64,
}

/// glibc's figures summed over every arena, which covers Rust and the C/C++
/// libraries that allocate through malloc (onnxruntime, SQLite); usearch maps
/// its tapes itself, so `IndexMemory` counts those. Zeros on other allocators.
#[cfg(target_env = "gnu")]
pub fn allocator_bytes() -> AllocatorBytes {
    // SAFETY: mallinfo2 takes no arguments, reads only allocator state behind
    // its own locks, and returns a plain value type.
    let info = unsafe { libc::mallinfo2() };
    let mmapped = info.hblkhd as u64;
    AllocatorBytes {
        live: info.uordblks as u64 + mmapped,
        free: info.fordblks as u64,
        system: info.arena as u64 + mmapped,
    }
}

#[cfg(not(target_env = "gnu"))]
pub fn allocator_bytes() -> AllocatorBytes {
    AllocatorBytes::default()
}

/// Hands the pages of free chunks in every arena back to the kernel. Freed
/// memory otherwise stays charged to the process after a large pass, because
/// glibc only returns an arena's top chunk on free. A no-op on other
/// allocators.
#[cfg(target_env = "gnu")]
pub fn release_free_heap() {
    // SAFETY: malloc_trim takes the allocator's own locks and touches only
    // free chunks.
    unsafe { libc::malloc_trim(0) };
}

#[cfg(not(target_env = "gnu"))]
pub fn release_free_heap() {}

/// The process's anonymous resident set, the figure a cgroup memory limit is
/// enforced against; 0 where `/proc/self/status` is unreadable.
pub fn rss_anon_bytes() -> u64 {
    std::fs::read_to_string("/proc/self/status").map_or(0, |status| rss_anon_from_status(&status))
}

fn rss_anon_from_status(status: &str) -> u64 {
    status
        .lines()
        .find_map(|line| line.strip_prefix("RssAnon:"))
        .map_or(0, |rest| {
            rest.trim()
                .trim_end_matches("kB")
                .trim()
                .parse::<u64>()
                .unwrap_or(0)
                * 1024
        })
}

/// Bytes SQLite has allocated across every connection in the process, page
/// caches and statement caches included.
pub fn sqlite_memory_used() -> u64 {
    let mut current: i64 = 0;
    let mut highwater: i64 = 0;
    // SAFETY: sqlite3_status64 only writes the two out-params, and the
    // bundled build keeps memory statistics on (SQLITE_DEFAULT_MEMSTATUS=1).
    let rc = unsafe {
        rusqlite::ffi::sqlite3_status64(
            rusqlite::ffi::SQLITE_STATUS_MEMORY_USED,
            &mut current,
            &mut highwater,
            0,
        )
    };
    if rc == rusqlite::ffi::SQLITE_OK {
        current.max(0) as u64
    } else {
        0
    }
}

/// Anonymous memory one `Indexes` holds. Mapped files are file-backed and so
/// not counted here.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
pub struct IndexMemory {
    pub vectors: u64,
    pub lexical: u64,
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
pub struct ComponentResidency {
    pub embedder: u64,
    pub reranker: u64,
    pub vector_writer: u64,
    pub vector_reader: u64,
    pub lexical: u64,
    pub sqlite: u64,
    pub allocator_free: u64,
}

impl ComponentResidency {
    pub fn total(&self) -> u64 {
        self.embedder
            + self.reranker
            + self.vector_writer
            + self.vector_reader
            + self.lexical
            + self.sqlite
            + self.allocator_free
    }
}

/// `writer` is `None` when no writer `Indexes` is open, as when the daemon's
/// drain loop has released its copy.
pub fn measure(
    embedder: Option<&Embedder>,
    reranker: Option<&Reranker>,
    reader: Option<IndexMemory>,
    writer: Option<IndexMemory>,
) -> ComponentResidency {
    let reader = reader.unwrap_or_default();
    let writer = writer.unwrap_or_default();
    ComponentResidency {
        embedder: embedder.map_or(0, Embedder::resident_bytes),
        reranker: reranker.map_or(0, Reranker::resident_bytes),
        vector_writer: writer.vectors,
        vector_reader: reader.vectors,
        lexical: reader.lexical + writer.lexical,
        sqlite: sqlite_memory_used(),
        allocator_free: resident_free(
            allocator_bytes(),
            rss_anon_bytes(),
            reader.vectors + writer.vectors,
        ),
    }
}

/// An estimate of the free allocator bytes still resident: the anonymous RSS
/// that live allocations and the vector indexes leave unexplained, capped at
/// what the allocator holds free. `malloc_trim` returns free pages without
/// taking their chunks off the free lists, so `AllocatorBytes::free` keeps
/// counting bytes that are no longer resident. Anonymous memory outside
/// malloc, such as thread stacks, reads as free; live bytes that are not
/// resident, and the vector indexes' malloc'd key tables (counted in both
/// terms), hide free bytes.
fn resident_free(allocator: AllocatorBytes, rss_anon: u64, mapped_vectors: u64) -> u64 {
    rss_anon
        .saturating_sub(allocator.live)
        .saturating_sub(mapped_vectors)
        .min(allocator.free)
}

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

    #[test]
    fn total_sums_every_component() {
        let r = ComponentResidency {
            embedder: 1,
            reranker: 2,
            vector_writer: 4,
            vector_reader: 8,
            lexical: 16,
            sqlite: 32,
            allocator_free: 64,
        };
        assert_eq!(r.total(), 127);
    }

    #[test]
    fn measure_without_models_or_indexes_reports_only_process_wide_parts() {
        let r = measure(None, None, None, None);
        assert_eq!(
            (
                r.embedder,
                r.reranker,
                r.vector_writer,
                r.vector_reader,
                r.lexical
            ),
            (0, 0, 0, 0, 0)
        );
    }

    #[test]
    fn measure_splits_writer_and_reader_vectors_and_sums_lexical() {
        let reader = IndexMemory {
            vectors: 10,
            lexical: 1,
        };
        let writer = IndexMemory {
            vectors: 100,
            lexical: 2,
        };
        let r = measure(None, None, Some(reader), Some(writer));
        assert_eq!((r.vector_writer, r.vector_reader, r.lexical), (100, 10, 3));
    }

    #[test]
    fn resident_free_is_rss_left_after_live_and_vectors_capped_at_free() {
        let allocator = |live, free| AllocatorBytes {
            live,
            free,
            system: live + free,
        };
        let cases = [
            ((allocator(100, 500), 900, 50), 500),
            ((allocator(100, 500), 400, 50), 250),
            ((allocator(100, 500), 120, 50), 0),
            ((allocator(100, 0), 900, 50), 0),
            ((allocator(0, 0), 0, 0), 0),
        ];
        for ((allocator, rss_anon, vectors), expected) in cases {
            assert_eq!(
                resident_free(allocator, rss_anon, vectors),
                expected,
                "{allocator:?} rss_anon {rss_anon} vectors {vectors}"
            );
        }
    }

    #[test]
    fn rss_anon_is_read_as_bytes_and_missing_reads_zero() {
        let status = "Name:\tsb\nVmRSS:\t 1653472 kB\nRssAnon:\t 1626960 kB\nThreads:\t24\n";
        assert_eq!(rss_anon_from_status(status), 1_626_960 * 1024);
        assert_eq!(rss_anon_from_status("Name:\tsb\nThreads:\t24\n"), 0);
    }

    #[test]
    fn sqlite_memory_covers_a_connection_holding_data() {
        let conn = rusqlite::Connection::open_in_memory().unwrap();
        conn.execute_batch("CREATE TABLE t(x); INSERT INTO t VALUES (randomblob(1000000));")
            .unwrap();
        assert!(sqlite_memory_used() >= 1_000_000);
        drop(conn);
    }

    #[cfg(target_env = "gnu")]
    #[test]
    fn allocator_live_covers_a_large_allocation() {
        let block = vec![1u8; 8 << 20];
        let bytes = allocator_bytes();
        assert!(bytes.live >= 8 << 20);
        assert!(bytes.system >= bytes.live);
        drop(block);
    }
}