Expand description
Allocator tuning for the leviath binary.
This crate holds exactly one capability: telling mimalloc to purge freed
memory at free time instead of deferring it. It exists as a separate
crate because the call is an unsafe C FFI invocation and the rest of
the workspace compiles under unsafe_code = "forbid"; the policy is that
OS-level unsafe lives in small audited places, and this crate is one.
§Why purge at free time
mimalloc’s default purge delay (10ms) is not a timer. It is a minimum age checked only when the owning thread next touches the allocator. A daemon worker thread that goes idle right after a burst therefore never returns its freed pages to the OS: the process sits tens to hundreds of MB above its idle baseline holding pages that contain nothing. Measured on the daemon: byte-for-byte flat across 10 idle minutes, then released by the next moment of allocator activity.
With a delay of zero the free that empties a span performs the OS
handoff itself, so nothing ever waits on future activity. The cost is a
syscall per emptied span (paid at run-reap, off every latency path) and
re-faulting pages when a later burst reallocates (milliseconds per burst
ramp, measured indistinguishable end to end on the benchmark suite). The
win is a daemon whose resident memory actually returns to its baseline
when work finishes.
A user who exports MIMALLOC_PURGE_DELAY themselves has made a choice,
and use_purge_at_free_unless_overridden leaves it alone.
§Audit note (the single unsafe call)
mi_option_set(option, value) writes a long into mimalloc’s static
options table. It allocates nothing, frees nothing, holds no lock, and is
documented callable at any time; subsequent purge decisions read the
stored value. The option index for mi_option_purge_delay is 15 in
the mimalloc v2 header vendored by libmimalloc-sys 0.1.49, anchored on
both sides by constants that crate does bind: mi_option_eager_commit_delay = 14 and mi_option_use_numa_nodes = 16 (the crate predates the
reset_delay to purge_delay rename and simply does not name index 15).
The test below asserts the round trip through mi_option_get, so a
vendored-header reordering would fail loudly rather than silently tune
the wrong knob.
Constants§
- PURGE_
DELAY_ VAR - The environment variable mimalloc itself reads for this option; a user who set it keeps their value.
Functions§
- use_
purge_ at_ free_ unless_ overridden - Without the mimalloc feature there is nothing to tune: builds on the system allocator keep their platform defaults.