Struct MmapFlags 

#[non_exhaustive]
pub struct MmapFlags {
    pub huge_pages: bool,
    pub populate: bool,
    pub numa_node: Option<u32>,
    pub guard_at_end: bool,
    pub lazy_commit: bool,
}

Optional flags for MmapBacked::with_flags.

Most flags route to features not yet implemented (HugePageAligned, NumaLocal). Currently only populate is honored on platforms that support it; the rest are accepted for forward compatibility but currently no-op.

#[non_exhaustive] so future bits (MAP_NORESERVE, MTE enable) can be added without an API break.

Note on MAP_LOCKED / mlock: page-locking for cryptographic secrets is available as a separate backing type — LockedMmapBacked — rather than as a flag here. Using a distinct type enforces the fail-closed guarantee (no silent unlocked fallback) at the type level and makes the security intent visible in caller code.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

huge_pages: bool

Request transparent / explicit huge pages. Implemented via HugePageAligned; ignored at this layer.

populate: bool

Fault all pages at allocation time so subsequent accesses don’t take page-fault latency.

Platform support is asymmetric — setting this to true does not guarantee eager paging on every platform:

• Linux: maps to MAP_POPULATE. Kernel walks the page tables at mmap time so subsequent accesses don’t fault.
• macOS / BSD: silently ignored. There is no portable equivalent that operates at mmap time; eager paging on Darwin requires madvise(MADV_WILLNEED) over the region after mapping, which MmapBacked does not currently perform.
• Windows: silently ignored — but not because eager paging already happened. VirtualAlloc(MEM_RESERVE|MEM_COMMIT) charges the full region against the system commit limit at construction, yet does not make pages resident: the working set is still populated lazily by demand-zero faults on first access, exactly as on Unix. So the per-page fault latency this flag targets is unchanged on Windows; there is nothing for it to populate eagerly. The real Windows-specific divergence is a cost, not a benefit: because Windows does not overcommit, that commit charge is reserved whether or not the pages are ever touched, so a large MmapBacked whose consumer writes only a fraction of it (e.g. a bump arena sized for headroom) still consumes its full size of commit budget — and the mapping fails at construction once the cumulative charge exceeds the limit, even with physical RAM free. Opt out of the up-front charge with lazy_commit (reserve-only + incremental MEM_COMMIT driven by FixedRange::commit as a BumpArena cursor advances).

Use Self::populate_supported to test at runtime whether setting this flag will have any effect, or branch on cfg! in caller code.

numa_node: Option<u32>

Bind to a specific NUMA node. Implemented via NumaLocal; ignored at this layer.

guard_at_end: bool

Append one unmapped guard page after the region. Implemented via GuardPage; ignored at this layer.

lazy_commit: bool

Reserve the address range without committing it up front, leaving per-page commit to FixedRange::commit as a consumer’s cursor advances.

Windows-only effect. On Windows, VirtualAlloc(MEM_RESERVE) reserves address space without charging the system commit limit; pages are committed lazily via commit. On Unix this flag is inert — mmap(MAP_ANONYMOUS|MAP_PRIVATE) is already demand-paged, so the region is created exactly as without the flag and commit is a no-op.

Safety / usage contract

A lazy_commit mapping hands back reserved-but-uncommitted pages on Windows; writing one before FixedRange::commit has committed it faults (access violation). Supported consumers commit before any write reaches the page:

• BumpArena / StackAlloc commit each block as the cursor advances — true demand-commit, the intended use.
• A pass-through FixedRange wrapper interposed between the arena and the mapping (Statistics, PoisonOnFree, Quarantine, Watermark, Canary, CacheJitter, Faulty, HugePageAligned, NumaLocal, SplitMetadata) forwards commit, so it stays safe.
• Slab, SizeClassed, and direct Allocator::allocate carve via allocate, which commits the block up front — safe, but commits eagerly (no demand-paging benefit on this path).

Two consumers still fault and are unsupported over a lazy mapping — use MmapBacked::new (eager) for them:

• SharedBumpArena — it is Sync and would race the !Sync commit watermark, so it deliberately does not call commit.
• GuardPage — its usable range starts past a guard page and its inner bound is only OsBacked, so it has no commit to forward.

Implementations

impl MmapFlags

pub const NONE: Self

Empty flag set — equivalent to MmapBacked::new.

pub const fn populate_supported() -> bool

Returns true if populate: true will actually be honored on the current platform — true on Linux, false on macOS / BSD / Windows. Allows callers to branch on whether the eager-paging performance hint is meaningful without resorting to cfg! checks scattered through application code.

Trait Implementations

impl Clone for MmapFlags

fn clone(&self) -> MmapFlags

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for MmapFlags

impl Debug for MmapFlags

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MmapFlags

fn default() -> Self

Returns the “default value” for a type.

impl Eq for MmapFlags

impl PartialEq for MmapFlags

fn eq(&self, other: &MmapFlags) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for MmapFlags