ReviewOS

zig-utils/zig-js

GC relocation: add stable protected handles to the Zig API

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

Parent: #336 Related: #334, #335, #350, #356 Roadmap: #144, #134

Context.compactGarbage is public to Zig embedders, but raw Value copies cannot be rewritten after movement and the only stable roots are currently C/private internals.

Scope

  • Add an allocator-owned, address-stable Context.ProtectedValue handle.
  • Add public protectValue and unprotectValue operations with exact context ownership.
  • Trace and relocate the handle's contained Value under the existing realm-root synchronization.
  • Reclaim outstanding handles during Context teardown.
  • Document that raw Values cannot cross a compaction boundary.

Acceptance

  • A protected Object survives useful compaction while its payload address changes.
  • The handle address stays stable and post-move Value/property access succeeds.
  • Foreign-context release is rejected and owner release removes the root.
  • Inventory and stale-pointer postcommit verification include the Zig handle surface.
  • Focused Debug, ReleaseSafe, and TSan tests pass without leaks.
9 days ago

Implemented and pushed as 3e38a5ac. Zig embedders now have an opaque, allocator-owned Context.ProtectedValue plus protectValue/unprotectValue. The stable record is synchronized with realm roots, traced during ordinary/concurrent marking, rewritten during compaction, included in postcommit stale-pointer verification, and reclaimed at Context teardown. The witness proves stable handle address, changed Object payload, intact property access, dense second pass, foreign-context rejection, and owner release. Debug/ReleaseSafe/TSan: 3/3, zero leaks; inventory green at 27 surfaces.

Sign in to comment on this issue.