Repository navigation
Description
Parent: #482
Related: #474, #480, #493, #885, #886
Problem
A completed Thread’s return value is not published into ThreadRecord.result until after several GC-capable operations. Because a running peer’s native stack is not conservatively scanned by the parallel collector, threadMain tries to bridge that interval with:
machine.gc_temp_roots.append(machine.arena, out) catch {};
Its own comment identifies this as the return value’s only precise root. If the append fails, microtask drains, waiter settlement, timers, or task pumping can advance collection and reclaim/relocate the value while it is still used.
After publishThreadCompletion, rec.result and rec.settling_joins are already traced under join_mutex; the later ignored temp-root appends are therefore redundant, not the only owners. However, the corresponding promise.resolve/reject calls and final drains also use catch {}, and finishThreadJoinSettlement publishes joins_settled = true even if a pending asyncJoin Promise was never settled or its required reaction publication failed.
#885 owns general Promise state-to-microtask publication. #886 owns already-existing queue transfer/restoration. This issue owns Thread completion’s pre-publication result root and its completion-state transaction.
Required implementation
- Publish the Thread result into a traced, join-mutex-protected ThreadRecord slot before any post-call GC-capable drain, without making
doneobservable early. - Keep
rec.resultandrec.settling_joinsas the authoritative post-publication roots; remove redundant best-effort temp-root appends or turn them into proved non-fallible optimization-only storage. - Publish
doneandjoins_settledonly at states that accurately describe the result, pending join capability settlement, and rerouted reaction ownership. - Propagate or materialize OOM through each asyncJoin result exactly once; never silently leave it pending.
- Compose with Thread termination, nested asyncJoin, thenable assimilation, local-to-realm queue closure, concurrent marking/moving GC, and teardown.
- Preserve the current synchronous join rule: it waits for
done && joins_settled && exited.
No-workaround rules
- No swallowed required root/settlement error, reliance on an unscanned running stack, disabling parallel GC, global GIL, leaking Thread records, capping valid pending joins, retrying user callbacks, or marking completion early.
- A barrier is not a substitute for durable rooting across later collection progress.
- Do not retain redundant fallible root copies as a false safety claim when the ThreadRecord already owns the post-publication roots.
Acceptance
- A deterministic allocator-fault witness proves the pre-publication result remains rooted when the temp-root allocator is exhausted.
- Forced concurrent GC between function return, each drain/waiter step, completion publication, join settlement, and Thread exit cannot reclaim or relocate an unpublished result or Promise.
- Every pre-existing asyncJoin Promise fulfills/rejects exactly once, or receives the exact engine OOM completion, before
joins_settledbecomes observable. - Root tracing/relocation tests prove
rec.result,pending_joins, andsettling_joinsownership at each state transition. - Nested joins, thenables, throwing Threads, termination, waitAsync/property-async rerouting, and late local-queue closure preserve order and liveness.
- Bounded heap, moving/parallel GC, lifecycle/mid-GC/threadfuzz, full units, and suppression-free TSan pass without leaks or suppressions.
- Exact Promise/async/Thread Test262 and PR-249 coverage has zero regressions; documentation makes no unsupported recovery guarantee.
Security boundary
Thread return values and pending join counts are script-controlled, and allocation pressure can coincide with concurrent marking. Required precise roots must be fail-closed engine invariants, not best-effort bookkeeping.
Activity
chrisbbreuer commentedon Sep 5, 2026
Source-level ownership proof for the implementation:
Binding.traceRootsmarksrec.result,rec.pending_joins, andrec.settling_joinsunconditionally while holdingjoin_mutex; it does not requiredone.gc_temp_roots.append(out) catch {}with an allocation-free publication ofouttorec.resultunderjoin_mutex, preceded by the ordinary insertion barrier, while leavingdone = false. Neither synchronousjoin()norasyncJoin()exposes the provisional slot because both branch on the lockeddonestate.publishThreadCompletion, the localpending_joinsslice aliases the same backing stored inrec.settling_joins, so the ignored result/join temp-root appends should be removed rather than “fixed”; they add failure points without adding ownership.finishThreadJoinSettlementmust remain gated on successful settlement of the complete frozen snapshot. Making that failure path exact depends on Promises: make reaction scheduling OOM-atomic #885’s Promise-to-microtask transaction; queue rerouting/restore remains Microtasks: make queue transfer and restoration OOM-atomic #886.No code is being mixed into the currently running #875 revision.
fix(threads): preserve completion roots and queue handoff (#886, #887)
chrisbbreuer commentedon Sep 8, 2026
Partial implementation landed on
origin/main: fix(threads): preserve completion roots and queue handoff (#886, #887) (paired with #886).ThreadRecord.resultnow receives successful values and the exact body exception/OOM completion underjoin_mutexbefore any post-call drain, waiter settlement, timer, or task pump.doneremains false during those checkpoints. This also fixes a separate observable bug: a throwing microtask previously overwrote the body exception before it was copied to the completion record.The record and
settling_joinsremain the authoritative post-publication roots; redundant best-effort temp-root copies are removed. Settlement iterations and synchronous join reload the result after GC-capable work. The new allocator-fault witness exhausts temp-root storage, then proves result/child retention with native stack scanning disabled beforedone, tests relocation, and proves collection after ownership is removed.Validation on the committed source:
TSAN_OPTIONS=halt_on_error=1)./tmp/zig-js-thread-transfer-evidence/(local evidence, not a portable checked-in report).Still outstanding: asyncJoin resolve/reject errors are still swallowed, and early worker setup failure still lacks a complete pending-join settlement transaction. Those paths must deliver an exact failure or commit thenable resolution/job ownership before
joins_settledis published. The broader forced-GC, startup/termination, PR-249, lifecycle/mid-GC, and full TSan acceptance checks also remain. This issue stays open; the landed root fix is not a claim that those OOM guarantees are complete.chrisbbreuer commentedon Sep 8, 2026
The remaining completion transaction is now implemented locally and in validation; it is not yet committed.
joins_settledasserts every prepared token has been consumed before releasing the snapshot roots.The initial Debug witnesses pass: competing registry growth under exhausted allocation; entry-root retention/relocation with native scanning disabled; 17 pending joins under first-root, second-root, and GC-capable then-getter OOM; allocation-free thrown-result rejection; delayed thenable adoption; and a throwing getter that reentrantly calls asyncJoin. The JS cases run in both GIL modes. Broader TSan/ReleaseSafe, full-unit, conformance, PR-249, and fuzz checks are underway sequentially.
One acceptance clarification:
joins_settledmust mean that the snapshot's resolution/rejection and required job publication have committed. A Promise adopting a thenable may legitimately remain pending after Thread exit; synchronous join must not wait for an arbitrary future thenable result. The new test explicitly proves that join returns while adoption is pending and that all 18 early/late capabilities later deliver the exact result once.fix(threads): commit prepared asyncJoin completion (#887)
chrisbbreuer commentedon Sep 8, 2026
Landed on
origin/main: fix(threads): commit prepared asyncJoin completion (#887).The completion transaction now reserves required publication before an asyncJoin capability escapes. Fallible root registration and then lookup retain that reservation; an engine OOM becomes the exact rooted OOM rejection with no Promise/queue growth and no replay of user code. The shared locked settlement commit preserves ordinary Promise scheduling as well.
Pending joins reserve the final realm/host destination. An already-completed Thread preserves the caller's current queue, including worker-local thenable jobs.
joins_settledis published after every token is consumed and the final worker queue is handed off; an adopted thenable can legitimately remain pending afterward.Both startup OOM paths that discarded pending joins have been removed: queue storage and an active-interpreter registry slot are prepared before OS-thread spawn. Ordinary registrations respect those reserved slots. The worker initializes its interpreter after the GC gate, then registers without allocation. The entry callable and arguments remain traced/relocated ThreadRecord roots until the body result is published.
Six new regression tests cover 17-capability OOM completion at both root allocations and a GC-capable then getter, exact thrown-result rejection under exhaustion, deferred adoption, reentrant throwing getters, late-join worker affinity, registry reservation pressure/cancellation, and startup root retention/relocation. GC tests disable native-stack fallback where relevant.
Validation on the committed executable source:
TSAN_OPTIONS=halt_on_error=1).lifecycle/async-join.jsandlifecycle/nested-threads.js: 2/2 in GIL and 2/2 in no-GIL./tmp/zig-js-887-evidence/(local evidence, not a portable checked-in report).Keeping #887 open for remaining acceptance work, including full-suite TSan and explicit moving-GC fault injection across the completion/checkpoint boundaries. General Promise job-execution OOM after successful job publication remains tracked in #885. A separate source-review finding about capped admission's completion-state lock is now #895; that test-only path is not covered by the default-cap test claim above.
fix(promises): preserve dequeued job completion on OOM (#885)
fix(runtime): preserve unowned checkpoint failures at host entry (#896)
fix(threads): hand off terminal checkpoint errors with queued jobs (#896
test(threads): exercise moving completion roots (#887)
chrisbbreuer commentedon Sep 22, 2026
Closing as implemented and accepted.
The production transaction landed in
a8f1b3ccand9fb57fa0; the final real-moving-GC witness landed in69400b3f.Final acceptance evidence:
ThreadRecord.resultwhiledoneremains false; normal and actual moving collections retain it, rewrite both parent and child pointers, preserve the exact value, and reclaim it after record ownership clears.joins_settled, with no outstanding reservations.The completion state now has durable root ownership and prepared settlement ownership at every fallible boundary, without a global GIL, pending-join cap, callback replay, or leaked Thread record.