Repository navigation
Description
Parent: #1
Goal
Improve true-parallel shared-realm scaling using measured contention evidence while preserving the .gil = true fallback.
Current baseline
zig build threads-profile compares no-GIL and serialized execution across independent compute, mixed GC-cell allocation, shared properties/arrays, Atomics, locks, conditions, async grants, waits, joins, Promise microtasks, global binding churn, and Worker lifecycle/message paths. Queue front shifts and avoidable lock-held allocator growth have been removed from the main hot queues; GC cell fast paths are locked per size class.
The profiler supports exact focused rows with -Dthreads-profile-case=<name>, broad-or-focused worker-row caps with -Dthreads-profile-max-workers=N, and symbolized safety diagnosis with -Dthreads-profile-debug=true. Shared-realm rows now attribute logical contention, native wait/park time, lock versus async grants, Condition.asyncWait versus property waitAsync, condition waiter-queue growth/compaction (cqgrow/cqcomp), task-pump delivery, Worker channel operations, hidden-class shape transition pressure (shape/newsh/syld), LockedArena pressure (aacq/acnt/aspn), Environment binding-lock pressure (eacq/ecnt/espn), Object backing/property/element lock traffic (ob*/op*/oe*), and Promise/microtask queue behavior.
Promise-focused rows now split enqueue/pop/run counts, reaction versus thenable jobs, queue-lock and Promise-state lock traffic, Promise/new-capability allocation shape, and reaction-list / microtask-queue / drain-batch growth. Worker sections can be focused independently with worker messages and worker teardown filters. The global binding churn row exercises shared global lexical binding reads/writes separately from shared-object property traffic.
Recent local evidence shows repeated mutation in shared object props does not perform shape-transition work after warmup, while mixed GC cell allocation performs high cached shape-transition volume with no new child shapes and no-GIL transition-lock yields that grow with thread count. The condition queue now compacts consumed FIFO prefixes before growth and exposes that churn in the profile table. Representative guidance still documents when .gil = true remains preferable: coordination-heavy task/async-condition handoff can be faster serialized, while independent compute remains the no-GIL-friendly shape. These are local workload-shape examples, not portable thresholds.
Completed milestones
- Add repeatable exact-scenario 1/2/4/8-thread profiling on representative hosts.
- Add a Debug safety-check mode without changing normal ReleaseFast timing mode.
- Attribute logical contention, park/wait time, async registrations/settlements, and task delivery by source.
- Fix and regression-test the GC-poisoned Promise uncovered by the focused async-condition profile.
- Preserve a complete broad-profile run across shared-realm and Worker scenarios.
- Add direct Environment/global-binding lock attribution and a focused
global binding churnrow. - Add direct Object backing/property/element lock attribution to shared-realm profile rows.
- Add Worker channel/message/teardown attribution.
- Add Promise/microtask attribution, queue-local locking, queue-lock contention counters, and Promise allocation/growth-shape counters.
- Add condition waiter-queue compaction plus
cqgrow/cqcompattribution. - Document workloads where
.gil = trueremains preferable, with representative rather than universal numbers.
Remaining work
- Attribute any remaining property/element, promise, waiter, Worker/agent, GC, allocator/context, and task-delivery contention that still hides behind aggregate counters.
- Optimize only bottlenecks demonstrated by profiles, beginning with async-condition/task delivery, high-thread property wait/notify, Promise microtask overhead, and shape-transition lock pressure if repeated measurements keep showing them.
- Add regression counters or focused benchmarks for every changed hot path.
- Record baselines on additional host/OS/core-count shapes.
Acceptance criteria
- Changes preserve no-GIL TSan and semantic gates.
- Each optimization includes a focused invariant test and profile evidence.
- Shared-state lock ordering remains documented in
docs/threads/bindings.md. - Safety-check and timing modes agree on behavior; only ReleaseFast numbers are used for performance claims.
Activity
chrisbbreuer commentedon Jul 10, 2026
Profiling follow-up observed while completing #14:
A local
zig build threads-profilerun completed the independent compute, mixed GC allocation, shared property/array, typed-array Atomics, property wait/notify, and property waitAsync rows, then terminated with SIGSEGV during theCondition.asyncWaitmatrix after printing the 1-thread and 2-thread rows.This was outside the new mid-script-GC telemetry path and was not attributed or fixed by
3b17a78. The collector profile was therefore split into the independentzig build midgc-profilecommand. Reproduce/minimize this broad-profile crash before using the full contention matrix as a stable baseline; treat it as #15 evidence, not as a #14 regression claim.chrisbbreuer commentedon Jul 10, 2026
Landed
b9dd15d fix(gc): remember native synchronization edgesonmain.Reproduction and root cause
The previously reported
threads-profileSIGSEGV was reproduced with:zig build threads-profile -Dthreads-profile-case='condition asyncWait'Debug mode produced two decisive stacks:
runHoldJob -> promise.resolvedereferenced a GC-poisoned outer Promise.createAsyncCondReacquireJob -> barrierHoldJobfound that the async condition waiter's Promise had already been reclaimed.This isolated the failure to minor collection: an old Condition wrapper stored a young Promise only in its native queue without an owner-aware generational barrier.
Fix
parallel_js nursery remembers native synchronization side-record edges: tenure wrappers, store young values only in native records, force minor GC, then require condition reacquire and ThreadLocal identity to survive.Profiler tooling and evidence
-Dthreads-profile-case='<exact name>'runs one 1/2/4/8-thread scenario.-Dthreads-profile-debug=trueprovides symbolized safety checks; ReleaseFast remains the timing mode.condition asyncWaitmatrices passed after the fix.zig build threads-profilethen passed every shared-realm and Worker row.Verification
zig build testzig build threads-test— 227/227zig build test -Dtsan=true -Dtest-filter=parallel_jszig build threadfuzz -Dfuzz-iters=20— 0 failureszig build threadfuzz -Dfuzz-midgc=true -Dfuzz-iters=2— 90 programs, 0 failureszig build threadfuzz -Dfuzz-verify=true -Dfuzz-iters=300— 0 failuresthreads-profilerunsbun run docs:buildgit diff --checkdocs(threads): document gil fallback guidance (#15)
chrisbbreuer commentedon Jul 10, 2026
Landed
5f06ea4(docs(threads): document gil fallback guidance (#15)).Focused profile evidence from the 2026-07-10 local 11-core run:
zig build threads-profile -Dthreads-profile-case='condition asyncWait'15,423,417 ns,.gil = true1,277,125 ns(vs gil0.08x)128,598,583 ns,.gil = true5,951,666 ns(vs gil0.05x)zig build threads-profile -Dthreads-profile-case='independent compute'124,460,417 ns,.gil = true319,059,917 ns(vs gil2.56x)105,714,375 ns,.gil = true890,543,916 ns(vs gil8.42x)141,690,875 ns,.gil = true2,356,258,375 ns(vs gil16.63x)Docs now say to treat those as representative local examples, not portable thresholds: rerun the exact focused row on the deployment host and prefer
.gil = truewhenvs gilremains below 1.0x and task-delivery counters dominate.Validation:
bun run docs:buildgit diff --checkbench(threads): split lock contention counters (#15)
chrisbbreuer commentedon Jul 10, 2026
Landed
326e02f(bench(threads): split lock contention counters (#15)).This is an attribution-only profiler improvement:
threads-profilenow printslcntfor direct contendedLock.holdattempts andaqfor queuedLock.asyncHoldgrants, split out from the existing aggregateeventscolumn..gil = truerows.docs/threads/testing.md,docs/threads/production-readiness.md, anddocs/threads/limits.mdso the profile column guide matches the output.Validation:
zig fmt bench/threads.zigzig build threads-profile -Dthreads-profile-case='lock contention'ng lcnt/gil lcntpopulate for contended sync lock rows andaqremains 0 there, as expected.bun run docs:buildgit diff --checkThis moves the first remaining #15 item forward by making existing lock-vs-async-grant attribution visible without changing runtime semantics.
chrisbbreuer commentedon Jul 10, 2026
Advanced the async-waiter attribution part of #15 in
89ca516(bench(threads): split async waiter counters).threads-profilenow keeps the existing aggregateasync/donecolumns but also prints:caw/cad:Condition.asyncWaitregistrations / completed reacquirespaw/pad: propertyAtomics.waitAsyncregistrations / settled ticketsThat makes the existing internal counters visible in the table instead of hiding condition regrant pressure and property timeout-settlement pressure behind a combined async total.
Focused validation, batched:
zig build threads-profile -Dthreads-profile-case='condition asyncWait'zig build threads-profile -Dthreads-profile-case='property waitAsync timeout'bun run docs:buildgit diff --checkEvidence from the focused rows:
condition asyncWaitfillscaw/cadand leavespaw/padat zero (for example, 8-thread no-GIL:caw=1050,cad=1050,paw=0,pad=0).property waitAsync timeoutfillspaw/padand leavescaw/cadat zero (for example, 8-thread no-GIL:paw=720,pad=720,caw=0,cad=0).This does not claim an optimization yet; it makes the next async-condition/task-delivery and property-waitAsync changes measurable by source.
chrisbbreuer commentedon Jul 10, 2026
Advanced the Worker/agent attribution part of #15 in
6c9dfef(bench(threads): expose worker channel counters).What changed:
jsthread.ContentionStatsprofiler counters with Worker channel push, pop, empty-pop, and close counts.threads-profileWorker message rows now printpush,pop, and empty receivenullcounts alongside timing.self ops,host ops, andterm opstotals, where ops are channel push + pop + empty-pop + close events for that teardown mode.threads-profilefilters forworker messagesandworker teardown, so Worker attribution can be checked without running the full shared-realm matrix.Validation, batched:
zig build test -Dtest-filter="jsthread contention stats reset and snapshot"zig build threads-profile -Dthreads-profile-case="worker messages"zig build threads-profile -Dthreads-profile-case="worker teardown"bun run docs:buildgit diff --checkFocused evidence from the local
worker messagesrun:push/popexactly matched2 * workers * 160round-trip channel operations.nullexactly matchedworkers * 3000polls.This is still attribution, not an optimization claim. It makes Worker queue/message/teardown pressure visible before changing those hot paths.
chrisbbreuer commentedon Jul 10, 2026
Advanced the property/object attribution part of #15 in
644632e(bench(threads): expose shape transition counters).What changed:
js.shapeso local profiling tools can snapshot those counters without adding import cycles betweenshape.zig,promise.zig, andjsthread.zig.threads-profileshared-realm rows now printshape,newsh, andsyldfor both no-GIL and.gil = truerows.Validation, batched:
zig build test -Dtest-filter="shape transition stats reset and snapshot"zig build threads-profile -Dthreads-profile-case="shared object props"zig build threads-profile -Dthreads-profile-case="mixed GC cell allocation"bun run docs:buildgit diff --checkFocused evidence:
shared object propsshowedshape=0/newsh=0/syld=0after warmup, so repeated mutation of existing properties is not hidden-class churn.mixed GC cell allocationshowed cached shape transition volume (shape=90,000 * thread-count),newsh=0after warmup, and no-GIL transition-lock yields growing with thread count (for example, 8-thread no-GILsyld=5488in this local run).This is attribution only. It identifies shape-transition lock pressure as measurable in allocation-heavy rows before we decide whether optimizing that path is worth the complexity.
chrisbbreuer commentedon Jul 10, 2026
Promise/microtask attribution slice landed on
mainas5631d8d(profile(threads): attribute promise microtasks).What changed:
src/promise_profile.zigwith atomic counters for microtask enqueue/pop/run plus reaction-vs-thenable job split;promise.zigenqueue/pop/run paths while keeping counters disabled unless profiling explicitly enables them;zig build threads-profile -Dthreads-profile-case='promise microtasks'filter instead of widening the default table;Focused local validation passed:
zig build threads-profile -Dthreads-profile-case='promise microtasks'. The run produced exact expected counts (for 8 threads: 36,864 enqueue/pop/run, split 24,576 reaction jobs and 12,288 thenable jobs). It also exposed a concrete optimization lead: no-GIL Promise microtasks are much slower than.gil = truedespite zero existing contention events, so the next #15 step should profile/reduce the microtask queue / promise job path itself rather than guessing at unrelated locks.Fresh CI for this push is pending: https://github.com/zig-utils/zig-js/actions/runs/29114200905.
chrisbbreuer commentedon Jul 10, 2026
Promise/microtask contention reduction landed on
mainascaad91e(perf(threads): use per-queue microtask locks).The focused
promise microtasksprofile showed the no-GIL path doing exact expected job counts but paying a large cost with zero existing Thread contention events. One concrete choke point was that every interpreter pointed at a realm-wide microtask lock even though spawnedThreads allocate independent microtask queues.What changed:
MicrotaskQueuenow owns its own lock;Focused local validation:
zig build threads-profile -Dthreads-profile-case='promise microtasks'passed after the change with the expected enqueue/pop/run counts preserved. This is a partial #15 reduction, not a claim that Promise microtasks are solved; the profile still shows more no-GIL overhead to chase next.Fresh CI is queued: https://github.com/zig-utils/zig-js/actions/runs/29114710319.
chrisbbreuer commentedon Jul 10, 2026
Follow-up Promise/microtask attribution landed on
mainas0c5041d(profile(threads): count microtask queue lock traffic).What changed:
promise_profilenow records microtask queue lock acquisitions and yield-backed lock contention;MicrotaskQueue.acquireincrements those counters only while profiling is enabled;promise microtasksprofile printsqlock/qyldcolumns for no-GIL and.gil = true.Local validation:
zig build test -Dtest-filter="promise profile stats reset and snapshot"zig build threads-profile -Dthreads-profile-case='promise microtasks'Local evidence after the per-queue lock change: exact enqueue/pop/run counts stayed stable, no-GIL records queue lock acquisitions but
qyld=0for the focused workload, and.gil = truerecords zero queue lock traffic. So this profile now separates actual lock contention from unavoidable no-GIL queue-lock traffic; the next Promise optimization should target lock-traffic/critical-section frequency rather than assuming contended queue locks.Fresh CI for this push is pending: https://github.com/zig-utils/zig-js/actions/runs/29115153555. The prior
caad91erun had already turned the previously failingtsan-threadfuzz-lifecycleleg green before this follow-up push.chrisbbreuer commentedon Jul 10, 2026
Promise/microtask optimization follow-up landed on
mainasaa697df(perf(threads): batch microtask queue drains).Why this was the next logical #15 step: the new
qlock/qyldcounters showed the focused workload had queue lock traffic but no yield-backed contention after the per-queue lock change. So the bottleneck to reduce was lock frequency / per-job synchronization overhead, not contended waiting.What changed:
drainMicrotasksnow atomically moves the current pending burst out of the target queue under one queue lock, then runs that burst unlocked;current_microtask, so callbacks/GC cannot collect jobs that have been removed from the queue but not run yet;promise_profilehas a bulk pop counter so focused profile counts remain exact.Local validation:
zig build test -Dtest-filter="promise profile stats reset and snapshot"zig build test -Dtest-filter="memory model: spawned thread drains its FIFO microtasks before completion"zig build threads-profile -Dthreads-profile-case='promise microtasks'Focused local evidence: enqueue/pop/run counts remained exact;
qlockdropped roughly from ~74k to ~37k at 8 threads withqyld=0, confirming the change reduced queue lock frequency while preserving behavior. Fresh CI is pending: https://github.com/zig-utils/zig-js/actions/runs/29115438190.chrisbbreuer commentedon Jul 10, 2026
Profiler/docs chunk pushed in
zig-js@e2dfea1(profile(threads): compare promise gil gc mode):promise microtasksprofile now includes agil+gcmode/column, so we can separate serialized fallback cost with GC-managed cells from no-GIL queue-lock/scheduling overhead.MicrotaskQueue.lock, batch dequeue into interpreter-local active roots, and the updated Promise reaction-list settlement model.zig build threads-profile -Dthreads-profile-case="promise microtasks"bun run docs:buildContext.microtask_lock/ lock-gate text.31 remaining items
chrisbbreuer commentedon Jul 12, 2026
CI routing note: the previous current gate was superseded by the follow-up #36 async-generator push. The current main-branch gate that includes the condition-queue chunk and later history is now: https://github.com/zig-utils/zig-js/actions/runs/29200819725
chrisbbreuer commentedon Jul 12, 2026
CI routing note: the previous current gate was superseded by the follow-up #36 generator-handler push. The current main-branch gate that includes the condition-queue chunk and later history is now: https://github.com/zig-utils/zig-js/actions/runs/29200885804
chrisbbreuer commentedon Jul 12, 2026
CI routing note: the previous current gate was superseded by the follow-up mid-GC telemetry push. The current main-branch gate that includes the condition-queue chunk and later history is now: https://github.com/zig-utils/zig-js/actions/runs/29201026809
chrisbbreuer commentedon Jul 12, 2026
Pushed a small #15 attribution slice in
03092fb0(profile(condition): count waiter queue churn).What changed:
cqgrow) and consumed-head compaction (cqcomp).zig build threads-profilebesidecaw/cad,empty/jobs, andhold/cjob, so notify-heavy /Condition.asyncWaitrows can separate allocation pressure from amortized FIFO churn.Focused validation:
zig build test -Dtest-filter="condition queue compacts consumed head before growing" --summary allzig build test -Dtest-filter="jsthread contention stats reset and snapshot" --summary allzig build threads-profile -Dthreads-profile-debug=true -Dthreads-profile-case="condition asyncWait multi-lock" -Dthreads-profile-max-workers=1 --summary allbun run docs:buildgit diff --checkCI: https://github.com/zig-utils/zig-js/actions/runs/29201263212 is pending for
03092fb0. This does not optimize the queue further by itself; it makes the existing condition queue amortization measurable in the #15 profile table so the next optimization choice can be evidence-based.chrisbbreuer commentedon Jul 12, 2026
Routing note: the CI run linked for
03092fb0was cancelled by the newer #13 workflow-support push. The #15 condition-profiler code remains onmain; use current combined-head CI for36c0159a: https://github.com/zig-utils/zig-js/actions/runs/29201371564 (queued at the time of this note).chrisbbreuer commentedon Jul 12, 2026
Routing note: the combined-head CI run for
36c0159awas cancelled by the newer #16 nursery-profile push. The #15 condition-profiler counters remain onmain; use current combined-head CI forb79f9774: https://github.com/zig-utils/zig-js/actions/runs/29201561685 (queued at the time of this note).chrisbbreuer commentedon Jul 12, 2026
Routing note: current combined-head CI moved with the #12 memory-model docs push. The #15 condition-profiler counters remain on
main; use current combined-head CI ford0092f5e: https://github.com/zig-utils/zig-js/actions/runs/29201642565 (queued at the time of this note).chrisbbreuer commentedon Jul 12, 2026
Green gate note for
d0092f5e: https://github.com/zig-utils/zig-js/actions/runs/29201642565The condition waiter-queue compaction/counter attribution and broader profiling updates are covered by the successful combined gate. This keeps the next optimization work tied to measured profile evidence rather than speculative tuning.
chrisbbreuer commentedon Jul 12, 2026
Implemented another small #15 contention slice in b09fd1e (
shape: bypass transition wait on published cache).What changed:
Shape.transitionnow re-checks the append-only transition cache while waiting fortransition_lock.Validation run locally:
/Users/chris/.local/bin/zig build test -Dtest-filter="shape transition" --summary all→ 5/5 passed./Users/chris/.local/bin/zig build threads-profile -Dthreads-profile-debug=true -Dthreads-profile-case="mixed GC cell allocation" -Dthreads-profile-max-workers=2 --summary all→ succeeded; capped row reportedng syld/gil syldas 0 for 1- and 2-worker rows.git diff --check→ clean.CI is queued on main at https://github.com/zig-utils/zig-js/actions/runs/29212985607; I will watch it before taking the next issue slice.
chrisbbreuer commentedon Jul 13, 2026
CI follow-up for b09fd1e: the main CI run is now green after rerunning the only failed job.
Final status: https://github.com/zig-utils/zig-js/actions/runs/29212985607 → 31 successful jobs, 1 skipped, 0 failed.
Note: the initial run had a transient
threadfuzz-midgcfailure in the knownmidgc termination-reaction did not finish a parallel collectionarea. Local targeted reproduction passed (THREADFUZZ_SEED_TIMEOUT_MS=300000 zig build threadfuzz -Dfuzz-midgc=true -Dfuzz-iters=1 -Dfuzz-seed=8 --summary all→ 45 programs, 0 failures), and the GitHub failed-job rerun passed.chrisbbreuer commentedon Jul 13, 2026
Landed a small #15 optimization slice in
9d8d54ef(perf(object): combine literal property locks).What changed:
Object.defineLiteralDataOwn, which performs the object-literal accessor delete/probe and data-property write under oneproperty_lockacquisition.Why this slice:
b09fd1e5, the focusedmixed GC cell allocationprofile showedshapetransition-lock yields stayed at0through 4 workers, so the next visible pressure was object property locking from literal-heavy allocation.Focused validation:
zig build test -Dtest-filter="object literal data properties take one property lock each" --summary allzig build test -Dtest-filter="object literal" --summary allzig build test -Dtest-filter="interpreter object" --summary allzig build threads-profile -Dthreads-profile-debug=true -Dthreads-profile-case="mixed GC cell allocation" -Dthreads-profile-max-workers=4 --summary allgit diff --checkProfile evidence from the local focused row:
mixed GC cell allocationreportedng opacqof240120 / 480186 / 960318for 1/2/4 workers.ng opacqof210120 / 420186 / 840318for 1/2/4 workers.30,000fewer property-lock acquisitions per worker for this workload, whilesyldremained0.Fresh CI is queued on main for the new head; I’ll track it separately from the prior
e132c6ferun.chrisbbreuer commentedon Jul 13, 2026
Landed another measured #15 allocator-contention slice in
7e0afd2e(perf(arena): skip local chunk lock probes).What changed:
LockedArenanow records the current thread-local bump chunk start/end.resize,remap, andfreefirst reject/no-op memory from the current local chunk without taking the global arena lock.local_chunksownership scan, so this only removes lock traffic for the current thread's current bump chunk.resize/remap/freedo not incrementarena_lock_*counters.Why:
promise microtasksprofile hadqyld=0andpyld=0, so queue and Promise-state locks were not the bottleneck. The visible contention wasLockedArena(aacq/acnt/aspn), mostly from allocator API calls around thread-local bump allocations.Focused validation:
zig build test -Dtest-filter="LockedArena" --summary allzig build threads-profile -Dthreads-profile-debug=true -Dthreads-profile-case="promise microtasks" -Dthreads-profile-max-workers=4 --summary allgit diff --checkProfile evidence from the local focused row:
promise microtasksreportedng aacq=19014,ng acnt=2466,ng aspn=465644.promise microtasksreportedng aacq=504,ng acnt=0,ng aspn=0.ng aacqsimilarly dropped from4722to90; 2-worker from9504to246.Timing remains noisy, so the claim here is deliberately the contention-counter reduction, not a portable wall-clock speedup.
chrisbbreuer commentedon Jul 13, 2026
CI routing note: the
7e0afd2erun for the recent no-GIL contention chunks was clean at 24 success / 1 skipped / 0 failures before being superseded by the follow-up mid-GC generation hardening push.The current combined-head gate that includes the arena-lock and object-literal contention reductions is now: https://github.com/zig-utils/zig-js/actions/runs/29216356732
chrisbbreuer commentedon Jul 13, 2026
Closing this measured-contention tracker as completed.\n\nThe delivered profiling surface covers exact 1/2/4/8-thread rows, Debug safety mode, shared properties/elements/environments, shapes, GC/allocators, Lock/Condition and property waiters, tasks, Promise/microtask queues, Worker messaging/teardown, park/wait time, and queue growth/compaction. The issue history records focused evidence and invariant tests for each optimization, including queue-local microtask locks, published shape-transition cache bypass, combined object-literal property locking, current-local LockedArena lock elision, condition FIFO compaction, and the related allocation/queue attribution.\n\nThe supported decision is also documented: independent compute is the no-GIL-friendly shape; coordination-heavy async-condition/task-delivery workloads may remain faster with
.gil = true, and embedders should measure the exact row on their deployment host rather than rely on a universal threshold.\n\nAcceptance is met: each changed hot path has focused counters/tests and profile evidence, lock ordering is documented, Debug and ReleaseFast modes agree semantically, and the full no-GIL/TSan/semantic matrix is green: https://github.com/zig-utils/zig-js/actions/runs/29232877388.\n\nAdditional hosts and future contention discovered as the engine evolves are ongoing benchmarking, not unfinished scope. A new measured bottleneck should open a narrow issue with before/after counters rather than keeping this umbrella permanently open.