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.
- 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
mallocever runs. This pass runs first because it produces the smallest IR shape for every pass after it. - 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.
| Strategy | When it is chosen | What is emitted |
|---|---|---|
StackAlloca | A 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. |
LibcCalloc | Constant 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. |
HugeCalloc | Same 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. |
LibcMalloc | A 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. |
HugeAlloc | A 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. |
ArenaBump | A 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. |
SharedAlloc | Shared<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. |
StdlibFfiHandle | new 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 theaxle_common::limitstable, 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 (
mmapplus 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-sizeT[N]buffer, and so on).
Limits / Uncabled
| Feature | State | Detail or workaround |
|---|---|---|
| Choosing a tier with an annotation | Not provided. | Write the plain new T(...); the analysis picks. |
| Stack promotion across a call to a function whose parameter may retain its argument | Refused: 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
- Memory model — the user-facing tier
rules and
defer. - Memory placement — the
optimisation-lens summary (stack > arena > heap, plus the opt-in
Shared<T>tier) in the full census of compiler optimisations. - Loop and idiom rewrites — the other rewrite passes that touch allocations.
- Refcount and transitions — the other deep-dive page in this section.
- Compiler internals overview — index of all internals pages.
- Concept index — every memory concept on one page.