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.
|