Struct VmemError

Source

pub struct VmemError { /* private fields */ }

Expand description

The cause of a virtual-memory operation failure.

os_code is Some(code) for a genuine OS refusal with a known cause, where code is errno (Unix) or GetLastError (Windows).
os_code is None for VmemError::invalid_argument — a contract violation (e.g. non-power-of-two align, zero size) detected before any syscall — and also for a no-code failure on the OS side (see os_refusal_unknown_code). Use is_invalid_argument to tell the two None cases apart — task #712/#713 (2026-08-09): an earlier version of this type stored the raw code as a bare u32 defaulting to 0 when unavailable, making “no OS code available” indistinguishable from a genuine code 0 / ERROR_SUCCESS — os_code() reported Some(0) for both. Storing Option<u32> closes that gap at the type level.

Implementations§

Source §

impl VmemError

Source

pub const fn invalid_argument() -> Self

A caller-contract-violation error: the arguments were rejected before any OS call. This covers MORE than the size/align contract, which is why neither this doc nor Display names that one contract specifically any more (task #1046, finding R7-7 — Display used to print “size/align contract violation” for every one of these). The rejected classes, enumerated from the actual call sites rather than guessed:

size/align contract: align not a power of two, size not a page multiple, size == 0, or the size + align sum overflowing.
The initial_commit contract on the lazy path.
The commit/recommit RANGE contract: start > end, either endpoint not a multiple of the runtime page_size(), or end past len().
Huge-page alignment on the Linux/Android huge path.
An internal fit computation failing — deliberately mapped here rather than to a stale OS error code, because no OS call refused anything.

The specific cause is documented on the method that returned it; this type carries no payload naming which parameter was at fault.

Source

pub const fn from_os_code(code: u32) -> Self

Wrap a raw OS error code (errno / GetLastError).

Source

pub const fn os_refusal_unknown_code() -> Self

A no-code failure on the OS side — the operation failed without a real OS error code to report. FOUR sources — keep this count in sync with the list below when adding one: task #1139 added the fourth and left the count reading “Three”, corrected by task #1141 (task #1106/L2 — an earlier revision of this doc called ALL of them a “genuine OS refusal”, which is false for the third and fourth):

under miri (no real errno/GetLastError exists to read) — a genuine refusal by the miri stand-in;
the rare case where the platform’s own raw_os_error() itself returns None — a genuine OS refusal with an unavailable cause;
(task #1068/F2) the crate’s own rejection of the kernel’s R7-11 address-zero mmap grant on Unix — mmap SUCCEEDED and the crate unmapped the grant itself, so no syscall refused anything and there is no real code to report. This source is not a refusal by the OS at all; it shares this sentinel because it is equally not a caller contract violation, and the type carries no further discrimination (crate still at 0.2.0, unpublished — a distinct kind was judged not worth the public-API surface; see the task #1106/L2 record);
a FAILED one-time OS page-size query (never observed on a supported platform): crate::try_page_size and every page-granular try_* state operation (try_decommit, try_recommit, try_commit_range, the lazy reservation constructor) report the crate’s fail-closed degraded state through this sentinel — the caller’s arguments are not at fault, and no per-call OS code exists (the query failed once, at first use, possibly long before the reporting call). Same no-new-kind reasoning as the third source above.

Distinct from invalid_argument: is_invalid_argument() is false here — the failure originated on the OS side (or in the crate’s response to an unusable OS grant), not in the caller’s arguments.

This FOUR-source count is scoped to production causes; it deliberately excludes two TEST-ONLY construction SOURCES, spread across FOUR TEST-ONLY construction SITES (task #1173/L2, re-measured for this doc’s own correction — task #1194 — against the actual call sites rather than re-asserted from an earlier audit’s count; re-measured again task #1249 after task #1219 added the decommit-side fault-injection hook, which grew the fault-injection source from one site to two. Counted with doc mentions EXCLUDED, because a raw grep -rn "VmemError::os_refusal_unknown_code()" crates/aligned-vmem/src/ also matches prose like this very sentence — its total therefore changes whenever this paragraph is edited, which is exactly how task #1194’s first attempt recorded a figure its own edit falsified one line later. The stable count is grep -rn "VmemError::os_refusal_unknown_code()" crates/aligned-vmem/src/ | grep -vE ":\s*(///|//!|//)" → 11 real construction sites; of those 11, 7 are production sites — matching the four causes below — and 4 are test-only sites): the aligned_vmem_mock backend’s scripted commit/reserve fault injection (crate::mock, gated on that cfg — TWO sites, take_reserve_fault/take_commit_fault) and the real-path fault-injection feature’s simulated commit AND decommit failures (crate::fault_injection, TWO sites — api/commit_range.rs and, since task #1219, api/decommit.rs’s dispatch_try_decommit) both also construct this sentinel, to simulate a no-code OS failure deterministically without touching the OS — see each module’s own doc for why NEITHER SOURCE is a fifth or sixth PRODUCTION source: all four sites exist only under test-only cfgs or an explicitly-armed opt-in feature, and none is reachable in an ordinary disarmed build.

Source

pub const fn os_code(&self) -> Option<u32>

The raw OS error code. None for invalid_argument OR for a no-code failure on the OS side (os_refusal_unknown_code) — use is_invalid_argument to tell those two None cases apart.

Source

pub const fn is_invalid_argument(&self) -> bool

true if this is a caller contract violation rather than an OS refusal.

Source

pub fn last_os_error() -> Self

Capture the current thread’s last OS error (errno / GetLastError). Yields os_refusal_unknown_code under miri, or if the platform’s own raw_os_error() returns None.

Timing contract: call this IMMEDIATELY after the syscall whose failure it is meant to capture, before any other FFI call (including cleanup) — any intervening call may overwrite errno/GetLastError (task #713).