aligned-vmem

Cross-platform aligned anonymous virtual memory — reserve a span whose base is aligned to an arbitrary power of two, commit/decommit its pages, release it. Directly through the OS, no file-mapping machinery, zero dependencies, 100 % Rust (no C / C++ libraries pulled in — the OS syscalls are declared locally through extern "system" / extern "C", the same way std itself links kernel32 / libc), miri-friendly.

[dependencies]
aligned-vmem = "0.2"

use aligned_vmem::{reserve_aligned, release};

// Reserve 4 MiB aligned to 4 MiB — e.g. one allocator segment.
let span = 4 * 1024 * 1024;
let r = reserve_aligned(span, span).expect("OOM");
let base = r.as_ptr();
assert_eq!(base.addr() % span, 0);

// SAFETY: base is valid for r.len() bytes (except decommitted ranges), owned exclusively.
unsafe { base.write(0xAB); assert_eq!(base.read(), 0xAB); }

// RAII release on drop — or take the parts for self-hosted manual release:
let (raw, raw_len, raw_align) = r.into_parts();
unsafe { release(raw, raw_len, raw_align) };

Runnable form: tests/readme_example.rs.

Reservation ownership: Reservation is a single-owner handle over its whole span with no built-in sub-span/re-derivation API. Sub-allocation on top of this crate is expected via raw pointer arithmetic within the reservation's bounds, done by the consumer.

What it does

