Axle v0.22.0

Escape analysis and promotion

new T(...) always looks like a heap allocation in the source. The compiler decides where it actually lives — and most of the time, that’s not the heap.

What this page covers: what “escape” means · the passes that answer it · what forces an object out of the stack tier · how the array allocation strategies are chosen · what the analysis refuses to decide · how to watch the decision in the emitted HIR and IR.

What “escape” means

An object escapes a function when something outside that function can still reach it after the function returns. That’s the one question that decides whether the object can go on the cheap stack tier: a stack slot vanishes when the frame pops, so anything that must outlive the call cannot live there.

An object escapes when it is:

   returned            stored in an        handed to a
   from the fn         escaping owner      spawn target
   ┌────────┐          ┌────────┐          ┌────────┐
   │  new T │──return─►│  new T │──field──►│  new T │──spawn──►
   └────────┘          └────────┘          └────────┘  ▲
        ▲                   ▲                           │
        │                   │                    the task reads it
   caller keeps it    outer object keeps    after this fn returns
   after we return    it after we return

If none of those can happen — the object is created, used, and dropped entirely inside the function — then it does not escape, and the compiler puts it on the stack. Escape analysis is the pass that answers this question for every allocation site, by following where each new T(...) flows.

   does the object escape its declaring function?
        │
        ├─ no, and never leaves its scope      → STACK  (alloca)
        ├─ no, but leaves its scope in-frame   → ARENA  (bump, rewound in bulk)
        └─ yes (return / throw / field / spawn) → HEAP   (malloc / shared)

Escape analysis is conservative: when it cannot prove an object stays local, it assumes it escapes and keeps it on the heap. A false “it escapes” only costs a malloc that was avoidable; a false “it’s local” would free memory still in use — so the analysis always errs toward the safe, heap-resident answer.

Two promotion passes

Two passes run one after the other over every allocation site, and each one only looks at what the previous one left on the heap.

  1. The stack promoter asks whether the value leaves its declaring function. If not, the allocation becomes a stack slot in the entry block. The frame pop reclaims the storage, and no malloc ever runs. This pass runs first because it produces the smallest IR shape for every pass after it.
  2. The arena promoter asks whether the value leaves the request scope. If it stays inside the function, the allocation moves to the per-function arena, and one rewind at function exit (or at the end of a wrapped loop iteration) releases every object in that scope. The arena pass walks the allocation dependency graph — constructor arguments, struct fields, array elements, field writes through a local receiver — so an allocation whose only escape paths end in scope-only positions is still promoted. The dependency closure is what answers “does this transitively outlive the frame”.

Allocations that fail both checks (returned, thrown, stored into a field of an escaping object, passed to a function that retains them, handed to a spawn target) stay on the heap — plain malloc for owned bindings, and the shared allocator (with its 16-byte refcount header) for Shared<T>.

What counts as “escape”

  • Returned from the function.
  • Stored into a field of a value that itself escapes.
  • Thrown from the function.
  • Assigned through an index, deref, or field write whose receiver escapes.
  • Passed to a callee whose parameter signature doesn’t promise non-retention (the callee captures into its own escape set).
  • Handed to a spawn, or captured by a closure that can outlive the frame.

The two-pass system is conservative — when in doubt, it stays on the heap. False positives (would have been safe to stack-promote, but went heap) are common at refactor boundaries; false negatives (escape that the analysis missed) would be unsound, so the rules err strictly.

Watch it happen

One class, two call sites, two tiers — decided purely by whether the object escapes. Build with --emit=hir and read the keyword in front of the allocation (stack vs a bare new for heap):

class Box {
    pub v : i64;
    constructor(v : i64) { self.v = v; }
}

// Does NOT escape: b is read and dropped inside the function.
fn sum_local() : i64 {
    let b : Box = new Box(41);   // HIR: stack Box(41)   → alloca, no malloc
    return b.v + 1;
}

// ESCAPES via return: the value must survive the frame pop.
fn hand_out() : Box {
    let b : Box = new Box(41);   // HIR: new Box(41)      → heap malloc
    return b;                    // one owner; freed at the caller's drop
}

The bodies are identical except for the last line. Returning b is an escape, so hand_out cannot use the stack; sum_local keeps b entirely local and pays nothing. You never annotate this — the analysis reads the return and routes accordingly.

Restrictions

Classes with a user-declared destructor are not refused the arena. The arena promoter registers the destructor at the allocation site, and the rewind runs the registrations newest first before it reclaims the memory (see Destructors and the arena). Two cases keep an object on the heap:

  • the class is a stdlib handle class (its value is an integer handle that the native half owns);
  • the class is non-trivial to tear down but the compiler cannot name the destructor function that would run.

A class that only owns heap fields (and so gets a compiler- synthesised destructor that just frees those fields) follows one rule: a child’s tier follows its container’s. When a let p = new Container(...) provably doesn’t escape its frame, the compiler inlines the constructor at the allocation site, promotes the container to the stack, promotes each single-write owned child onto the stack with it, and drops the synthesised destructor for that instance — the frame pop reclaims the whole graph. So class Pair { a : Wrap; b : Wrap; } used locally puts the Pair and both Wraps on the stack with zero malloc; the optimiser then dissolves the entire graph into registers (there’s no allocation left to optimise). A child that itself owns heap, a reassigned field, or an escaping container keeps the ordinary heap path — and when the container escapes, its children stay on the heap with it, freed by the destructor.

   let p = new Pair(...)   provably local          p returned / stored → escapes
   ┌────────────────────────────────────┐          ┌──────────────────────────┐
   │ STACK frame                        │          │ HEAP                     │
   │   Pair ──owns──► Wrap a            │          │   Pair ──owns──► Wrap a  │
   │        └─owns──► Wrap b            │          │        └─owns──► Wrap b  │
   └────────────────────────────────────┘          └──────────────────────────┘
     child tier FOLLOWS the container:                the whole graph is heap;
     all three on the stack, zero malloc,             the synthesised destructor
     synthesised destructor dropped                   frees each owned child

