Module memory_guard 

Process-level RAM guardian with adaptive eviction and hard OOM protection.

Monitors RSS via platform-specific APIs and triggers tiered cache eviction when memory usage exceeds configurable thresholds (default: 5% of system RAM). At critical levels, performs aggressive eviction and signals background tasks to abort. It never exits the process — recovery is always via eviction.

Structs

MemorySnapshot

Snapshot of current memory state for diagnostics.

Enums

PressureLevel

Functions

abort_requested

Returns true if the guardian has requested background tasks to abort.

current_pressure

Returns the current pressure level as last observed by the guardian thread.

force_purge

Force immediate purge of all caches and jemalloc arenas.

get_rss_bytes

Current process RSS in bytes, or None if unavailable.

get_rss_bytes_for_pid

RSS of an arbitrary process by PID, or None if unavailable/dead.

get_system_ram_bytes

Total physical RAM in bytes, or None if unavailable.

is_under_pressure

Quick, non-allocating memory pressure check for hot loops (scanners, indexers). Reads the cached atomic flag set by the guardian thread — O(1), no syscalls.

jemalloc_purge

Force-purge all jemalloc arenas to return memory to the OS. Uses MALLCTL_ARENAS_ALL (value 4096) which is the jemalloc sentinel for “all arenas”. Logs errors instead of silently swallowing them.

peak_rss_bytes

Recorded peak RSS since process start.

rss_limit_bytes

Returns the RSS limit in bytes based on max_ram_percent config.

start_guard

Start the background memory guardian task (idempotent). Polls every 3s (normal), 1s (under pressure), or up to 15s once RSS has been stably calm (idle backoff). At Critical level, performs aggressive eviction and signals background tasks to abort — never exits the process.