Every fallible entry point has an infallible Option/bool counterpart that discards the cause. Optional features: lazy-commit (incremental commit: reserve_aligned_lazy + commit_range, and the LazyReservation watermark type above; the alloc-lazy-commit name is kept as a compat alias for one release and will be removed in 0.3.0/1.0.0 — migrate to lazy-commit now), huge-pages (reserve_aligned_huge — MAP_HUGETLB / MEM_LARGE_PAGES, best-effort with fallback — on Linux and Android, size and align must both additionally be multiples of the huge-page size (2 MiB), or the request is rejected up front; on Windows, large pages (MEM_LARGE_PAGES) are only ever requested and possibly granted via the single-call fast path; the two-call path never requests large pages, so is_huge() is always false for a reservation that takes it; otherwise the request falls back to ordinary pages — see the function's own rustdoc for the full technical explanation; use Reservation::is_huge to detect whether a reservation actually got large/huge pages on either platform), and fault-injection — a PUBLIC, process-global, opt-in Cargo feature with armed hooks on TWO real syscall paths: fault_injection::arm_fail_next / arm_fail_at on the REAL try_commit_range syscall path, and (since task #1219) fault_injection::arm_fail_next_decommit on the REAL decommit dispatch path (try_decommit / Reservation::try_decommit) — DISTINCT from the mock backend: it changes nothing about which backend runs, it only forces a specific real commit or decommit call to report failure, for a consumer that needs the genuine OS backend under test. The mock backend (recording call log + fail_next_reserve / fail_next_commit fault injection for deterministic OOM-path tests on any target — replaces the commit/decommit/recommit backend with a stub) is enabled via the aligned_vmem_mock cfg flag (RUSTFLAGS="--cfg aligned_vmem_mock" cargo test ...), following the same pattern as this repo's cfg(loom)/cfg(kani) flags. A --cfg flag cannot be silently unified into a build by another crate downstream — exactly why it was converted (task #962).

Migrating to 0.2.0 (breaking changes)

• Reservation's seven OS-state mutators now take &mut self: decommit, try_decommit, decommit_lazy, recommit, try_recommit, commit_range, try_commit_range. Bind the reservation as let mut r = reserve_aligned(...) at the call site. If a Reservation is held behind a shared reference (inside a struct whose method takes &self, inside an Rc, or captured by a Fn closure), that pattern no longer compiles and needs RefCell/Mutex (single-threaded / cross-thread respectively) or a &mut self method instead. This closes a real soundness gap: a leaked &Reservation used to let 100%-safe code decommit or recommit memory behind a LazyReservation's watermark without it knowing.
• reserve_aligned_lazy / try_reserve_aligned_lazy now return LazyReservation, not Reservation. A caller that keeps its own commit bookkeeping and wants the plain Reservation back calls .into_reservation() on the result.

Backends: mmap/munmap/madvise on Unix, VirtualAlloc/VirtualFree(MEM_DECOMMIT/MEM_RELEASE) on Windows, std::alloc fallback under miri (so consumers stay miri-testable).

Why not region / memmap2 / mmap-rs?

Those are excellent for file mappings and page-protection changes. aligned-vmem does one different, narrow thing: hand you an anonymous span aligned to a power of two you choose plus page-granular decommit/recommit. That is exactly what an allocator / arena / slab needs ("give me a 4 MiB-aligned 4 MiB span, let me hand pages back to the OS, keep the address reservation"), and what the file-mapping crates don't directly offer.

Alignment contract

• align must be a power of two >= PAGE (4 KiB).
• size must be a non-zero multiple of PAGE.
• decommit/decommit_lazy offsets must be multiples of the runtime page size (page_size()).
• recommit/commit_range offsets must be multiples of the runtime page size (page_size()).
• Lazy reservations (feature lazy-commit): reserve_aligned_lazy's size and initial_commit must BOTH be multiples of the runtime page size (page_size()), not just PAGE. This is required because commit_range operates on whole runtime pages, and a size not aligned to page_size() would create an unwritable tail that cannot be committed via the public API.
• reserve_aligned (eager) does NOT enforce the page_size() half of this contract, unlike the lazy constructor above. A size that is a PAGE multiple but not also a page_size() multiple is accepted — on a host where those differ (e.g. Apple Silicon macOS, 16 KiB pages), the resulting reservation's span can never be fully decommitted: decommit(0, size) on it is a debug-build panic and a silent permanent no-op in release. Round size up to a page_size() multiple yourself if it is not already one.

Note: decommit/decommit_lazy and recommit/commit_range validate the same granularity, but respond differently to a violated range — this asymmetry is intentional. decommit/decommit_lazy have an infallible () return with no write-permitting sentinel to misuse, so silently skipping on a violated range is safe; recommit/commit_range's boolean/Result return means a silent no-op could hide a real OOM, so they reject violations instead. Since task #1051 the eager decommit additionally trips a debug_assert! on a violated range in DEBUG builds (zero cost — and still a silent no-op — in release); decommit_lazy silently skips on every profile, and try_decommit reports the violation as Err on every profile.

• On Linux and Android with huge-pages enabled, reserve_aligned_huge/ try_reserve_aligned_huge additionally require size and align to both be multiples of the huge-page size (2 MiB) — see that function's own rustdoc.

Most violations return None / false / Err(_) — never a panic, so this is safe to call from inside a GlobalAlloc::alloc body: reserve_aligned and its siblings, and decommit_lazy (which silently no-ops on a violated range on every profile, an intentional asymmetry with recommit/commit_range below — since the () return has no write-permitting sentinel to misuse, silently skipping is safe, whereas recommit/commit_range's boolean/Result return previously clamped a contract violation to the same value a genuine success reports, which crashed an in-repo consumer — see recommit's own rustdoc). The eager decommit is the one debug-build exception: since task #1051 a violated range trips its debug_assert! there (release builds keep the silent no-op; try_decommit reports the violation as Err on every profile).

Behavior change: recommit and commit_range (and their fallible try_* forms) now reject, rather than silently accept, a violated offset range (start > end or misaligned) — they still don't panic, but callers relying on the old silent-no-op shape should check the return value.

Two panic exceptions: Reservation::from_raw_parts (an unsafe fn for adopting a foreign OS reservation, not part of the ordinary reservation flow) panics immediately on a contract-violating align/reservation_len pair; and release panics on a contract-violating (reservation_len, align) pair (a null pointer remains a documented no-op) — see release's own rustdoc # Panics section for the full detail. A third, debug-only panic surface exists: decommit's task-#1051 debug_assert! on a violated range, compiled out of release builds (see above).

Platform caveats

The table entry above (decommit/recommit) hides six platform and failure-mode divergences worth knowing before you rely on it — see each function's own rustdoc for the full technical explanation:

• Windows: a write before recommit is a hard crash, not a soft re-fault. MEM_DECOMMIT genuinely unmaps the pages, so writing into [base+start, base+end) before calling recommit raises a STATUS_ACCESS_VIOLATION on Windows. On Linux and Android, MADV_DONTNEED keeps the mapping resident and transparently re-faults a fresh zero page on the next write, so code that is safe on Linux or Android can crash on Windows. This exact divergence has already crashed an in-repo consumer — see https://github.com/PHPCraftdream/sefer-alloc/blob/main/docs/CORRECTNESS_OPEN_ITEMS.md item 6 for the incident record.
• Lazy reservations on Windows: only the committed prefix is writable. reserve_aligned_lazy returns a LazyReservation, which tracks the committed prefix as a watermark (LazyReservation::committed_len()); on the real Windows backend only the initial_commit bytes are actually committed at reservation time (see lazy_commit_is_honored() — Unix, miri, and the mock backend commit the whole span up front regardless of what was requested, so this distinction is Windows-only in practice). The tail [committed_len(), len()) must be committed via LazyReservation::ensure_committed(len) before it becomes writable — this call is idempotent and monotone, so it is safe to call before every write without separately tracking what was already committed. Writing to the uncommitted tail raises a STATUS_ACCESS_VIOLATION. This is different from eager reservations (reserve_aligned), where the entire len() span is writable from the start. A caller that keeps its own commit bookkeeping instead of using LazyReservation's watermark can call .into_reservation() and drive commit_range/try_commit_range directly on the raw Reservation.
• Huge pages: decommit's behavior is platform- AND range-dependent, not a blanket no-op. When a reservation came from reserve_aligned_huge (Reservation::is_huge() == true):
  • Windows: unconditionally does nothing. VirtualFree with MEM_DECOMMIT fails on large-page regions regardless of the requested range.
  • Linux/Android: the eligible-range/post-5.18-kernel case is FORWARDED to the kernel, the kernel is observed to ACCEPT that call, AND — since task #1174 — the crate's own CI now reads memory content back and confirms the zero-fill. madvise(2) documents that MADV_DONTNEED gained HugeTLB support in Linux 5.18, with the same 2-MiB-alignment requirement this crate already imposes on reserve_aligned_huge's own size/align on Linux/Android — so decommitting an entire huge reservation, or any 2-MiB-granular sub-range of it, IS such an eligible range. A page_size()-granular (e.g. 4 KiB) but not 2-MiB-granular offset still gets EINVAL and does nothing, as does EVERY range on a pre-5.18 kernel. Reservation::decommit/Reservation::try_decommit (the safe methods) check both is_huge() and the range before deciding whether to call the backend at all; the free decommit function has no is_huge() to consult and always issues the syscall, letting the kernel itself turn an ineligible range into a no-op. Documented per the man page cited above, and — since task #1152 (F1) — empirically exercised under a real hugetlb pool by this crate's own CI: the aligned-vmem-hugetlb-real job (.github/workflows/ci.yml) configures a real nr_hugepages pool, hard-asserts (via a path-activation oracle) that a huge-page grant was actually obtained, and then drives both an eligible and an ineligible range through the safe methods, confirming the eligible case reaches the real MADV_DONTNEED backend call rather than silently taking the Rust-level skip path. Since task #1164 (strengthened task #1166, F5), that job additionally hard-asserts the kernel's own response: under bench-internals, libc_madvise (src/os/unix.rs) records whether the syscall itself returned 0 (accepted) or -1 (rejected) into a counter pair, and the job now asserts that the successes counter equals the attempts counter for the eligible-range call (assert_eq!, not merely >) — i.e. the kernel genuinely accepted MADV_DONTNEED on this real MAP_HUGETLB mapping, not merely that the crate dispatched to it, and not merely that at least one of possibly several calls succeeded. Since task #1174, the CI job goes one step further and proves the outcome, not just the dispatch: ci_hugetlb_real_pool_decommit_actually_zeroes_memory_on_reaccess (tests/decommit_capability.rs) writes a non-zero byte pattern across the whole eligible range, calls decommit, then reads every byte back and hard-asserts it is zero — closing the "accepted the call" vs. "actually zero-fills on next access" gap this section used to leave open. What still remains NOT proven, and is deliberately kept separate from the zero-fill result above: that the kernel physically returned the huge pages to the pool. The CI job logs HugePages_Free (from /proc/meminfo) around the decommit call for a human to read, but does NOT gate on it — HugePages_Free is a kernel-global counter shared with every other huge-page reservation the job's other targets make, so it cannot be attributed to one test's own decommit() call without racing them, and is observation-only by design, not a pass/fail assertion. So: zero-fill-on-next-access is empirically proven for the eligible-range case; physical reclaim of the pages back to the hugetlb pool is not.
  • Either way — Windows, or an ineligible range/kernel on Linux/Android — the effect is indistinguishable from a silent no-op: RSS does not drop and reads return the old data. decommit_lazy is NOT part of this change: MADV_FREE has no documented HugeTLB support (unlike MADV_DONTNEED above), so it remains an unconditional no-op on huge reservations on every platform.
  • Use reserve_aligned instead of reserve_aligned_huge if you need decommit to work unconditionally, regardless of range shape or kernel version. Note: Huge-page support on Linux and Android (reserve_aligned_huge with the huge-pages feature) requires kernel >= 3.8 for correct MAP_HUGE_2MB size encoding. On kernels older than 3.8, the size bits are ignored and the system's configured default huge-page size is used instead of the expected 2 MiB; the crate does not detect this mismatch.
• Darwin (macOS/iOS/tvOS/watchOS): no zero-fill, no RSS return, on ordinary reservations too. MADV_DONTNEED is advisory-only for anonymous memory on Darwin, so unlike Linux and Android it does not reliably unmap the physical pages: a decommit + recommit round trip on any Darwin target can still observe the old data instead of a fresh zero page, even for a non-huge reservation. Confirmed as a real, failing-test-level gap by this crate's first real-macOS CI run on 2026-08-13 (the underlying hazard was already documented elsewhere in this repository since Round 9, before this crate was extracted); no fix is implemented yet — see https://github.com/PHPCraftdream/sefer-alloc/blob/main/docs/CORRECTNESS_OPEN_ITEMS.md item 48 for the open item. Use Reservation::decommit_reclaims_and_zeroes() to programmatically query whether the current platform guarantees reclaim+zero-fill semantics.
• BSD (FreeBSD/DragonFly/NetBSD/OpenBSD): the same advisory-only eager decommit caveat as Darwin, but lazy decommit_lazy genuinely reclaims. MADV_DONTNEED is advisory-only for anonymous memory on the four BSDs too — like Darwin, and unlike Linux and Android, eager decommit does not reliably unmap the physical pages there, so the same "no zero-fill, no RSS return" gap applies. Unlike eager decommit, though, decommit_lazy's MADV_FREE advice on BSD (as on Darwin's MADV_FREE_REUSABLE) DOES do something real: it drops the physical footprint rather than being a no-op — see decommit's own rustdoc for the precise wording this caveat mirrors. Use Reservation::decommit_reclaims_and_zeroes() to programmatically query whether the current platform guarantees reclaim+zero-fill semantics. REASONED-FROM-SPEC only (no BSD CI runner in this crate to verify against empirically); not independently confirmed the way the Darwin gap above was by a real CI run.
• Degraded state: if the one-time OS page-size query itself fails, every page-granular state operation fails closed for the process lifetime — not observed on any supported platform, but a documented user-visible contract. page_size() stays infallible (it returns the conservative PAGE floor, 4 KiB) so it never panics, but from that point on: decommit/decommit_lazy become no-ops, recommit/commit_range return false, and the try_* family (try_decommit, try_recommit, try_commit_range, the lazy reservation constructor, and try_page_size itself) reports Err(VmemError::os_refusal_unknown_code()). Reserving, using, and releasing memory are unaffected — only page-granular decommit/ recommit state operations are refused. Use try_page_size() to detect this upfront rather than discovering it through a later try_decommit error. See page_size()'s own rustdoc ("If the one-time OS query fails") for the full enumeration and rationale.

Supported targets

This crate's platform support falls into two categories:

CI-verified targets

The following platforms are verified by this project's CI and are tested on every commit:

• x86_64 Linux (Ubuntu, glibc)
• x86_64 Windows (Windows Server)
• AArch64 macOS (Apple Silicon, macos-latest CI)
• i686 Linux (compile-only check via cargo check --target i686-unknown-linux-gnu and cargo check --target i686-unknown-linux-musl) — musl uses 64-bit off_t on all architectures, so 32-bit musl targets (including i686) are safe with this crate's dual-arch OffT type.

Reasoned-from-spec targets

The following targets are supported but have not been empirically verified in CI. Support is based on published specifications and OS documentation:

• AArch64 Linux — the crate's FFI constants (MAP_ANON, MADV_*, _SC_PAGESIZE) are architecture-agnostic standard Linux values, not x86_64-specific, so the same 64-bit code path used by x86_64 Linux applies, but this has not been empirically CI-verified. (The project's CI has a cross-compilation matrix for aarch64, but no job runs on an ARM64 runner; AArch64 macOS is CI-verified — see the CI-verified list above.)
• BSD family (FreeBSD, DragonFly BSD, NetBSD, OpenBSD) — MAP_ANON, _SC_PAGESIZE, and MADV_* constants are derived from each OS's header files; no BSD CI runner exists for this project. MADV_DONTNEED's advisory-only behavior is confirmed by BSD documentation but not empirically verified on BSD hardware.
• Android (bionic) — 32-bit targets use a 32-bit off_t by default (matching glibc behavior without _FILE_OFFSET_BITS=64); this is reasoned from bionic's design documentation, not CI-verified.
• 32-bit musl Linux (e.g., armv7-unknown-linux-musleabihf) — off_t is correctly declared as 64-bit on all musl architectures (musl uses 64-bit off_t on all architectures), so the crate's dual-arch OffT type is safe; the i686-unknown-linux-musl target is compile-checked in CI (see the CI-verified list above), but other 32-bit musl targets are not.
• Apple platforms beyond macOS (iOS, tvOS, watchOS) — constants and behavior are derived from Apple's unified documentation; no CI runner currently tests these targets.
• MIPS — not supported (compile_error!). MIPS (both mips and mips64) uses different MAP_ANON/MAP_HUGETLB constant values than the asm-generic/mman-common.h values this crate hardcodes for Linux/Android. MIPS defines MAP_ANONYMOUS = 0x0800 and MAP_HUGETLB = 0x80000, while this crate uses 0x20 and 0x40000 respectively. With the wrong constants, every reserve_aligned call fails closed at runtime with EBADF (invalid file descriptor) but the failure is silent (no diagnostic points to the constant error). Rather than compile a buildable-but-broken crate, MIPS targets fail compilation with a clear diagnostic. This is a release decision; see https://github.com/PHPCraftdream/sefer-alloc/blob/main/docs/CORRECTNESS_OPEN_ITEMS.md item 62 for the decision record. Adding support requires adding a #[cfg(any(target_arch = "mips", target_arch = "mips64"))] arm with the correct MIPS-specific constant values.

