Skip to content

Minimize the interpreter: remove fast-plan machinery, unify variable storage - #10

Open
t04dJ14n9 wants to merge 4 commits into
cursor/gig-code-cleanup-2d21from
cursor/gig-unify-frame-storage-2d21
Open

t04dJ14n9 wants to merge 4 commits into
cursor/gig-code-cleanup-2d21from
cursor/gig-unify-frame-storage-2d21

Conversation

@t04dJ14n9

@t04dJ14n9 t04dJ14n9 commented Aug 13, 2026 •

Copy link
Copy Markdown
Owner

Goal

Make the interpreter minimal and easy to understand, accepting reduced throughput on synthetic numeric loops. Breaking internal changes are fine. Variable storage is a single []Cell per frame throughout.

Stacked on cursor/gig-code-cleanup-2d21 (PR #9); review that first.

1. Unify variable storage into a single []Cell

Previously the frame used a dense slots array plus a lazy cells map (the map held only Alloc results). Now every SSA value — including Alloc — gets a slot and the cells map is removed (proven dead by asserting no writes across the full -race suite). cell/setCell/bindCell are slot-only; closures are unaffected because runMakeClosure snapshots into fresh Cells.

2. Remove the fast-plan ("block plan") machinery

Deleted the entire fast-path layer that made the hot loop hard to follow:

  • fast_plan.go (typed int/bool fast instructions, fast phis, fused IndexAddr plans, whole-block fast loop) — deleted.
  • runFrame is now a single loop: resolve block Phis, then visitInstr per instruction. runBlockPhis has only the generic path.
  • frameLayout reduced to a plain map[ssa.Value]int (no struct wrapper, no slotKinds/blockPlans/fusedIndexAddr).
  • Cell drops the typed cache (fastInt/fastBool/fastDirty); setSlotValue/materializeSlot gone.
  • Removed the fused IndexAddr optimization; the generic path handles it. (isPlainIntSliceType stays — native int-slice value representation.)

3. Remove post-simplification vestiges (review follow-up)

A comparative review of the minimized code found leftover dead/vestigial bits, all behavior-preserving:

  • drop the write-only frame.freeVars field and the unneeded newFrame parameter;
  • drop the redundant cancelTicks reset (leftover from frame pooling);
  • remove the unreachable *ssa.Phi case in visitInstr and a redundant re-assertion in runBlockPhis;
  • print/println built a []any that was immediately discarded → plain no-op;
  • remove a dead sentinel setCell in runRange;
  • refresh stale comments ("hot path", "vertical slice", "Phase 6.x").

Overall: ≈ −960 net lines; fast_plan.go removed; runFrame/frameLayout drastically simplified.

Performance trade-off (benchstat, int-heavy loops)

~3.6× geomean slower on synthetic numeric kernels (BubbleSort +604%, ArithmeticSum +381%, GCD +145%). gig's target rule-engine workloads (field access, comparisons, string/host calls) run through visitInstr + the host bridge and are unaffected. Deliberate simplicity-over-microbench-throughput trade.

Validation

go test -race ./... pass (root + cmd/gig) · golangci-lint 0 issues (root + CLI) · gosec 0 issues · go vet clean.

Open in Web Open in Cursor 

cursoragent and others added 2 commits August 13, 2026 17:02
Previously the frame stored SSA values in two tiers: a dense slots array
for most values plus a lazily-created cells map fallback used only for
Alloc results (Allocs were excluded from the slot layout). This split was
a common source of confusion.

Every SSA value that can be read/written is known at frameLayout time, so
Alloc can be slotted too: re-executing an Alloc still allocates a fresh
addressable object via runAlloc; the slot merely holds the latest pointer,
and earlier objects stay alive through other references. Closures are
unaffected because runMakeClosure snapshots values into fresh Cells rather
than pointing at frame storage.

With Allocs slotted, the cells map is provably dead (verified by asserting
no writes across the full -race suite), so it is removed. cell/setCell/
bindCell now use slots exclusively; an unslotted value is a hard invariant
violation.

Result (benchstat, n=6, int-heavy workloads): time geomean +0.64% (a
couple arithmetic microloops +3-4%, several others slightly faster),
allocs geomean -5.58% (SliceSum -17.65%, BubbleSort -18.75%) from dropping
the lazy map. Full 'go test -race ./...' passes; lint/gosec clean.

Co-authored-by: t04dJ14n9 <t04dJ14n9@users.noreply.github.com>
Per the decision to prioritize minimal, understandable code over peak
throughput on synthetic numeric loops, this deletes the entire fast-path
('block plan') layer and leaves a single, uniform dispatch:

- Delete fast_plan.go (typed int/bool fast instrs, fast phis, fused
  IndexAddr plans, whole-block fast loop).
- runFrame is now one loop: resolve block Phis, then visitInstr per
  instruction. runBlockPhis has only the generic path.
- frameLayout computes just the slot index (no slotKinds, blockPlans, or
  fusedIndexAddr precompilation).
- Cell drops the typed cache (fastInt/fastBool/fastDirty); setCell/bindCell
  write Cell.Value directly; setSlotValue/materializeSlot are gone.
- Remove the fused IndexAddr optimization (fusableIndexAddrConsumer,
  tryRunFusedIndexAddr); the generic IndexAddr/Load/Store path handles it.
  isPlainIntSliceType stays (native int-slice value representation).
- Drop the fast-plan-internals tests; keep the behavior tests.

Net -895/+21 lines. Full 'go test -race ./...' passes; lint/gosec clean.

Performance trade-off (benchstat, int-heavy loops): ~3.6x geomean slower
(e.g. ArithmeticSum +381%, BubbleSort +604%). These are synthetic numeric
kernels, not gig's target rule-engine workloads; external-call/host paths
are unaffected. Variable storage remains a single []Cell per frame.

Co-authored-by: t04dJ14n9 <t04dJ14n9@users.noreply.github.com>
@cursor cursor Bot changed the title refactor: unify frame variable storage into a single []Cell Minimize the interpreter: remove fast-plan machinery, unify variable storage Aug 13, 2026
@t04dJ14n9
t04dJ14n9 marked this pull request as ready for review August 13, 2026 17:15
cursoragent and others added 2 commits August 13, 2026 17:52
After the fast-plan removal, frameLayout held only 'index', so the struct
wrapper and the separate newFrameWithLayout helper were pure indirection.
frameLayout now returns map[ssa.Value]int directly and newFrame builds the
frame inline. No behavior change.

Co-authored-by: t04dJ14n9 <t04dJ14n9@users.noreply.github.com>
Follow-up cleanups found by a code review of the minimized interpreter,
all behavior-preserving (full -race suite + lint/gosec green):

- frame: drop the write-only freeVars field (free vars are bound via the
  callSSA parameter) and the now-unneeded newFrame freeVars parameter.
- callSSA: drop the redundant 'fr.cancelTicks = 0' reset (newFrame always
  returns a freshly-zeroed frame; a leftover from frame pooling).
- visitInstr: remove the unreachable *ssa.Phi no-op case (runFrame resolves
  and skips Phis before dispatch).
- runBlockPhis: drop the redundant re-assertion in the second loop; indices
  below phiCount are leading Phis by construction.
- callBuiltin: print/println built a []any that was immediately discarded;
  reduce to a plain no-op return.
- runRange: remove the dead sentinel setCell (the Range value is never read;
  iteration flows through fr.iters).
- Refresh stale comments (drop 'hot path', 'vertical slice', 'Phase 6.x').

Net -22 lines.

Co-authored-by: t04dJ14n9 <t04dJ14n9@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants