← Back to AILP Home

Memory regions

Nitpick gives you explicit control over where a value lives, separate from how the borrow checker tracks aliasing. This guide explains the five memory regions, when to use each, and how they interact with the borrow checker, the # pin operator, and wild/wildx interop.

Quick reference

Region Keyword Backing Lifetime
Default (none) LLVM alloca function frame
Stack stack LLVM alloca function frame
GC heap gc npk_gc_alloc until unreachable, then collected
Wild heap wild npk_alloc (manual) user-managed
Wildx wildx npk_alloc_exec (W^X) user-managed

Chapters

  1. Regions — the five regions in detail, with examples.
  2. Stack — the default region: when, why, and what escapes it.
  3. GC — gc heap allocation, generational mark-sweep, safepoints, auto-pinning, shadow-stack rooting.
  4. Wild — wild / wildx manual heap, FFI, and the leak/use-after-free diagnostics that catch the obvious mistakes.
  5. Pointers and FFI ABI — T->, @, <-, p->field, pointer arithmetic gates, NULL failsafe sentinel 46, and the C ABI table for scalar/struct/erased/function-pointer shapes.
  6. Pinning — #x, what it does per region, and the pin-derived alias rules.
  7. Tuning — runtime knobs (NPK_GC_NURSERY_SIZE, NPK_GC_OLD_GEN_THRESHOLD, NPK_GC_MODE).
  8. Interop — GC ↔ wild / wildx invariants and the npk_shadow_stack_add_root escape hatch.
  9. Diagnostics — the memory-region diagnostic codes (ARIA-014, ARIA-015, ARIA-028, ARIA-029, ARIA-031, ARIA-032, ARIA-065, ARIA-066, ARIA-067) — what they mean and how to fix the most common cases.
  10. Cross-region safety — practical walkthrough of ARIA-029 and ARIA-031: recogniser shapes, the if-arm asymmetry, and the documented workarounds (copy-by-value, pin, promote-to-gc) with K-runtime parity tests.
  11. FAQ — short answers to recurring questions about regions, the borrow checker, the GC, and FFI.

For the handle subsystem (generation-checked arena allocation, Handle<T>, ARIA-032), see the separate guide/handles/ cookbook — including the v0.30.x cross_module chapter on how ARIA-032 flows across use boundaries. For runtime code generation on top of wildx, see the guide/jit/ cookbook. For the opt-in RAII layer that auto-frees wild / wildx / HandleArena / JitFn bindings at scope exit, see the guide/drop/ cookbook (v0.29.x).

Validation snapshot (v0.32.6 — pointer/cast cycle close)