Module memory 

Memory tracking for the keyspace.

Provides byte-level accounting of memory used by entries. Updated on every mutation so the engine can enforce memory limits and report stats without scanning the entire keyspace.

Platform notes

Overhead constants are empirical estimates for 64-bit platforms (x86-64, aarch64). On 32-bit systems these would be smaller; the effect is that we’d overestimate memory usage, which triggers eviction earlier than necessary but doesn’t cause correctness issues.

The constants assume Rust’s standard library allocator. Custom allocators (jemalloc, mimalloc) may have different per-allocation overhead.

Safety margin

Because overhead constants are estimates and allocator fragmentation is unpredictable, we apply a safety margin when enforcing memory limits. The effective limit is set to MEMORY_SAFETY_MARGIN_PERCENT% of the configured max, reserving headroom so the process doesn’t OOM before eviction has a chance to kick in.

Structs

MemoryTracker

Tracks memory usage for a single keyspace.

Constants

LAZY_FREE_THRESHOLD

Element count threshold below which values are dropped inline rather than sent to the background drop thread. Strings are always inline (Bytes::drop is O(1)), but collections with more than this many elements get deferred.

MEMORY_SAFETY_MARGIN_PERCENT

Percentage of the configured max_memory that we actually use as the effective write limit. The remaining headroom absorbs allocator overhead, internal fragmentation, and estimation error in our per-entry constants.

Functions

effective_limit

Computes the effective memory limit after applying the safety margin.

entry_size

Estimates the total memory footprint of a single entry.

is_large_value

Returns true if dropping this value is expensive enough to justify sending it to the background drop thread.

value_size

Returns the byte size of a value’s payload.