ReviewOS

zig-utils/zig-js

ABI: implement VM GC, memory accounting, and idle scheduling

#207
Closed chris opened this 9 days ago ·
9 days ago

Parent

Scope

Implement the nine shared pinned VM imports:

  • JSC__VM__blockBytesAllocated
  • JSC__VM__collectAsync
  • JSC__VM__externalMemorySize
  • JSC__VM__heapSize
  • JSC__VM__performOpportunisticallyScheduledTasks
  • JSC__VM__releaseWeakRefs
  • JSC__VM__reportExtraMemory
  • JSC__VM__runGC
  • JSC__VM__shrinkFootprint

Pinned source behavior

The Bun 4982b91e bodies are the executable contract: blockBytesAllocated includes extra memory, externalMemorySize stays distinct, synchronous and deferred collection preserve their different scheduling semantics, runGC returns the size after the last full collection, and opportunistic work treats until as a duration from monotonic now.

Acceptance criteria

  • VM identity and every counter are shared by sibling realms and isolated across foreign context groups.
  • zig-gc exposes the minimal race-safe live/committed/last-full-collection accounting needed by zig-js; changes land in the dependency repository as their own small commits before the zig-js integration update.
  • Reported external/extra memory uses checked or saturating accounting, is observable in the pinned counters, and cannot wrap on repeated reports.
  • Synchronous runGC performs a full quiescent collection and returns the post-collection size; the non-sync and collectAsync paths request/defer work without pretending an immediate synchronous sweep occurred.
  • releaseWeakRefs, shrinkFootprint, and opportunistic scheduling execute real runtime checkpoints; they are not no-op compatibility symbols.
  • Focused coverage includes arena and precise-GC modes, reachable/unreachable allocation, weak processing, extra/external accounting, sibling/foreign VMs, monotonic scheduling bounds, null inputs, repeated collection, and post-collection return values.
  • Home/Bun inventories, README/API evidence, and all parent trackers are regenerated from checked-in results; benchmark scores remain unchanged unless the runtime hot path is materially altered.
9 days ago

Implemented and documented on main.

Evidence:

  • zig-gc@87c5297 — race-safe live/last-full heap accounting API, parallel-lock path coverage, full dependency test suite passed
  • ddc5bc19 — nine pinned VM heap/accounting/scheduling imports, precise-GC Context coverage, 145-symbol consumer fixture, regenerated inventories
  • b97083b6 — README/API/Home/ABI evidence and current counts
  • zig build test-home-private-abi -Doptimize=Debug — 145/145 linked runtime matrix passed
  • zig build test -Dtest-filter="runtime heap accounting" — precise allocation/reclamation/last-full snapshot passed with zero leaks
  • zig build home-private-abi-audit bun-private-abi-audit — Home 146/431 (285 pending), Bun 140/421 (281 pending), zero drift/unclassified entries

Coverage includes sibling/foreign VM accounting, external-versus-extra separation, saturating reports, deferred GC, positive/zero-duration opportunistic jobs, synchronous/non-sync full collection return values, weak/footprint checkpoints, null inputs, precise and arena heap modes, and first-exception preservation. Benchmark scores were intentionally retained because the change adds explicit control calls and no benchmark hot path.

Sign in to comment on this issue.