51ff558904
Phase 32 L-2.1 complete implementation: 1. Stage-1 UsingResolver main line JoinIR connection - CFG-based LoopForm construction for resolve_for_source/5 - LoopToJoinLowerer integration with handwritten fallback - JSON snapshot tests 6/6 PASS 2. JoinIR/VM Bridge improvements - Simplified join_ir_vm_bridge.rs dispatch logic - Enhanced json.rs serialization - PHI core boxes cleanup (local_scope_inspector, loop_exit_liveness, loop_var_classifier) 3. Stage-1 CLI enhancements - Extended args.rs, groups.rs, mod.rs for new options - Improved stage1_bridge module (args, env, mod) - Updated stage1_cli.hako 4. MIR builder cleanup - Simplified if_form.rs control flow - Removed dead code from loop_builder.rs - Enhanced phi_merge.rs 5. Runner module updates - json_v0_bridge/lowering.rs improvements - dispatch.rs, selfhost.rs, modes/vm.rs cleanup 6. Documentation updates - CURRENT_TASK.md, AGENTS.md - Various docs/ updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
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_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.
|