tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
4f0ffae70dbdb4e8ad5299dd00e6b71625cb87d0
hakorune/docs/reference/runtime/gc.md
nyash-codex 51ff558904 feat(phase32): L-2.1 Stage-1 UsingResolver JoinIR integration + cleanup 
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>
2025-11-26 10:17:37 +09:00

3.2 KiB
Raw Blame History

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.