Repository navigation
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Child tracker from #11/#16/#1.
Goal
Define and maintain the public heap-cap and per-thread OOM contract for zig-js contexts, including how allocation pressure is surfaced to hosts and to shared-realm Thread joiners.
Current status
The original PR-249 blocker semantics/oom-one-thread.js is now promoted. GC-backed capped contexts can collect and retry at safe GC cell allocation failures and ArrayBuffer byte allocation failures, and the reference recovery witness passes.
Implemented contract:
Context.Options.heap_limit_bytesapplies a thread-safe outstanding-byte budget to Context-owned allocator traffic.Context.heapBudgetStats()reports limit, used, peak, and remaining bytes for capped contexts.- Top-level host evaluation reports unrecovered cap pressure as Zig
error.OutOfMemory. - A capped context prebuilds an immutable
OutOfMemoryErrorobject so shared-realmThreadcompletion can publish a deterministic JS error value even when ordinary heap allocation is exhausted. join()rethrows that reserved object, and already-createdasyncJoin()reactions reject with it when they can be delivered.- Allocation-site OOM can become catchable by active JS handlers in the covered interpreter/tree-walker paths, including catch-binding pressure that has pre-reserved environment storage.
- Arena-backed caps remain fail-closed and non-reclaimable unless callers opt into GC-backed recovery.
- GC-backed capped contexts can recover after unreachable pressure is collected at safe allocation-recovery points.
Remaining linked work
- Runtime: extend heap-cap emergency recovery beyond current safe allocation classes #30 tracks the remaining emergency-recovery perfection work: no-GIL root-publication recovery, side-store pressure, and avoiding lock-order deadlocks during collect/retry.
- Keep documenting any new capped allocation classes as either fail-closed, catchable, or recoverable.
- Keep the PR-249 audit/probe evidence current if a future behavior change affects heap-cap cases.
Acceptance criteria
- Heap-cap behavior is documented for arena-backed and GC-backed contexts.
- Allocation failure remains observable as ordinary JS/host errors without corrupting GC state.
- One capped shared-realm
Threadcan hit OOM while siblings and cleanup/finalization remain well-defined. - Promoted reference coverage and focused unit tests prove the intended supported contract.
- Remaining uncovered allocation classes are tracked by narrower follow-up issues rather than hidden behind this parent tracker.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
chrisbbreuer commentedon Jul 11, 2026
Landed first resource-control primitive in
a510e76(feat(context): add heap allocation limit).What changed:
Context.Options.heap_limit_bytesplus matchingContext.TestingOptions.heap_limit_bytes.BudgetAllocatorwrapper that enforces a per-Context outstanding-byte cap and fails closed witherror.OutOfMemory.Context.gpausers.Contextallocation before arena/budget unwind.Focused validation run locally:
zig build test -Dtest-filter='BudgetAllocator enforces outstanding byte limit' --summary nonezig build test -Dtest-filter='Context heap_limit_bytes fails closed on allocation pressure' --summary nonezig build test -Dtest-filter='Context public Options expose only stable thread controls' --summary nonebun run docs:buildgit diff --checkRemaining for this issue:
chrisbbreuer commentedon Jul 11, 2026
Landed another small #24 slice in
5df46a7(feat(context): expose heap budget stats).What changed:
Context.heapBudgetStats()for capped contexts, returninglimit_bytes, currentused_bytes, lifetime successful-allocationpeak_bytes, andremaining_bytes.null, keeping the diagnostic tied to the explicit fail-closed allocator boundary.BudgetAllocatortests so peak accounting stays monotonic and only reflects successful outstanding allocation growth.Validation run locally:
zig build test -Dtest-filter='BudgetAllocator enforces outstanding byte limit' --summary nonezig build test -Dtest-filter='Context heap' --summary nonebun run docs:buildgit diff --checkRemaining #24 work is still the harder semantics piece: define deterministic per-thread OOM survivor behavior under pressure and then promote the matching WebKit PR-249 witness once that observable contract is nailed down.
chrisbbreuer commentedon Jul 11, 2026
Landed the first deterministic per-thread OOM survivor contract slice in
ecce653(fix(threads): publish heap-limit oom sentinel).What changed:
Value.staticStr(comptime)for sentinel values that must remain constructible under heap pressure.Threads now publish a static"OutOfMemoryError"completion value when thread startup or body execution hits nativeerror.OutOfMemory, instead of allowingjoin()to rethrow an ambiguousundefined.ThreadexhaustsContext.Options.heap_limit_bytes,join()catches the sentinel, and an already-running siblingThreadstill joins successfully afterward.Context.evaluate()reports Zigerror.OutOfMemory; spawnedThreadcompletion publishes the allocation-free sentinel for JS-visible joining.Validation run locally:
zig fmt src/value.zig src/jsthread.zig src/context.zigzig build test -Dtest-filter='Context heap_limit_bytes lets sibling Threads survive one Thread OOM' --summary nonezig build test -Dtest-filter='Context heap' --summary nonebun run docs:buildgit diff --checkRemaining #24 work: stress this survivor contract under more interleavings and then promote or reclassify the PR-249 OOM reference case based on the audited observable behavior.
chrisbbreuer commentedon Jul 11, 2026
Opened follow-up #26 for the final polish beyond the current robust sentinel contract: use an emergency reserve/prebuilt value so heap-limit
ThreadOOM can throw a realOutOfMemoryErrorobject instead of the current allocation-free string sentinel, without depending on ordinary heap headroom.chrisbbreuer commentedon Jul 11, 2026
Follow-up #26 landed in
78c5a4f: the #24 OOM survivor contract now uses a reserved immutableOutOfMemoryErrorobject instead of the temporary primitive sentinel.That means the documented spawned-Thread path is now:
Context.evaluate()still reports allocator pressure as Zigerror.OutOfMemory;Threadthat exhausts the context budget publishes a prebuiltOutOfMemoryErrorobject;join()rethrows that object without allocating on the failed path;Threads remain joinable after the exhausted peer.Focused validation is listed on #26.
chrisbbreuer commentedon Jul 11, 2026
Landed another small #24 slice in f3cb0cc: f3cb0cc
What changed:
semantics/oom-one-thread.jsreference probe now maps the inert vendored JSC RAM-cap directive to zig-js's realContext.Options.heap_limit_bytescap (192MiB).tools/threads-reference-audit.pynow classifies that probe under allocation-site catchable OOM semantics and expects the current blocker evidence.Validation:
zig fmt conformance/threads_test.zigPATH="/Users/chris/.local/bin:$PATH" python3 tools/threads-reference-audit.py --fail-on-uncategorized --run-probes --expect-current-blockers --skip-timeout-probes --probe-timeout 20/Users/chris/.bun/bin/bun run docs:buildgit diff --checkCurrent evidence is now sharper: the probe fails with
OutOfMemoryError: Context heap limit exceeded, so the cap is firing. The remaining runtime gap is that JS allocation pressure escapes as whole-Threadcompletion instead of being catchable by the allocating frame's localtry/catch.Opened follow-up #27 for that allocation-site catchability work.
chrisbbreuer commentedon Jul 11, 2026
Follow-up landed in 75a7e49: 75a7e49
This improves the heap-cap contract from #24/#27: capped allocation failures can now become catchable JS
OutOfMemoryErrorthrows when an active JS handler exists, using the prebuilt OOM object instead of trying to allocate a fresh error while the heap is full.Validation:
semantics/oom-one-thread.js: still fails withOutOfMemoryError: Context heap limit exceeded, so Runtime: make heap-limit allocation failures catchable at JS allocation sites #27 remains open for catch-binding/small-increment pressure.Also opened #28 for the separate string-cell OOM panic found during this work.
chrisbbreuer commentedon Jul 11, 2026
#27 follow-up from 4a83575: 4a83575
The simple allocation-site catch-binding blocker improved: capped
catch (e)now pre-reserves its catch environment/binding and has a focused green regression.The PR-249
semantics/oom-one-thread.jswitness still fails with a whole-threadOutOfMemoryError. The remaining shape appears to belong here in the heap-cap contract: the witness expects recovery after dropping JS references, but the current arena-backedheap_limit_bytesbudget is outstanding-byte based and does not reclaim individual arena allocations when the hog clears its hoard. We need to decide/implement the intended contract for capped threaded contexts: arena fail-closed only, GC-backed reclaimable caps for PR-249-style recovery, emergency headroom, or a hybrid.chrisbbreuer commentedon Jul 11, 2026
Opened #29 to track the concrete heap-cap recovery policy now blocking PR-249
semantics/oom-one-thread.jsafter the #27 catch-binding improvement.The decision needed here is the contract split: arena-backed caps are fail-closed and non-reclaimable, while GC-backed capped contexts need safe collect/retry or emergency-headroom behavior if we want PR-249-style post-OOM recovery.
chrisbbreuer commentedon Jul 11, 2026
Heap-cap contract update: zig-gc b99de49 plus zig-js 78b553a promote semantics/oom-one-thread.js. GC-backed capped contexts now have a GIL-safe GC cell allocation failure collect/retry path, and the PR-249 recovery witness passes.
The remaining cap-policy surface is narrower now: #30 tracks no-GIL emergency recovery and side-store/ArrayBuffer-byte retry policy. Arena-backed caps remain fail-closed unless callers opt into GC-backed recovery.
chrisbbreuer commentedon Jul 11, 2026
Heap-cap contract docs caught up in
34134b7.Current status for #24:
OutOfMemoryErrorobject and keeps siblings joinable;semantics/oom-one-thread.js.I am leaving #24 open while #30 tracks the remaining perfection work: no-GIL emergency recovery and lock-aware side-store pressure. Arena-backed caps are intentionally documented as fail-closed.
chrisbbreuer commentedon Jul 11, 2026
CI follow-up:
e179650tightens the heap-cap recovery contract after TSan caught parked-stack conservative scanning during allocation-failure recovery. The practical contract is now clearer: GIL/single-thread recovery may collect and retry when it can scan only safe roots; live no-GIL peers fail closed until #30 grows an abort-safe recovery collector. Focused TSan checks forsemantics/oom-one-thread.jsand the sibling-thread OOM unit witness pass locally.chrisbbreuer commentedon Jul 11, 2026
Completed. The heap-cap and per-thread OOM contract is now covered by promoted/reference evidence plus focused unit coverage, including the bounded sibling-Thread OOM witness.
Fresh full CI is green for
b2e7dbe5e9bc2a27a87ff1bad8be8b0be777e46e: https://github.com/zig-utils/zig-js/actions/runs/29170980761Remaining narrower heap-cap perfection work stays open in #30.