Crate forge_alloc 

forge-alloc

Composable memory allocator primitives. Snap together at the type level to produce application-specific allocators with zero runtime dispatch overhead, compile-time-enforced guarantees, and pay-for-what-you-use security hardening.

forge-alloc bundles the three implementation layers as modules:

• backing — Layer 1: raw memory sources — InlineBacked, StaticBacked, HeapBytes, MmapBacked, HugePageBacked, System.
• layout — Layer 2: structure over a backing — BumpArena, Slab, SizeClassed, StackAlloc, WithFallback, and more.
• hardening — Layer 3: security & observability wrappers — Canary, PoisonOnFree, Quarantine, GuardPage, Statistics, and more.

Conformance helpers for downstream Allocator / FixedRange implementers live in testing (re-exported from forge-alloc-core).

The trait contracts (Allocator, Deallocator, OsBacked, FixedRange, FreelistProtection, NonZeroLayout, and the rest) live in the companion forge-alloc-core crate and are re-exported here, so a single forge-alloc dependency gives you the whole surface.

Quick start

use forge_alloc::{Allocator, BumpArena, Deallocator, InlineBacked, NonZeroLayout};

// 1 KiB stack-local bump arena.
let arena = BumpArena::new(InlineBacked::<1024>::new()).unwrap();
let layout = NonZeroLayout::from_size_align(64, 8).unwrap();

let block = arena.allocate(layout).unwrap();
assert_eq!(block.cast::<u8>().as_ptr() as usize % 8, 0);
// deallocate is a no-op for BumpArena; reclaim happens via reset(&mut self).
unsafe { arena.deallocate(block.cast(), layout) };

See ARCHITECTURE.md and COMPOSITION_RECIPES.md for the design and caller-facing composition recipes.

Modules

cache_padded

CachePadded<T> — target-aware cache-line alignment.

testing

Conformance helpers for downstream impls of FixedRange and Allocator.

traits

Foundation traits.

Structs

AllocError

The AllocError error indicates an allocation failure that may be due to resource exhaustion or to something wrong when combining the given input arguments with this allocator.

AllocStats

Snapshot of allocation activity. All counters are atomic; reading is Ordering::Relaxed because counter values are advisory (operators read them for diagnostics, not for ordering guarantees).

AlwaysFail

Policy that fails every allocation.

ArenaPool

A pool of recyclable BumpArenas — hand them out with checkout, return them with give_back (an O(1) reset plus retain up to a cap), so in steady state the same backings are reused with no munmap / mmap / re-fault. The motivating use is a per-commit / per-branch workload where throwing arenas away per unit of work would dominate the cost.

BumpArena

Bump arena over any FixedRange backing.

BumpDeallocator

ZST deallocator token tied to a BumpArena’s borrow.

CacheJitter

CacheJitter wrapper.

CachePadded

Wraps a value so it occupies a whole cache line, preventing the neighboring fields in a struct from being invalidated when the wrapped atomic is written by another core.

Canary

The Canary wrapper.

ExtendableSlab

Growable typed slab.

FailAfter

Policy that permits the first successes allocations and fails every allocation thereafter.

FailEveryNth

Policy that fails every period-th allocation and permits the rest.

FailOnSize

Policy that fails any allocation whose requested size is at least min_fail_bytes, and permits smaller ones.

Faulty

Fault-injection wrapper: forces allocations to fail according to a AllocFaultPolicy.

FnHandler

Dispatches every event to a user-supplied closure. The closure receives the level via event.level.

FreelistCorruption

Returned by FreelistProtection::verify when the stored MAC does not match the expected value.

GenerationalSlab

Generational slab.

GuardPage

Guard-page wrapper.

Handle

Stable, non-pointer handle to a slot in a GenerationalSlab.

HeapBytes

Owner of a single global-allocator block, exposed as FixedRange.

HugePageAligned

HugePageAligned wrapper.

HugePageBacked

OS-mapped anonymous region backed by huge / large pages.

InlineBacked

Fixed-size inline storage backing.

LockedMmapBacked

OS-mapped anonymous region whose pages are locked into physical RAM.

LogHandler

Emits one eprintln! line per event. Suitable for development; not recommended for production hot paths (stderr writes hit a global lock in libstd).

MmapBacked

OS-mapped anonymous region.

MmapFlags

Optional flags for MmapBacked::with_flags.

NeverFail

Policy that never injects a failure — every allocation proceeds to the inner allocator unchanged.

NoProtection

Zero-overhead default. sign returns 0; verify always succeeds. The optimizer reliably folds calls through NoProtection into no-ops in release builds.

NodeSet

Compact set of NUMA node IDs (up to 64 nodes). Built directly into a Linux nodemask word at mbind time. Bigger systems need a dynamic representation; that’s not yet shipped.

NonZeroLayout

A Layout with size > 0 and a power-of-two alignment.

NullHandler

Discards every event. Zero-overhead substitute when monitoring is disabled in a release build.

NumaLocal

NumaLocal wrapper.