The array allocation strategies

Once the analysis has picked the tier, every array allocation in the program is tagged with one of eight strategies. The enum is HirAllocStrategy, and the names below are the variants.

An object allocation (new T(...)) carries its tier on the expression itself — StackAlloc, ArenaAlloc, HeapAlloc or SharedAlloc — and not through this enum. The enum answers for T[N](v) and new T[n] sites. The decision is made once at compile time; the code emitter mechanically picks the matching call shape and never re-inspects allocation sizes, types, or escape state.

StrategyWhen it is chosenWhat is emitted
StackAllocaA constant-count T[N] whose byte size is at most STACK_ALLOC_BYTES_MAX (32 KiB), and which does not escape its frame; or a constant-count new T[n] of plain scalars (header plus data within the same 32 KiB) held by a local the function only indexes or measures.One alloca [N x T] in the entry block, plus an optional zero-fill; for new T[n], one slot holding the [capacity \| length] header and the data, with nothing to free.
LibcCallocConstant count and sizeof(T), product below HUGE_PAGE_MIN_BYTES, and the buffer is read before it is fully written.calloc(count, size) — zero-filled in one call.
HugeCallocSame operands as LibcCalloc, with a total of at least 2 MiB (HUGE_PAGE_MIN_BYTES); or a constant-size new T[n] of at least 2 MiB, whose slots must start zeroed.__axle_runtime_huge_calloc(count, size): mapping with the huge-page hint, zero-filled by the operating system’s fresh pages, so no clearing pass follows.
LibcMallocA dynamic-count new T[n]; or a constant count above the stack threshold and below 2 MiB; or a new T[n] that is passed, returned, stored, captured, freed by hand, re-assigned or not made of plain scalars; or any buffer proven to be fully overwritten before its first read, so the zero-fill is skipped.malloc(N). A T[N] that skips its fill is left uninitialised; a new T[n] is cleared right after, unless the loop that follows provably overwrites every slot.
HugeAllocA constant total of at least 2 MiB whose zero-fill is proven unnecessary.__axle_runtime_huge_alloc(size): mapping with the huge-page hint, no zero-fill.
ArenaBumpA buffer whose value stays inside the function’s arena scope.An inline bump of the thread’s axle_arena_cursor, calling the slow path only when the active chunk is full.
SharedAllocShared<T> storage (share new T(...), or share new T[n]).axle_shared_alloc(size): a 16-byte refcount header followed by a 16-byte-aligned payload.
StdlibFfiHandlenew ClassName(args) on a stdlib handle class such as ReentrantLock, BoundedChannel or Semaphore.__axle_stdlib_<module>_<Class>_new(args), which returns an i64 handle. The address of the state the native half allocated; no malloc runs on the Axle side.

The most conservative strategy (LibcMalloc) is the default — it’s always correct, never always fastest. Every other strategy is an upgrade applied when the analysis can prove the upgrade is safe.

Note

The 32 KiB stack threshold is one of two stack budgets. A stack-promoted T[N] literal initialiser is also bounded by a separate, smaller budget (512 bytes and at most 64 elements). Both are named in the axle_common::limits table, so they cannot drift between sema and codegen.

Bookend behaviour you can rely on

  • Every let x = new T(...) whose receiver provably doesn’t escape becomes a stack slot. Tight loops allocate at zero runtime cost — the slot is materialised once at the function entry block and overwritten in place on each iteration.
  • Every arena-eligible allocation is released when its scope ends. Each arena-using frame records the arena position it inherited on entry, and rewinds to exactly that position on every return path, including unwind and throw exits. It never releases the whole pool. A callee returning to a still-live caller leaves the caller’s arena objects intact, and that nesting contract is what lets one arena function call another. A loop body whose allocations do not escape the iteration is wrapped with the same record-and-rewind pair, so its peak memory stays bounded by one iteration’s footprint.
  • A constant-size array buffer of at least 2 MiB is routed through the runtime’s huge-page allocator (mmap plus the huge-page hint) on Linux. Single objects are not. The compile-time decision and the runtime use the same threshold constant, so they cannot drift.
  • The Shared<T> 16-byte refcount header is allocated contiguously with its payload (one allocation, not two), so a shared object behaves like a plain pointer through the rest of the pipeline. Header offsets are baked into the access patterns at compile time.

Limitations

The analysis is a proof, not a guess: when it cannot prove an object does not escape, it sends the object to the next tier up. What it refuses to decide is enumerated under Restrictions: call an unknown function, store through a raw pointer, hand the object to a spawn, and the object leaves the cheap tier rather than being miscompiled.

Two consequences are worth stating here, because they are permanent:

  • The tier is a result, not a promise. Two versions of the same source may place an object differently as the analysis improves; correctness does not depend on which tier a program got.
  • You cannot request a tier. There is no annotation that pins an object to the stack or the arena — only the workarounds the analysis recognises (share new T[n] for a shared array, a constant-size T[N] buffer, and so on).

Limits / Uncabled

FeatureStateDetail or workaround
Choosing a tier with an annotationNot provided.Write the plain new T(...); the analysis picks.
Stack promotion across a call to a function whose parameter may retain its argumentRefused: the argument counts as escaping.Take the parameter borrowed (the default), which the callee cannot retain. An own parameter transfers the object and therefore escapes.

See also

memoryescape-analysisstackoptimization