docs / composition

fx Â· 0.9.0

Composition under regions

How to build real programs in fx without treating it as a GC language â€” and without an unsafe dialect.

Package markdown: docs/COMPOSITION.md. Dual-emit tracking â†’ Tracking.

Lane A â€” the fx method (default)

Effects visible (alloc / mut / io)
Named regions as memory epochs (no GC)
Grow by reassignment: v = vec_push(v, x)
Prefer indices over pointers into growing storage
Slot update: vec_set(v, i, x) or no-grow v[i] = x (requires mut) â€” does not reallocate
Fixed tables: arrays + &mut [T]
Pools: std/pool + typed Id (lib/id_pool)
Map accumulate: map_add_i32 / std/map.add_i32

There is no unsafe path. Convenience helpers and Growing/Frozen phase types were skipped â€” prefer ids, pools, and SoA.

Patterns

fx run examples/pattern_ids/main.fx
fx run examples/pattern_mut_table/main.fx
fx run examples/pattern_grow_freeze/main.fx
fx run examples/pattern_pool/main.fx
fx run examples/pattern_ring/main.fx

Composition example programs

fx run examples/composition_tally/main.fx   # multi-pass Map add_i32 â†’ 42
fx run examples/composition_reach/main.fx   # typed Id pool + BFS â†’ 42
fx run examples/cap_host_smoke/main.fx      # host mints read; guest has no io â†’ 42

Prefer parallel Vecs + typed ids (SoA). Host-minted I/O keeps authority at the C boundary.

Related

Surface map â€” what exists today
Regions â€” effects and region kinds
Tracking â€” map C back to fx