PoisonOnFree

Wrapper that overwrites freed memory with a poison pattern.

ProtectFlags

Memory protection bits passed to OsBacked::protect.

Quarantine

Quarantine wrapper.

Scope

A scratch scope over a BumpArena, created by BumpArena::scope.

SharedBumpArena

Atomic-cursor bump arena.

SipHashMAC

SipHash-1-3 keyed MAC over the (next_idx, slot_addr) pair.

SizeClassed

SizeClassed allocator.

Slab

Fixed-stride typed slab.

SlabOwner

Owns the slab. Has exclusive allocate access. Send (can be moved across threads) but !Sync (one-at-a-time access — enforced by UnsafeCell on the inner slab plus our manual Send impl with no corresponding Sync impl).

SlabRemote

Remote deallocation handle. Send + Sync — freely cloneable across threads. Implements Deallocator only; cannot allocate.

SplitMetadata

SplitMetadata wrapper.

StackAlloc

LIFO-discipline allocator over a FixedRange backing.

StaticBacked

Borrows an external byte buffer as a FixedRange.

Statistics

Wrapper that records allocation activity in AllocStats.

StdCompat

Adapter that exposes any crate::Allocator as an allocator_api2::alloc::Allocator.

System

Adapter exposing the standard System allocator as an forge_alloc_core::Allocator.

Watermark

Watermark wrapper.

WatermarkEvent

Snapshot of allocation state when a WatermarkHandler fires.

WatermarkThresholds

Threshold percentages for the warn / critical levels.

WithFallback

Router with primary + secondary allocator.

ZeroizeOnFree

Wrapper that volatile-zeroes freed memory.

Enums

BatchPolicy

How aggressively the owner drains the remote-free queue.

NumaPolicy

NUMA placement policy. v0.1 accepts an explicit node set rather than dispatching against the calling thread’s node — supply current_numa_node() if you want the local-at-construction behaviour.

WatermarkLevel

Severity bucket emitted to a WatermarkHandler.

Constants

ADAPTIVE_COOLDOWN_TICKS

Number of maybe_drain ticks between adaptive step adjustments. Tuned for low overhead and quick settling on bursty workloads.

ADAPTIVE_LEVELS

Drain-threshold levels for BatchPolicy::Adaptive.

CACHE_LINE

The cache-line alignment used by CachePadded on this target. Surfaced so dependent crates and const _: () = assert!(...) layout pins can reference the same value the wrapper itself uses.

DEFAULT_CLASS_SIZES_8

Default class sizes (bytes): 8, 16, 32, 64, 128, 256, 512, 1024.

DEFAULT_POISON

Default poison byte. 0xDE is a recognizable hex marker that’s unlikely to be a valid value for most types and easy to spot in a memory dump.

MAX_ALIGN

Maximum supported alignment for InlineBacked allocations.

Traits

AllocFaultPolicy

Decides whether a pending allocation request should be forced to fail.

Allocator

The allocation contract. Returns memory satisfying a NonZeroLayout or AllocError. Extends Deallocator so that any allocator can also reclaim what it issued.

Deallocator

The deallocation half of an allocator. Every type that issues memory must be able to take it back at drop time.

FixedRange

Address range fixed at construction.

FreelistProtection

Pluggable integrity policy for slab freelists.

GenerationInt

Width of the generation counter. Public so callers can pick u32 (default — 2^32 reuses per slot before wraparound) or u64 (effectively unbounded). Internal trait sealed via the empty trait pattern.

OsBacked

Allocators backed by OS-managed virtual memory.

WatermarkHandler

Callback handler invoked on threshold crossings and on OOM.

Functions

current_numa_node

Best-effort detect of the calling thread’s NUMA node.

default_huge_page_size

Platform-default huge page size in bytes.

mmap_clear_last_os_error

Clear the per-thread last-error slot. Mainly useful in tests; callers in production typically just read mmap_last_os_error after a failure.

mmap_last_os_error

Return the most recent failing-syscall error captured into this module’s slot on the current thread, or None if none has been recorded since thread start or mmap_clear_last_os_error was last called.

mmap_record_os_error

Record the current platform errno / GetLastError into the per-thread last-error slot from an external crate. Use this immediately after a failing syscall (e.g. mbind, madvise, pthread_*) in a crate that composes with MmapBacked so callers can read a single mmap_last_os_error regardless of which layer’s syscall failed.

page_size

The OS memory page size in bytes — 4 KiB on most x86-64, 16 KiB on Apple Silicon. Pass this where a primitive needs a page-size argument (such as GuardPage) rather than hard-coding a value that is wrong on 16 KiB-page platforms.

Type Aliases

CryptoSlab

The HardenedSlab security stack over RAM-locked, core-dump-excluded memory, wrapped in non-elidable scrub-on-free — the recommended composition for cryptographic key material (“crypto allocator”).

HardenedSlab

Slab with split metadata and guard pages on both regions — the recommended maximum-hardening composition for security- critical data: PHI, key material, audit logs, allocation tokens.