Crate aligned_vmem 

aligned-vmem — cross-platform aligned anonymous virtual memory.

Reserve a span of size bytes whose base is aligned to an arbitrary power-of-two align, commit/decommit its pages, and release it — directly through the OS (mmap/munmap/madvise on Unix, VirtualAlloc/ VirtualFree on Windows), with no file-mapping machinery and no dependencies. Under miri it falls back to std::alloc so consumers stay miri-testable.

This is the OS aperture extracted from sefer-alloc. It is the one crate whose entire purpose is the unsafe OS calls — every unsafe block carries a // SAFETY: proof, and a safe API is exposed on top.

Why not region / memmap2 / mmap-rs?

Those crates are oriented around file mappings and page-protection. aligned-vmem does one different thing: hand you an anonymous span whose base is aligned to a power of two you choose (e.g. 2 MiB / 4 MiB for an allocator’s segments) via the classic over-reserve + trim technique, plus page-granularity decommit/recommit so you can return physical memory to the OS while keeping the address-space reservation. If you are building an allocator, an arena, or a slab and need “give me a 4 MiB-aligned 4 MiB span”, this is the small focused tool.

Example

use aligned_vmem::{reserve_aligned, release};

// Reserve 4 MiB aligned to 4 MiB.
let span = 4 * 1024 * 1024;
let r = reserve_aligned(span, span).expect("OOM");
let base = r.as_ptr();
assert_eq!(base as usize % span, 0); // base is `span`-aligned

// SAFETY: `base` is valid for `r.len()` bytes; we own it exclusively.
unsafe { base.write(0xAB); assert_eq!(base.read(), 0xAB); }

// RAII release on drop, or take the parts for manual self-hosted release:
let (raw, raw_len, raw_align) = r.into_parts();
// SAFETY: the triple came from `into_parts` and is released exactly once.
unsafe { release(raw, raw_len, raw_align) };

Alignment contract

align must be a power of two and at least page_size. size must be a non-zero multiple of page_size (so decommit ranges land on page boundaries). Violations return None rather than panicking.

Structs

Reservation

An owning handle to one aligned span of anonymous virtual memory.

Constants

PAGE

The page size this crate assumes for decommit/recommit granularity: 4 KiB, the smallest unit both mmap and VirtualAlloc will commit/decommit on the platforms this crate targets. Decommit/recommit offsets must be multiples of this value.

Functions

decommit^⚠

Decommit pages [base + start, base + end): return their physical backing to the OS while keeping the address-space reservation alive. Re-access after decommit produces fresh zero-filled pages (after recommit on Windows; implicitly on Unix).

page_size

Return the page size used for decommit / recommit granularity.

recommit^⚠

Recommit pages [base + start, base + end) previously passed to decommit. On Windows this re-commits physical pages (VirtualAlloc(MEM_COMMIT)); on Unix re-access is implicit so this is a no-op.

release^⚠

Release a whole OS reservation obtained from Reservation::into_parts.

reserve_aligned

Reserve size bytes of anonymous virtual memory whose base is aligned to align, via the over-reserve + trim technique.