Runtime

The Atoll runtime executes compiler-generated continuation code, isolates live Unit instances, owns their arenas and host resources, and connects local execution to debugging, deployment, and optional Raft-replicated services.

This section documents the current implementation. It distinguishes frozen ABI layouts from changeable policy and calls out incomplete subsystems where the repository contains design substrate but not an end-to-end guarantee.

Mental model

Program
├─ immutable link-group artifacts
├─ Unit manifest and ABI metadata
└─ Store fleet
   └─ Store reactor
      ├─ Wasmtime Store
      │  └─ link-group Instances and memories
      └─ UnitInstance cache
         ├─ persistent arena
         ├─ root task tree
         ├─ invocation frames
         └─ host I/O and resources

The most important distinctions are:

A runtime Unit instance is not a Wasm Instance, and an arena is not a per-function scratch buffer. Those two distinctions explain most of the runtime’s routing, memory, and migration behavior.

Execution

• Architecture defines Program, group, Store, routing, concurrency, and failure boundaries.
• Units defines Unit and Unit-instance identity, placement, lifecycle, eviction, and migration.
• Execution follows one invocation through CPS scheduling, task trees, suspension, cancellation, and completion.
• ABI records exact frame, TCB, stream, tag, and method-entry layouts.
• Host I/O explains operation slots, resource handles, buffer pinning, and cancellation.

Memory

Memory introduces the complete memory hierarchy:

• Arenas covers physical layout, builders, growth, relocation, generations, snapshots, and failure cleanup.
• Flat Values covers canonical offset-based value and collection layouts.
• TLSF covers bump-mode promotion, size classes, splitting, coalescing, and verification.
• Ownership covers compiler ownership modes, reference counting, reuse, and precise cycle collection.

Operations

• Deployment covers link-group topology, atomic cutover, selective Store replacement, state-preserving redeploy, migration, and draining.
• Debugger covers DAP sessions, source safepoints, continuation-aware stepping, paused-instance isolation, stacks, and variables.
• Clustering covers Raft proposals, database apply, follower forwarding, watermarks, subscriptions, and current limitations.

Guarantees

The runtime provides:

• single-mutator execution for one Unit instance;
• bounded invocation and cluster-writer queues;
• arena-relative state that survives memory relocation;
• explicit suspension and resume through generated continuations;
• generation-checked host resource handles;
• isolated Program snapshots during redeploy;
• explicit compatibility rejection for unsafe state migration.

The runtime does not turn instance memory into durable storage, make local singleton placement cluster-wide, or roll back arbitrary external effects after timeout or cancellation.

Status language

Pages use these terms consistently:

• ABI contract means compiler and runtime must change together.
• runtime invariant means the implementation depends on the property for correctness.
• policy means a configurable or replaceable current choice.
• current limit means the end-to-end behavior is not implemented even when supporting types or design documents exist.

In particular, clustering currently recovers through log replay rather than nonempty Raft snapshots, and workflow event-await integration is incomplete.

Sources

The primary implementations are atoll-runtime-abi, atoll-runtime, atoll-runtime-wasm, atoll-flat, atoll-flat-wasm, atoll-dap, and atoll-cluster. Generated layout constants and compile-time assertions take precedence over stale legacy documentation.