56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
|
# Phase 20.9 — Hakorune‑Driven C ABI (Script First)
|
|||
|
|
|
|||
|
|
Status
|
|||
|
|
- Planning & scaffolding. No behavior change until gates are enabled.
|
|||
|
|
|
|||
|
|
Goals
|
|||
|
|
- Hakorune→LLVM line can call C ABI directly (Rust optional). Start with GC observability; expand carefully.
|
|||
|
|
|
|||
|
|
Gates
|
|||
|
|
- Default OFF. Enable via environment/test gates only (no behavior change unless explicitly gated).
|
|||
|
|
|
|||
|
|
Milestones
|
|||
|
|
|
|||
|
|
## 1) ABI Surface (script→C)
|
|||
|
|
- [x] Define symbol mapping (read‑only GC): `env.gc.stats/0` → `hako_gc_stats`, `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot` (see ABI_MAP.md)
|
|||
|
|
- [x] Header prototypes (memory API): `hako_mem_alloc/realloc/free`
|
|||
|
|
- [x] Header ownership note: `hako_gc_stats()` returns `char*` to be freed by `hako_mem_free()`
|
|||
|
|
- [x] (Docs) Alignment guarantee and thread-safety note for memory API — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
|
|||
|
|
- [x] (Docs) TLV/flat ABI notes for future control hooks and utilities — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
|
|||
|
|
- [x] Diagnostics policy: NOT_FOUND/UNSUPPORTED/VALIDATION short lines remain mandatory
|
|||
|
|
|
|||
|
|
## 2) LLVM Lowering (llvmlite)
|
|||
|
|
- [x] Lower `env.gc.stats/0` → `hako_gc_stats` (bridge i8* → handle)
|
|||
|
|
- [x] Lower `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot`
|
|||
|
|
- [x] Free boxed C string via `hako_mem_free` after boxing (leak防止)
|
|||
|
|
- [ ] (Optional) Provide `from_i8_string_take(i8*)` to elide a free (future)
|
|||
|
|
- [x] Canary smokes prepared under gate (see SMOKES.md)
|
|||
|
|
|
|||
|
|
## 3) Control Hooks (gated)
|
|||
|
|
- [x] Registry entries added for `env.gc.{collect,start,stop}` (SSOT only)
|
|||
|
|
- [x] Lowering: implement as no‑op or explicit FAIL under gate (no silent fallback)
|
|||
|
|
- [x] (Docs) Gate: `NYASH_LLVM_GC_CONTROL_FAIL=1` → emit stable message via debug trace and return 0 (dev only)
|
|||
|
|
|
|||
|
|
## 4) Policy Box (Hakorune)
|
|||
|
|
- [x] GcBox skeleton and `policy_tick()` example (dev only)
|
|||
|
|
- [ ] Cadence thresholds and logging templates (doc + sample)
|
|||
|
|
|
|||
|
|
## 5) Parity & Safety
|
|||
|
|
- [x] VM↔LLVM parity for read‑only GC externs (shape equality)
|
|||
|
|
- [x] Diagnostics parity (short lines + details) for missing handlers/symbols
|
|||
|
|
|
|||
|
|
## 6) C Shim (libc first)
|
|||
|
|
- [x] Implement `hako_mem_alloc/realloc/free` (libc backed)
|
|||
|
|
- [x] Implement `hako_gc_stats` / `hako_gc_roots_snapshot` (read‑only, minimal JSON/int)
|
|||
|
|
- [x] Platform notes (Windows/Unix CRT differences) — prefer `hako_mem_free` only
|
|||
|
|
|
|||
|
|
Docs
|
|||
|
|
- [x] hakorune-c-abi-bridge.md (this plan)
|
|||
|
|
- [x] gc/llvm-extern-plan.md (GC read‑only path first)
|
|||
|
|
- [x] gc/policy-vs-data-plane.md (separation)
|
|||
|
|
- [x] phase-20.9/ABI_MAP.md（extern→C symbol）
|
|||
|
|
- [x] phase-20.9/SMOKES.md（LLVM canary）
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
- Keep gates OFF by default. Roll out in small, reversible steps.
|