Crate mimalloc_pprof

Expand description

Rust global allocator support for the in-tree mimalloc build.

use mimalloc_pprof::{prof, MiMalloc};
#[global_allocator] static ALLOCATOR: MiMalloc = MiMalloc;
prof::start(512 * 1024);
prof::dump_file(std::path::Path::new("heap.prof"))?;

Since 0.12.0 every observability subsystem is opt-in and the default build is a plain fast allocator whose malloc/free fast path is byte-identical to upstream mimalloc. Enable what you need with cargo features – pprof (the example above), memory-events, diagnostics, dhat (implies memory-events), owner-gate, or full for all of them:

mimalloc-pprof = { version = "1", features = ["pprof"] }

The whole API compiles and links in every configuration: a subsystem that was not built in simply reports itself off (prof::start returns false, heap_dump_json returns None, and so on), so no #[cfg] is needed at the call site. Cargo features are additive and unified across the dependency graph, so a dependency that enables one enables it for your build too – cargo tree -e features shows who.

See the README’s Rust integration guide for frame-pointer and line-table build flags. Open the resulting profile with pprof -http=: app.exe heap.prof.

Modules§

dhat: Exact DHAT v2 heap/lifetime profiling controls.
memory_events: Opt-in allocation-change accounting and callbacks (include/mimalloc/memory-events.h).
options: mimalloc’s mi_option_* settings: the runtime knobs behind every MIMALLOC_* environment variable.
prof: Safe controls for mimalloc’s sampled heap profiler.
stats: The allocator’s own exact statistics, as opposed to the sampled numbers crate::prof::stats reports.
sys: Raw bindings to the in-tree mimalloc static amalgamation.

Structs§

IdlePark: Returned by park_while_idle; ends the park when dropped.
MiMalloc: A #[global_allocator] implementation backed by mimalloc.
ProfConfig: Ergonomic, Rust-facing sibling of mi_prof_config_t (include/mimalloc/profile.h) for enable_heap_profiling_with.
PurgeAllReport: What a purge_all / purge_all_ex call returned to the OS and which threads it could not reach (issue #366). Mirrors mi_purge_all_report_t.
PurgeFlags: Flags for purge_all_ex (issue #366).

Enums§

DumpFormat: Output format for ProfConfig::dump_at_exit.
ProfConfigMode: How ProfConfig fields interact with the profiler’s environment variables and mi_option_* settings.
PurgeStatus: The outcome of a purge_all / purge_all_ex call (issue #366).

Constants§

HEAP_DUMP_JSON_DEFAULT_WAIT_MS: Default owner-acquisition deadline used by heap_dump_json.
PURGE_ALL_DEFAULT_WAIT_MS: The wait_ms C’s mi_purge_all passes to mi_purge_all_ex, and what purge_all uses.

Functions§

enable_heap_profiling: Turn on sampled heap profiling at the default sample rate.
enable_heap_profiling_with: Turn on sampled heap profiling using a struct-based configuration.
expand^⚠: Try to grow an allocation in place, without moving it.
heap_dump_json: Live per-heap -> per-page -> (optional) per-block JSON snapshot of the current subprocess (issue #269, Bun parity P4). Backs Bun’s shipped bun:jsc heapStats({dump:true|"blocks"}).mimallocDump; see src/heap-dump.c for the JSON shape ({"heaps":[{"seq":N,"pages":[{"id","block_size","used","reserved","thread_id"}], "blocks":[[id,size],...]}]}, blocks present only when include_blocks).
heap_dump_json_ex: Live heap JSON capture with an explicit owner-acquisition deadline.
heap_snapshot_to_file: Write a binary heap snapshot to path (issue #338, Bun parity).
on_thread_idle: Tell mimalloc this thread is idle (issue #272, Bun parity P7a).
park_while_idle: Guard form of on_thread_idle for a thread that is about to BLOCK: hands this thread’s heaps to the background scavenger, which does the idle work above while this thread sits in the kernel, and takes them back on drop.
purge_all: Process-wide eager purge from any thread (issue #366), with the C default of a 100 ms owner-acquisition wait: mi_purge_all(force), but with the report kept.
purge_all_ex: Process-wide eager purge from any thread (issue #366): the full form of purge_all.
purge_holes_report: Print, per size class, what hole purging leaves behind (issue #272, Bun parity P7b).
purge_holes_stats: What page hole purging has reclaimed, process wide (issue #272, Bun parity P7b).
recalloc^⚠: Grow or shrink an allocation to count * size bytes, zeroing any newly-exposed tail.
rezalloc^⚠: Grow or shrink an allocation, zeroing any newly-exposed tail.
scavenger_stop: Stop the background scavenger thread (issue #272).
unwrapped_free^⚠: Free a pointer returned by unwrapped_malloc or unwrapped_realloc.
unwrapped_malloc^⚠: Allocate size bytes from mimalloc’s raw-OS-layer “unwrapped” path.
unwrapped_realloc^⚠: Resize a pointer returned by unwrapped_malloc or unwrapped_realloc.
usable_size^⚠: Bytes actually available in an allocation, which may exceed what was requested.