Allocator Fast Paths And Page Backend

Allocator fast-path evidence defines how native runtime allocation stays local,

bounded, and explicit. This page covers allocator profiles, size classes, local

free lists, local heap ownership, slow-path span refill, remote-free batching,

transfer caches, central page/span management, hosted-server hugepage and NUMA

hooks, stress coverage, and shutdown cleanup.

Run:

make allocator-fast-path-check
make native-memory-control-check

make native-memory-control-check depends on make allocator-fast-path-check.

The allocator gate validates allocator-specific performance, page-backend, and

stress evidence before the broader native memory-control evidence is accepted.

Evidence Files

• allocator/profiles.tsv defines allocator profiles.
• allocator/size-classes.tsv defines size classes and fast-path budgets.
• allocator/local-fast-path.tsv records local free-list and local heap

behavior.

• allocator/remote-free.tsv records bounded remote-free queues or message

passing.

• allocator/page-backend.tsv records central page/span management.
• allocator/transfer-cache.tsv records transfer cache behavior.
• allocator/hosted-hooks.tsv records hugepage and NUMA hooks.
• allocator/stress-cases.tsv records positive and negative stress fixtures.
• allocator/diagnostics.tsv defines stable diagnostics.
• release/allocator-fast-path-report.tsv records fast-path instruction and

branch budgets.

• release/allocator-remote-free-report.tsv records remote-free queue

behavior.

• release/allocator-page-backend-report.tsv records page backend behavior.
• release/allocator-stress-report.tsv records stress coverage.
• release/allocator-diagnostics-report.tsv records negative diagnostics.
• perf/allocator-fast-path-benchmarks.tsv records performance budgets.
• compat/allocator-fast-path-contract.tsv records release ownership and gate

wiring.

• tools/allocator-fast-path-check.py validates the evidence and fixtures.

Profiles

The allocator profiles are:

• freestanding: reserved static or arena storage, no OS dependency, no remote

frees, no hugepage or NUMA behavior;

• hosted-small: thread-local fast paths and ordinary mmap spans;
• hosted-server: thread-local fast paths, central spans, transfer caches,

and opt-in hugepage or NUMA hooks;

• realtime: actor-local heaps and bounded message-passing remote frees;
• test-fixture: deterministic test-only page backend;
• compiler-internal: compiler arena spans and local ownership.

GC is not the default for any allocator profile.

Fast Paths

Fast paths must fit recorded instruction and branch budgets. Local allocations

use local free lists and local heap ownership. Slow-path refill pulls from

transfer caches or central spans. Remote frees must not perturb the local fast

path except at documented drain points such as safepoints, slow-path refill,

thread exit, message boundaries, actor shutdown, or arena reset.

Page Backend

The page backend owns span allocation, central cache behavior, transfer-cache

refill, exhaustion behavior, and release cleanup. Exhaustion fails closed before

publishing partial values. Shutdown must drain remote-free queues and release

owned spans.

Hugepage and NUMA hooks are allowed only for explicit hosted-server release

profiles. They are disabled by default and rejected for hosted-small,

freestanding, realtime, compiler-internal, and test fixture profiles.

Stress Coverage

The allocator stress suite covers:

• local free;
• remote free;
• cross-thread allocation;
• fragmentation;
• large objects;
• exhaustion;
• shutdown cleanup.

Diagnostics

The allocator gate uses stable diagnostics:

ALLOCATOR_FAST_PATH_BUDGET
ALLOCATOR_REMOTE_FREE_OVERFLOW
ALLOCATOR_PAGE_EXHAUSTION
ALLOCATOR_HUGEPAGE_POLICY
ALLOCATOR_NUMA_POLICY
ALLOCATOR_EXHAUSTION
ALLOCATOR_SHUTDOWN_LEAK

Documentation Impact

Runtime memory, native allocation, page backend, hugepage, NUMA, allocator

stress, or shutdown behavior changes must update this page, the allocator

evidence files, release notes, and the public reference index in the same

change.