Struct MemoryGuard 

pub struct MemoryGuard { /* private fields */ }

Available on crate feature memory only.

Cgroup-aware memory tracking with backpressure signals.

Tracks application-level memory usage (not process RSS) and provides fast atomic checks for the hot path. Designed for data pipeline services where incoming data must be rejected (503) before hitting the container memory limit.

Usage

use hyperi_rustlib::memory::{MemoryGuard, MemoryGuardConfig};

let guard = MemoryGuard::new(MemoryGuardConfig::default());

// On data arrival -- check before accepting
let payload_len = 1024u64;
if !guard.try_reserve(payload_len) {
    // return 503 -- backpressure
}

// After data is flushed/sent
guard.release(payload_len);

// Fast hot-path check
if guard.under_pressure() {
    // return 503
}

Implementations

impl MemoryGuard

pub fn new(config: MemoryGuardConfig) -> Self

Create a new memory guard.

If config.limit_bytes is 0, auto-detects from cgroup (K8s) or system memory, then applies cgroup_headroom factor to leave room for process overhead.

pub fn try_reserve(&self, bytes: u64) -> bool

Try to reserve bytes. Returns false if over the limit (backpressure).

With a registered set_heap_source, this is a projected-admission check against the true total heap (heap() + bytes <= limit) and does NOT mutate the reservation counter – the allocator already accounts the bytes once they are allocated, and frees them on drop, so no release is needed. Without a source it is the classic atomic check-and-add on the per-batch counter (rolled back if it would exceed the limit).

pub fn add_bytes(&self, bytes: u64)

Add bytes without checking the limit (for tracking only). Use when data is already accepted and you just need to track it.

pub fn release(&self, bytes: u64)

Release bytes after data is flushed/sent/dropped.

Uses saturating subtraction to prevent underflow wrapping.

pub fn under_pressure(&self) -> bool

Fast hot-path pressure check.

With a registered set_heap_source, computes live from the true heap (one atomic load + compare); otherwise reads the cached flag maintained by try_reserve/add_bytes/release.

pub fn pressure(&self) -> MemoryPressure

Current pressure level.

pub fn pressure_ratio(&self) -> f64

Current usage as fraction of limit (0.0 - 1.0+).

pub fn current_bytes(&self) -> u64

Current memory usage in bytes.

Returns the true total live heap when a set_heap_source is registered, otherwise the sum of outstanding per-batch reservations.

pub fn limit_bytes(&self) -> u64

Configured memory limit in bytes.