Note: The absence of CI verification for a target means only that this project's own test suite has not executed on that platform. The platform-specific constants (e.g., MADV_DONTNEED = 4, Linux's _SC_PAGESIZE = 30, macOS's _SC_PAGESIZE = 29) are sourced from the respective OS's official documentation and header files. If you use this crate on a reasoned-from-spec target and encounter issues, please file a bug report.

The exact support matrix (task #1106/L3 — this enumeration, not a blanket family claim, is the contract; each arm is enforced by compile_error! in src/os/unix.rs for anything outside it):

• Unix, MAP_ANON = 0x20 arm: Linux and Android (any architecture except MIPS — see below).
• Unix, MAP_ANON = 0x1000 arm: macOS, iOS, tvOS, watchOS, FreeBSD, NetBSD, OpenBSD, DragonFly BSD.
• Unix, everything else (e.g. Solaris, illumos, AIX, Haiku): fails compilation with a diagnostic naming the missing MAP_ANON definition — cfg(unix) alone is NOT a promise of support.
• MIPS (any Unix OS): fails compilation (see the MIPS entry above).
• Windows: the Win32 backend (VirtualAlloc/VirtualFree); see the CI-verified list for which targets are tested.

Only the targets in the CI-verified list above have had the test suite actually run on them; everything else in the matrix is reasoned-from-spec.

Provenance & safety

Every unsafe block carries a // SAFETY: proof. The crate is the OS aperture extracted from sefer-alloc; it is deliberately the one place where the raw OS calls live, so consumers can stay #![forbid(unsafe_code)] above it. The returned pointers preserve provenance (no exposed-address as usize casts in the public API — the mock backend's diagnostic-only call recorder stores addresses as usize for comparison/logging, obtained via the non-exposing .addr(), and none of those values is ever cast back into a pointer; this crate's own tests/ files, which are not part of the public API, still use as usize at a few sites).

License

Dual-licensed under MIT or Apache-2.0, at your option.