Decision D026 · accepted
The runtime and the C backend for stage B
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15). Research: reports/Runtime and C backend design.md, whose decision table numbers are given in brackets.
The approach
The runtime and the C backend follow the design Koka and Lean 4 have proven: direct-style C, one C function per definition, a context pointer as the first argument of every call, a status checked after calls that may unwind, values as 64-bit tagged words, precise reference counting with reuse (D004). Three changes come from what Diaspar has and they do not: the moment a value dies is observable through release (D023), and types and globals are redefined live (D003, D010). Those three changes (the normative liveness rule, a type id per type version, a retire list for old globals) have no precedent and are prototyped and measured first.
Decisions for milestone B1 (accepted)
- Value word [2]. 64 bits with low-bit tags: pointers end in
000; 63-bit immediate integers; constants (nil, booleans) under their own tag; two tags reserved. Integers between 2⁶² and 2⁶³ are boxed, so D013's rule (an error only beyond 64 bits) holds. Floats are boxed in the first version and unboxed in typed locals. - Header and count [3]. 8 bytes: a 32-bit count and a 32-bit type id. The count follows Lean: 1 is unique, 0 is immortal (constants and literals, never counted), negative is shared between threads and updated atomically, with a sticky band against overflow. The type id has 28 bits plus 4 flags.
- Type ids [4]. Each type version and each variant has its own id; descriptors live in a table that only grows. Field access compares the id and takes the cached offset, else looks the field up by name (D010), so old values stay readable after a redefinition. Reuse in place rewrites the id.
- Strings and vectors [6]. Strings are UTF-8 with an "only ASCII" flag, so
countis O(1) for ASCII text (D013); no small-string optimization; slices copy. Vectors are flat arrays updated in place when unique; tries only if profiling asks for them. - One liveness rule [7]. The last-use rule of the bootstrap (
bootstrap/src/analyze/liveness.rs) is ported once and is part of the language definition: the interpreter and the compiler's reference-counting pass share it, soreleasefires at the same place in both. Drops of values that may implementReleaseare never moved. - Calling convention [9]. The context pointer first; direct calls at known arities; a uniform closure entry with four register arguments and a spill area in the context; arguments are owned.
- Unwinding [10]. The status lives in the context and is checked after calls that may unwind (always after calls through cells in development builds), with cleanup labels that cascade; no
setjmp/longjmp, which would skip reference counts. Nim measured this style at about two instructions per call, on par with C++ exception tables. - The restricted context [12] (answers D002's open question). The compiler infers properties of code after reference-counting operations are inserted (whether it may allocate, free, switch fibers, lock, or reach
Unsafe); attributes in the source state upper bounds checked against them. A violation is an error in runtime modules and in modules that importstd.unsafe, a warning elsewhere. The restrictions:no-managed(no allocation and no freeing, since a drop may free),no-alloc,no-switch,signal-safe. An escape hatch,assume, requires a written reason and is checked by assertions in debug builds. These properties are not algebraic effects: no handler could give "allocates" a meaning. Precedents: OxCaml's[@zero_alloc], Clang's function effects, Swift's performance annotations, Go's runtime directives, Ferron's#[no_managed]. - Allocator for stage B [13]. libc
mallocor mimalloc through FFI; an allocator written in Diaspar after self-hosting. - Debug information [16].
#lineper form (switchable), reversible name mangling, a ring buffer of recent frames in development builds for traces. - Build layout [17]. One
.cfile per module, an object cache keyed by content hashes, parallelcc.
Tail calls [1] (accepted)
Only loop/recur is guaranteed to run in constant stack (since 2026-11-17: loop with continue, and a function's call to itself in tail position, D034); it compiles to goto and works with every C compiler. Other calls in tail position use musttail as an optimization where the C compiler supports it and the signatures match, but they are not a promise of the language. The backend needs no trampoline mode, the seed needs no musttail, and the interpreter and the compiler agree. The compiler warns about a function that calls itself in tail position without recur ("use recur to guarantee constant stack"). A guarantee can be widened later (the uniform closure signature keeps general tail calls possible) but never narrowed; mutual recursion can use a trampoline helper, as in Clojure.
Cells and guarded direct calls [11] (accepted)
Each global definition has a cell {entry0..entry3, entryN, value, version}; a call site compiled for two arguments calls entry2, and a redefinition that drops an arity points that entry to a stub that raises an arity error.
Calls are guarded direct calls: the call site compares the cell's version with the version it was compiled against and, if they match, calls the function directly, which the C compiler can inline; otherwise it calls through the cell. This is the speculative devirtualization JIT compilers and C++ compilers use.
// (vec-add a b)
if (likely(vec_add_cell.version == 7))
result = vec_add_v7(ctx, a, b); // direct, inlinable
else
result = vec_add_cell.entry2(ctx, a, b); // redefined since: through the cell
- Every function is redefinable in every build, with no annotations and no difference between development and release; an inlined copy of an old version never runs after a redefinition, because the guard fails. This keeps the live environment (D001, D018) in release builds.
- The cost is a load, a compare, and a predicted branch per call, plus the slow branch's code size; inlining across modules still needs LTO, as in any option. It is measured on the C backend (a hot loop against a plain direct call and a plain cell call); if it proves too expensive, Clojure-style direct linking with
^:redefinableopt-outs uses the same cell ABI. diaspar build --sealedremoves the guards for the whole program: calls are plain direct calls, and redefining anything in a sealed program is an error, never silently ignored.- Old code that may still be on the stack is never unmapped during a session.
Rejected: always calling through cells (no inlining, a real cost for games and numeric code); Clojure's direct linking with ^:redefinable (two behaviours, development and release, and redefinition that silently does nothing when an annotation was forgotten); ^:inline opt-ins (hot functions found by hand).
Stack overflow (accepted, 2026-11-16)
Every compiled function checks the stack pointer on entry against a limit kept in the context, as Go's and OCaml 5's prologues do: one comparison, sp < ctx->stack_limit. Crossing it raises Diaspar's ordinary "stack overflow" error through the status ([10]), so it unwinds, runs cleanup, and can be caught, as in the interpreter. Depth is measured in bytes rather than calls, so the exact call at which it happens differs from the interpreter's 10,000 calls; the error text is the same. Since recur is the only guaranteed tail call ([1]), deep recursion is ordinary: main runs on a large stack (64 MB, on its own thread), with the limit set below its end. Rejected: a depth counter on every call (a cost on every call), and only a guard page with a signal handler (Rust's way: free, but the error can only abort the process, not be caught).
Later
For B2 and self-hosting: map and set order [5], release errors at drops [8], borrowing [14], reuse [15], the seed format [18]. For stage D: globals under redefinition [19], the cycle collector [20], fibers [21], the native REPL tier [22].