`mem`

Memory management - box any value into a mutable reference with ptr, create explicit unsafe guard tokens, and manage a pure-ilusm mark-and-sweep GC arena: allocate objects with numeric IDs, declare reference edges, mark roots, synchronously collect, step incrementally with a budget, run GC concurrently or incrementally in a background task, tune pause time and step budget, and call host process-GC hooks.

Load with: use mem

What this module does

mem bridges the high-level (ptr boxes, uns guards) and the low-level (a pure-ilusm mark-and-sweep arena). The arena is a data structure - an object tracking allocated IDs, reference edges, roots, and GC state - that you manage explicitly. This is useful for implementing custom object graphs, caches, or any structure that needs deterministic reclamation without relying solely on the host GC.

The incremental and concurrent variants let you amortise GC pauses by spreading work across many small steps or running the collector in a background task via syn.spawn.

Quick example

use mem

# Box a value
box = mem.box(42)       # same as ptr.new(42)

# Unsafe guard
g = mem.unsafe("my_block")  # same as uns.guard("my_block")

# Mark-and-sweep arena
ar = mem.gc_new()

id1 = mem.gc_put(ar, {name: "root_node"})
id2 = mem.gc_put(ar, {name: "child_node"})

mem.gc_root(ar, id1)       # mark id1 as a GC root
mem.gc_ref(ar, id1, id2)   # declare id1 → id2 edge

freed = mem.gc_collect(ar) # synchronous full collection
prn(freed)  # 0 (both reachable)

# Incremental collection (budget: 50 steps per tick)
mem.gc_tune(ar, 0, 50)
whl !mem.gc_done(ar):
    mem.gc_step(ar)

# Concurrent GC in background
task = mem.gc_concurrent(ar)

# Host process GC
mem.proc_run()
prn(mem.proc_stats())

Functions

High-level helpers

membo(v) / mem.box(v)

Creates a ptr box holding v.

memun(tag) / mem.unsafe(tag)

Creates an uns guard token with the given tag string.

memmo() / mem.model()

Returns a description string of the memory model.

Arena lifecycle

memgcnew() / mem.gc_new()

Creates a fresh GC arena object.

memgcput(ar, v) / mem.gc_put(ar, v)

Allocates v in the arena. Returns a numeric ID.

memgcref(ar, a, b) / mem.gc_ref(ar, a, b)

Declares a reference edge from ID a to ID b.

memgcrt(ar, id) / mem.gc_root(ar, id)

Marks ID as a GC root (always reachable).

memgcdrop(ar, id) / mem.gc_drop(ar, id)

Removes an ID from the arena immediately.

Collection

memgcsyn(ar) / mem.gc_collect(ar)

Synchronous mark-and-sweep. Returns the number of freed objects.

memgcstp(ar) / mem.gc_step(ar)

Performs one incremental GC step up to the configured budget. Returns freed count for that step.

memgcfin(ar) / mem.gc_done(ar)

Returns tru if an incremental collection cycle is complete.

memgcrst(ar) / mem.gc_reset(ar)

Resets incremental GC state without collecting.

memgctun(ar, pause_ms, budget) / mem.gc_tune(ar, ms, bud)

Sets the pause between incremental steps (ms) and the step budget (number of nodes per step).

memgccon(ar) / mem.gc_concurrent(ar)

Runs a full collection as a concurrent task via syn.spawn. Returns the task handle.

memgcinc(ar) / mem.gc_incremental(ar)

Runs the full incremental collection loop in a background task, sleeping pause_ms between steps.

Host process GC

memprrun() / mem.proc_run()

Triggers the host process GC via __mem_gc_proc_run.

memprstats() / mem.proc_stats()

Returns host GC stats via __mem_gc_proc_stats.

memprtune(pause_ms, step_mx, conc) / mem.proc_tune(…)

Tunes the host GC via __mem_gc_proc_tune.

memprspawn() / mem.proc_spawn()

Spawns the host GC run in a concurrent task.

memprwait(t) / mem.proc_wait(t)

Waits for a previously spawned GC task.

Notes

Requires trl, ptr, uns, syn, and eru.