hakorune/docs/reference/runtime/gc.md

Nyash GC Modes — Design and Usage

Overview

• Nyash adopts a pragmatic GC strategy that balances safety, performance, and simplicity.
• Default is reference counting with a periodic cycle collector; advanced modes exist for tuning and debugging.

User‑Facing Modes (recommended)

• rc+cycle (default, safe)
  • Reference counting with periodic cycle detection/collection.
  • Recommended for most applications; memory leaks from cycles are handled.
• minorgen (high‑performance)
  • Lightweight generational GC: moving nursery (Gen‑0), non‑moving upper generations.
  • Write barrier (old→new) is minimal; plugin/FFI objects remain non‑moving via handle indirection.

Advanced Modes (for language dev/debug)

• stw (debug/verification)
  • Non‑moving stop‑the‑world mark‑and‑sweep. Useful for strict correctness checks and leak cause isolation.
• rc (baseline for comparisons)
  • rc+cycle with cycle detection disabled. For performance comparisons or targeted debugging.
• off (expert, self‑responsibility)
  • Cycle detection and tracing off. Use only when cycles are guaranteed not to occur. Not recommended for long‑running services.

Selection & Precedence

• CLI: --gc {auto,rc+cycle,minorgen,stw,rc,off} (auto = rc+cycle)
• ENV: NYASH_GC_MODE (overridden by CLI)
• nyash.toml [env] applies last

Instrumentation & Diagnostics

• NYASH_GC_METRICS=1: print brief metrics (allocs/bytes/cycles/pauses)
• NYASH_GC_METRICS_JSON=1: emit JSON metrics for CI/aggregation
• NYASH_GC_LEAK_DIAG=1: on exit, dump suspected unreleased objects (Top‑K by type/site)
• NYASH_GC_ALLOC_THRESHOLD=<N>: warn or fail when allocations/bytes exceed threshold

Operational Guidance

• Default: rc+cycle for stable operations.
• Try minorgen when throughput/latency matter; it will fall back to rc+cycle on unsupported platforms or when plugin objects are declared non‑moving.
• off/rc are for special cases only; prefer enabling leak diagnostics when using them in development.

Implementation Roadmap (Step‑wise)

1. Wiring & Observability
   • Introduce GcMode, GcController, unify roots (handles, globals, frames) and safepoints.
   • Add LeakRegistry (allocation ledger) and exit‑time dump.
   • Ship rc+cycle (trial deletion) behind the controller (dev default can be rc+cycle).
2. minorgen (nursery)
   • Moving Gen‑0 with simple promotion; upper generations non‑moving mark‑sweep.
   • Minimal write barrier (old→new card marking). Plugin/FFI remain non‑moving.
3. stw (dev verify)
   • Non‑moving STW mark‑and‑sweep for correctness checks.

Notes

• Safepoint and barrier MIR ops already exist and are reused as GC coordination hooks.
• Handle indirection keeps future moving GCs compatible with plugin/FFI boundaries.

LLVM Safepoints

• Automatic safepoint insertion can be toggled for the LLVM harness/backend:
  • NYASH_LLVM_AUTO_SAFEPOINT=1 enables insertion (default 1)
  • Injection points: loop headers, function calls, externcalls, and selected boxcalls.
  • Safepoints call ny_check_safepoint/ny_safepoint in NyRT, which forwards to runtime hooks (GC.safepoint + scheduler poll).

Controller & Metrics

• The unified GcController implements GcHooks and aggregates metrics (safepoints/read/write/alloc).
• CountingGc is a thin wrapper around GcController for compatibility.