docs/ci: selfhost bootstrap/exe-first workflows; add ny-llvmc scaffolding + JSON v0 schema validation; plan: unify to Nyash ABI v2 (no backwards compat)
This commit is contained in:
Selfhosting Dev
96
docs/reference/mir/json_v0.schema.json
Normal file
96
docs/reference/mir/json_v0.schema.json
Normal file
@ -0,0 +1,96 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://nyash.dev/schema/mir/json_v0.schema.json",
|
||||
"title": "Nyash MIR JSON v0",
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"schema_version": { "type": ["integer", "string" ] },
|
||||
"functions": {
|
||||
"oneOf": [
|
||||
{ "$ref": "#/definitions/functionList" },
|
||||
{ "$ref": "#/definitions/functionMap" }
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": ["functions"],
|
||||
"definitions": {
|
||||
"functionList": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/function" }
|
||||
},
|
||||
"functionMap": {
|
||||
"type": "object",
|
||||
"additionalProperties": { "$ref": "#/definitions/functionBody" }
|
||||
},
|
||||
"function": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"params": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"type": { "type": "string" }
|
||||
},
|
||||
"required": ["name", "type"]
|
||||
}
|
||||
},
|
||||
"return_type": { "type": "string" },
|
||||
"entry_block": { "type": ["integer", "string"] },
|
||||
"blocks": { "$ref": "#/definitions/blocks" }
|
||||
},
|
||||
"required": ["name", "blocks"]
|
||||
},
|
||||
"functionBody": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"params": { "$ref": "#/definitions/function/properties/params" },
|
||||
"return_type": { "type": "string" },
|
||||
"entry_block": { "type": ["integer", "string"] },
|
||||
"blocks": { "$ref": "#/definitions/blocks" }
|
||||
},
|
||||
"required": ["blocks"]
|
||||
},
|
||||
"blocks": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/block" }
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"additionalProperties": { "$ref": "#/definitions/block" }
|
||||
}
|
||||
]
|
||||
},
|
||||
"block": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"id": { "type": ["integer", "string"] },
|
||||
"instructions": { "$ref": "#/definitions/instructions" },
|
||||
"terminator": { "$ref": "#/definitions/instruction" }
|
||||
},
|
||||
"required": ["id", "instructions"]
|
||||
},
|
||||
"instructions": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/instruction" }
|
||||
},
|
||||
"instruction": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"kind": { "type": "string" }
|
||||
},
|
||||
"required": ["kind"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
62
docs/reference/runtime/gc.md
Normal file
62
docs/reference/runtime/gc.md
Normal file
@ -0,0 +1,62 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user