ReviewOS

zig-utils/zig-js

ABI: implement VM jobs, module registry, and code invalidation

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

Parent

Scope

Implement the seven shared pinned job/cache imports:

  • JSC__JSGlobalObject__deleteModuleRegistryEntry
  • JSC__JSGlobalObject__drainMicrotasks
  • JSC__JSGlobalObject__handleRejectedPromises
  • JSC__JSGlobalObject__queueMicrotaskCallback
  • JSC__JSGlobalObject__queueMicrotaskJob
  • JSC__VM__deleteAllCode
  • JSC__VM__drainMicrotasks

Acceptance criteria

  • Job queues remain selected-realm but VM draining observes all required shared work in pinned order, with reentrant jobs drained to quiescence and first exceptions preserved.
  • Native callbacks copy/retain their context safely through execution and run exactly once. Encoded job values enforce same-VM ownership and exact argument identity.
  • Module registry deletion uses exact ZigString decoding, affects only the selected realm entry, and is synchronized with module graph tracing.
  • Rejected-promise handling emits each unhandled event once and respects later handled transitions.
  • deleteAllCode drains jobs, clears module/source caches, safely invalidates every native-tier entry before executable mappings are released, and reports abandoned graphs without leaving stale pointers.
  • Sibling realms, foreign VM/global pairs, null/invalid inputs, callback throws, reentrancy, already-empty queues, module reload, and post-invalidation interpreter fallback are covered.
  • Inventories, README/API evidence, and parent trackers are regenerated from checked-in results.
9 days ago

Implemented and pushed to main in small commits:

  • e94f8fa1 — safe native-code invalidation leases and tier reset
  • b83b5787 — VM/global job queues, rejection handling, module-registry deletion, and deleteAllCode
  • a24fd2eb — ABI inventories and implementation evidence
  • 16b99d70 — private VM job/control API documentation
  • ee079b27 — amortize the execution lease per outer VM run
  • af5abba8 — make benchmark publication report partial mode wins accurately
  • 36a617b3 — publish the isolated 1,540-sample zig-js/JSC matrix and refresh README/docs

Acceptance evidence:

  • Native callbacks and encoded jobs preserve exact context/arguments, reject foreign-VM values, execute once, and drain reentrant FIFO work to quiescence. A throwing job preserves the first exception and requeues the untouched tail.
  • VM draining visits all live realms; selected-global draining remains realm-local. Unhandled rejections are rooted, one-shot, and skipped after a handled transition.
  • Module entries are cached per realm, exact-key deletion reloads only the selected entry, and registry tracing/deletion is synchronized.
  • deleteAllCode drains jobs, clears the selected registry/source state, waits for active compilation/execution leases, invalidates every tier safely, unmaps code, requests collection, and permits later interpreter/recompile fallback.
  • Focused Owner, module-registry, hot native-tier, numeric-tier, GC-root, reentrancy, invalid-input, exception-tail, rejection, and invalidation tests pass.
  • zig build test-home-private-abi -Doptimize=Debug passes: Home 153/431 implemented, 278 pending; combined runtime fixture 152/152.
  • python3 tools/bun-private-abi.py passes: Bun core 147/421 implemented, 274 pending. Public/extension accounting remains 117/19.
  • zig build benchmark-comparison-test passes 11 publication + 7 harness tests.
  • Final isolated comparison at engine commit ee079b27: zig-js wins 10/10 direct rows at 2.38x geometric-mean throughput, 9/10 warmed eight-lane rows at 2.36x, and 10/10 cold eight-lane rows at 2.61x; shared-realm scaling is 4.24x. The README explicitly records the warmed object_churn loss.

Report: https://github.com/zig-utils/zig-js/blob/main/docs/.data/benchmark-comparison-2026-07-17-vm-run-leases.md Raw samples: https://github.com/zig-utils/zig-js/blob/main/docs/.data/benchmark-comparison-2026-07-17-vm-run-leases.tsv

9 days ago

All seven pinned imports, their semantic and lifetime tests, regenerated inventories, API/README evidence, and the post-change isolated JSC comparison are now on main. Closing as complete; the remaining private-ABI work continues under the updated parent trackers.

Sign in to comment on this issue.