Memory Model
Value representation
Every Karkain value is a tagged union (Value) with one of the
following type tags:
TYPE_INT64-bit signed integer, stored unboxed.
TYPE_FLOAT6464-bit IEEE 754 double, stored unboxed.
TYPE_BOOLtrue/false.TYPE_STRINGLength-prefixed UTF-8 byte array (heap-allocated, managed by the runtime).
TYPE_ARRAYDynamic array of
Valuepointers (heap-allocated, managed by the runtime).TYPE_STRUCTMap-based container — field names are string keys.
TYPE_OPTIONTagged wrapper:
some(value)ornone.TYPE_RESULTTagged wrapper:
ok(value)orerr(message).
Equality is value-level — values_equal compares by type tag and
contents, not by pointer identity.
Ownership
Karkain uses lexical-scope ownership (Borrow Checker, Phase 51):
Variables own the values they bind.
Ownership transfers on re-binding or scope exit.
Dead-name analysis prevents use after scope end.
There is no runtime reference counting or garbage collector — heap containers (strings, arrays, maps) are managed by the C runtime’s arena allocator (Phase 101/102).
Heap-managed containers
Strings, arrays, and maps are heap-allocated:
make_string/make_array/make_mapcreate heap cells.karkain_memory.cprovides the arena allocator (karkain_arena_alloc/karkain_arena_reset).karkain_mem.cprovides a coalescing free-list allocator on top of the arena (karkain_mem_alloc/karkain_mem_free).
Concurrency (Phase 107)
The concurrency runtime adds:
Work-stealing task scheduler — fixed pool of workers, bounded grab queue, per-worker wake condvar.
Bounded/unblocking channels —
channel(),chanSend(),chanClose(),receive().Actors — serialised mailbox dispatch with state cell.
All concurrency primitives are implemented in C
(runtime/concurrency/c/) and embedded into generated assemblies.
Stack frames
Each function call pushes a frame onto the C call stack. The maximum
depth is KARKAIN_MAX_FRAMES (128). karkain_frame_enter /
karkain_frame_leave bookend every function body and power the stack
trace on runtime errors.