Struct Reservation 

pub struct Reservation { /* private fields */ }

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

as_ptr() is non-null, aligned to the align requested at reservation, and valid for len() bytes for the lifetime of this handle. The span is not initialised. Dropping the handle returns the whole underlying OS reservation to the OS exactly once.

For a self-hosted allocator that records (reservation, reservation_len) in its own metadata rather than keeping a Vec<Reservation>, use into_parts to take the raw reservation (suppressing the Drop) and release it later with release.

Reservation is Send (the span is owned exclusively) but not Sync (writes through the raw pointer are unsynchronised — that is the caller’s concern).

Implementations

impl Reservation

pub fn as_ptr(&self) -> *mut u8

The aligned usable base of this span. Non-null, valid for len bytes, aligned to the align requested at reservation time.

pub const fn len(&self) -> usize

The number of usable bytes at as_ptr.

pub const fn is_empty(&self) -> bool

Whether the usable span is empty (always false — reserve_aligned rejects zero sizes; provided for lint-friendliness).

pub fn reservation_ptr(&self) -> *mut u8

The start of the underlying OS reservation (may sit below as_ptr due to the over-reserve + trim technique).

pub const fn reservation_len(&self) -> usize

The full size of the underlying OS reservation.

pub fn into_parts(self) -> (*mut u8, usize, usize)

Consume the handle WITHOUT releasing the OS reservation, returning the (reservation_ptr, reservation_len, align) the caller must later hand to release exactly once. Use this when your allocator records the reservation in its own self-hosted metadata instead of relying on Drop.

align is the alignment originally requested; the native release paths ignore it, but it is required for the miri fallback to reconstruct the exact Layout. A self-hosting allocator that always uses one alignment can pass that constant to release instead of storing this value.

pub unsafe fn from_raw_parts( base: *mut u8, len: usize, reservation: *mut u8, reservation_len: usize, align: usize, ) -> Self

Wrap a pre-existing OS reservation (e.g. one obtained from VirtualAllocExNuma or another platform-specific allocator that reserve_aligned does not call directly) in a Reservation handle.

The handle then participates in the normal RAII lifecycle: on Drop (or via release) the underlying reservation is returned to the OS using the platform-appropriate release routine (VirtualFree(MEM_RELEASE) on Windows, munmap on Unix, std::alloc::dealloc on miri).

This is the inverse of into_parts and exists for the cross-crate handoff pattern: a sibling crate (numa-shim on Windows) issues a platform-specific reservation call that aligned-vmem itself does not wrap, then adopts the result via this constructor so downstream code can hold a uniform Reservation regardless of which syscall produced it.

Safety

All five values must describe a live, exclusively-owned OS reservation compatible with aligned-vmem’s release path:

• base is the aligned usable start; non-null, valid for len bytes, aligned to align.
• len is the usable span size, a non-zero multiple of PAGE.
• reservation is the underlying OS reservation start (often equal to base, but may be lower under the over-reserve + trim technique).
• reservation_len is the full size of the OS reservation, a non-zero multiple of PAGE, reservation_len >= len + (base - reservation).
• align is a power of two >= PAGE and matches the alignment the OS reservation was created with. The native release paths (VirtualFree / munmap) ignore it; the miri fallback uses it to reconstruct the exact Layout.

The reservation must be released exactly once — by dropping this handle, or by extracting via into_parts and calling release manually. Constructing two Reservation handles over the same OS reservation is undefined behaviour (double release).

On Windows specifically, the reservation MUST have been created with MEM_RESERVE | MEM_COMMIT so VirtualFree(MEM_RELEASE) accepts it. (VirtualAllocExNuma(..., MEM_RESERVE | MEM_COMMIT, ...) satisfies this — that is the intended call site.)

Trait Implementations

impl Drop for Reservation

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Reservation