mimalloc

mimalloc is a thin, #![no_std] Rust binding that lets any Rust program replace its default global allocator with Microsoft’s mimalloc — a general-purpose, performance-oriented C allocator — by declaring a single #[global_allocator] static. The crate implements the standard GlobalAlloc trait by forwarding alloc, alloc_zeroed, dealloc, and realloc directly to mimalloc’s aligned FFI entry points, so it adds effectively no overhead of its own on top of the underlying C allocator.

Under the hood, the actual mimalloc C source is vendored as a git submodule inside the companion libmimalloc-sys crate and compiled from source via a build.rs that uses the cc crate, so consumers need a working C compiler (and MSVC/clang-cl users get an automatic C++17 wrapper for mimalloc’s atomics path). Cargo feature flags map onto mimalloc’s own compile-time knobs: secure for guard pages and encrypted free lists, v2/v3 to pick the mimalloc source generation, override to replace the process-wide system allocator (with OS X zone/interpose support), plus debug, no_thp, local_dynamic_tls, and win_direct_tls for platform and diagnostics tuning. An extended feature adds convenience methods for reading the mimalloc version, per-allocation usable size, and JSON-formatted process statistics.

Because it’s a faithful wrapper rather than a reimplementation, mimalloc-for-Rust inherits the upstream C allocator’s performance characteristics — free-list sharding, deferred/thread-local frees, and encrypted-heap security options — while giving Rust code an idiomatic, one-line integration point.

What You Get

• Drop-in GlobalAlloc implementation - implement Rust’s standard allocator trait with a single static MiMalloc declaration, no call-site changes required anywhere else in your code
• Secure mode - opt into guard pages, randomized allocation, and encrypted free lists via the secure feature for roughly a 10% performance cost
• v2/v3 mimalloc source selection - choose between mimalloc’s v2 and v3 C source generations via Cargo features without touching your build scripts
• Allocator override support - the override feature replaces the process-wide system malloc (with Apple zone/interpose handling built in)
• Extended diagnostics API - the extended feature exposes version(), usable_size(), and JSON-formatted stats_json() for runtime introspection
• Nightly Allocator trait support - implements the unstable core::alloc::Allocator trait behind the nightly_allocator_api feature for use with allocator-aware collections

Common Use Cases

• Speeding up allocation-heavy services - swap in mimalloc for a web server or data-processing binary that spends measurable time in malloc/free without touching business logic
• Hardening allocator security - enable secure mode in a service handling untrusted input to get guard pages and encrypted free lists as a defense-in-depth measure
• Overriding the system allocator in embedded/FFI contexts - use the override feature so C libraries linked into a Rust binary also allocate through mimalloc
• Benchmarking allocator impact - toggle the crate on and off (or switch v2/v3) to measure how allocator choice affects a specific workload’s throughput and memory footprint
• Diagnosing memory usage in production - pull stats_json() output via the extended feature to inspect per-process allocation statistics without external tooling

Under The Hood

Architecture The crate is a thin wrapper crate over a C library. src/lib.rs defines a zero-sized MiMalloc struct implementing the standard GlobalAlloc trait from core::alloc, delegating its four required methods (alloc, alloc_zeroed, dealloc, realloc) directly to FFI functions (mi_malloc_aligned, mi_zalloc_aligned, mi_free, mi_realloc_aligned) re-exported from the sibling libmimalloc-sys crate as ffi. Two optional modules extend this surface behind feature flags: extended.rs adds version(), usable_size(), and a StatsJson RAII wrapper around mi_stats_get_json; nightly_allocator_api.rs implements the unstable core::alloc::Allocator trait via a private tag_allocation helper using NonNull<[u8]>/ptr_metadata. The real allocator logic lives entirely in libmimalloc-sys, a separate workspace member that vendors Microsoft’s mimalloc C source as a git submodule (c_src/mimalloc/v2 and v3) and compiles it through a build.rs built on the cc crate. This is a deliberately layered design — a safe, #![no_std] Rust wrapper on top of an FFI-binding-and-build crate on top of vendored C — so the entire public contract for consumers is the four GlobalAlloc methods, and everything else is opt-in extension.

Tech Stack Rust edition 2018 throughout; the wrapper crate (mimalloc) has zero runtime dependencies beyond its own workspace sibling libmimalloc-sys (path dependency) and an optional cty 0.2 for the extended feature’s C-type bindings. libmimalloc-sys vendors mimalloc’s C11 source via git submodule and compiles it with the cc 1.2 build-dependency, requiring a C compiler on every target and C++17 on MSVC/clang-cl (handled via an auto-generated .cc wrapper file). Nine Cargo feature flags (secure, override, debug, debug_in_debug, local_dynamic_tls, win_direct_tls, no_thp, v2, extended) map onto build.rs branches that set matching C preprocessor defines (MI_SECURE, MI_MALLOC_OVERRIDE, MI_DEBUG, MI_NO_THP, etc). The workspace also carries a libmimalloc-sys-test crate that exercises the raw FFI bindings directly, and a test-override-with-dylib crate validating the override feature end to end. CI runs a full matrix (ubuntu/macos/windows, every meaningful feature combination) plus a dedicated nightly job running cargo rustdoc -D warnings to catch broken documentation links.

Code Quality Testing is minimal but targeted at the boundary the wrapper crate actually controls: src/lib.rs carries six inline unit tests covering small and large (1MB) allocation, zeroed allocation, and reallocation paths; extended.rs adds three more for version(), usable_size(), and JSON stats. There’s no broad integration suite inside the wrapper crate itself — deeper correctness coverage instead comes from the separate libmimalloc-sys-test crate exercising the raw C FFI, and from mimalloc’s own upstream C test suite. Given the crate implements an inherently unsafe trait, most public functions are unsafe fn with explicit safety-contract doc comments rather than Result-based error handling; the nightly Allocator trait implementation does return AllocError per that trait’s own contract. CI enforces cargo fmt --all -- --check; a Clippy step exists in the workflow file but is currently commented out, so lint enforcement is not fully active.

API Design The entire integration surface is one line — #[global_allocator] static GLOBAL: MiMalloc = MiMalloc; — making this about as low-friction a “drop-in” allocator swap as Rust allows, with no required runtime configuration. Everything beyond that default is opt-in through Cargo features rather than runtime flags (secure mode, v2 vs v3 mimalloc source, override, extended diagnostics), which keeps the default build minimal while still exposing power-user knobs like JSON stats and per-pointer usable-size introspection to anyone who opts into extended. Documentation is concise and consistent — the README and the crate-level doc comment share the same four-line usage example — and a dedicated CI job specifically checks for dead documentation links via cargo rustdoc -D warnings. It isn’t inventing new allocator concepts of its own; its value is a faithful, ergonomic Rust binding to an existing, well-regarded C allocator.