Memory Model

Value representation

Every Karkain value is a tagged union (Value) with one of the following type tags:

TYPE_INT

64-bit signed integer, stored unboxed.

TYPE_FLOAT64

64-bit IEEE 754 double, stored unboxed.

TYPE_BOOL

true / false.

TYPE_STRING

Length-prefixed UTF-8 byte array (heap-allocated, managed by the runtime).

TYPE_ARRAY

Dynamic array of Value pointers (heap-allocated, managed by the runtime).

TYPE_STRUCT

Map-based container — field names are string keys.

TYPE_OPTION

Tagged wrapper: some(value) or none.

TYPE_RESULT

Tagged wrapper: ok(value) or err(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_map create heap cells.

  • karkain_memory.c provides the arena allocator (karkain_arena_alloc / karkain_arena_reset).

  • karkain_mem.c provides 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.