Memory

Atoll uses several cooperating memory layers. Calling all of them “the heap” hides the rules that make values relocatable, asynchronous I/O safe, and Unit instances independently disposable.

WebAssembly linear memory
└─ link-group allocator
   └─ Unit instance backing allocation
      ├─ FlatBuilderHeader
      └─ RuntimeArena body
         ├─ RuntimeArena header
         ├─ values and collection blocks
         ├─ task control blocks
         ├─ continuation frames
         └─ scheduler nodes

The link-group allocator obtains raw ranges from WebAssembly linear memory. A Unit instance owns one of those ranges as its arena. The arena allocator starts as a bump allocator and can promote itself to TLSF when arbitrary reclamation becomes useful. Atoll values inside the arena use flat, offset-based layouts.

This chapter describes the current WebAssembly runtime implementation. Layouts and generated-code interactions are runtime ABI contracts. Allocation thresholds and growth heuristics are implementation policy unless a page says otherwise.

Core rules

The memory model rests on six rules:

1. A Unit instance owns a persistent arena. It is not recreated for every function call or every invocation.
2. An arena-relative offset is the durable address of in-arena data. A native pointer into WebAssembly memory is temporary.
3. Offset 0 is null or the empty niche. Valid allocations therefore have nonzero offsets.
4. Relocating an arena changes its absolute address but preserves its internal offsets.
5. Compiler-inserted ownership operations reclaim ordinary acyclic data. Precise tracing handles compiler-identified cycles.
6. Destroying or poisoning a Unit instance releases its complete arena as one backing allocation.

Memory layers

Host resources such as sockets and database handles are not stored inside the arena. The arena contains compact handles; the runtime keeps the corresponding host objects in a generation-checked slab.

Addressing

Generated code normally manipulates a u32 offset relative to the arena body:

absolute Wasm address = current arena body base + arena-relative offset

The runtime republishes the body base after growth. Code that materializes a raw address must not retain it across an operation that can grow, suspend, or otherwise relocate the arena. A generation counter lets generated and host code detect that a previously materialized address belongs to an older arena generation.

The u32 offset representation imposes a design ceiling of 4 GiB for one arena. Runtime configuration and allocation checks may impose smaller practical limits.

Lifetimes

The arena contains data with different logical lifetimes:

• invocation frames and scheduler bookkeeping are temporary;
• Unit state and reachable values can survive across invocations;
• asynchronous operations can keep arena ranges live across suspension;
• retired arena generations survive only while an operation has pinned them.

The distinction matters during cleanup. Normal invocation completion releases the temporary frame region, but the Unit instance and its arena remain cached. Termination can leave frames and reference counts indeterminate, so a poisoned instance is evicted wholesale instead of attempting ordinary destructor execution.

Read next

• Arenas defines the physical arena, growth, and generation protocol.
• Flat Values defines the layouts stored in an arena.
• TLSF explains promotion, size classes, splitting, coalescing, and deferred reclamation.
• Ownership connects compiler ownership modes, reference counting, reuse, and cycle collection.
• Units explains why each Unit instance owns an arena.
• Host I/O explains how suspended operations borrow or pin arena memory.

Implementation

The primary implementation is in atoll-flat, atoll-flat-wasm, atoll-runtime-abi, and atoll-runtime-wasm. Generated layouts remain authoritative when an older design document disagrees with compile-time size or offset assertions.