devnw-thread-pool

fork of gitlab.com/devnw/zig/thread-pool for zig 0.17

devnw-thread-pool docs

3 folders · 27 files

· fix(queue): FIFO owner pop so batch steals cannot overrun (SONNY-2448) · 1mo ago

docs(perf): Go-gap round 3 FINAL — externalised DescCache FAILED

docs(pool): close REV-001 — document task panic contract + add skew observability

docs(plans): add 2026-06-11 audit remediation implementation plan

fix(queue): FIFO owner pop so batch steals cannot overrun (SONNY-2448)

api-reference.md

docs: round out appsec remediation + single-pool documentation

APPSEC_REVIEW_2026-04-15_src.md

docs: AppSec review report and remediation plan (2026-04-15)

APPSEC_REVIEW_2026-06-11_round2.md

docs(audit): appsec review round 2 - all AP findings verified closed

APPSEC_REVIEW_2026-06-11_src.md

docs(audit): 2026-06-11 appsec review + full audit gap sync

architecture.md

fix(queue): FIFO owner pop so batch steals cannot overrun (SONNY-2448)

docs: fix 4 unrenderable mermaid blocks + add check-mermaid pre-commit

BUG_2026-04-25_submitter_free_mask_shift_ub.md

fix(submitter): special-case max_submitter_queues=64 in free-mask init

codex-review-2026-04-14.md

feat(pool): add scratch fast path and idle wake queue

docs: close Q-NEW-03/04/05/06/07/09, QR-005 residual, RISK-06 staleness (#108 #109 #110 #111 #112 #114 #49 #85)

perf(bench): add runtime comparison suite and docs

perf(bench): add runtime comparison suite and docs

GAP_ANALYSIS_RESOLVED.md

docs: update gap analysis tracking after 2026-06-11 remediation pass

GAP_ANALYSIS.md

docs: close round-2 audit findings - tracking consistency + CLAUDE.md refresh (Q2-NEW-01, G2-NEW-01..04)

gap-closure-report-2026-04-16.md

docs: close 6 gaps (SEC-018, REV-001, QS-002/003/008, OBS-PIVOT)

getting-started.md

chore: bump Zig target to 0.16.0

HANDOFF-2026-04-14.md

perf(bench): add runtime comparison suite and docs

HANDOFF-2026-04-15.md

docs: round out appsec remediation + single-pool documentation

PERF_GAP_ANALYSIS.md

docs: update gap analysis tracking after 2026-06-11 remediation pass

PERFORMANCE_TARGETS.md

docs: close Q-NEW-03/04/05/06/07/09, QR-005 residual, RISK-06 staleness (#108 #109 #110 #111 #112 #114 #49 #85)

PERFORMANCE_TRACKING.md

test(pool): rename the g2 wake test and state the Condition timeout and CPU caveats (SONNY-2427)

QUALITY_GAP_ANALYSIS.md

docs: close round-2 audit findings - tracking consistency + CLAUDE.md refresh (Q2-NEW-01, G2-NEW-01..04)

docs(perf): Go-gap round 3 FINAL — externalised DescCache FAILED

RUNTIME_COMPARISON.md

fix: close GAP-0054/0042/0047/0057, QR-002 - toolchain fallback, image pin, submodule note, script hardening, single-pool CI gate (#103 #98 #102 #106 #24)

SCHEDULER_DECISION.md

feat(thread-pool): implement bounded pool, benchmarks, and docs

docs: round out appsec remediation + single-pool documentation

docs: add comprehensive usage guide for external importers

README.md

thread-pool Documentation #

Documentation for setup, API usage, testing, benchmarking, algorithms, and performance history.

Start Here #

Getting Started — install, build, first pool
API Reference — every public symbol
Examples — batch submit, blocking lanes, cancellation
FAQ

Architecture & Algorithms #

Architecture — component layout + ownership rules
Design — rationale, queue design, memory model, shutdown
Algorithms — mermaid diagrams for each pipeline (submit flow, worker loop, descriptor lifecycle, DescCache, Chase-Lev deque, RingQueue SPMC, Vyukov MPMC, wake coalescing, lane routing, watchdog, shutdown)
Scheduler Decision — variant-picking rubric

Testing & Benchmarks #

Testing — validation matrix, TSan, fuzz, stress gate
Benchmarks — scenario matrix, measurement protocol, current snapshot, A/B loop reference
Runtime Comparison — Zig vs Tokio vs Go same-host snapshot + analysis
Performance Tracking — long-form per-phase delta history

Security #

AppSec Review (2026-04-15) — full-src audit; all 7 priority findings fixed.
AppSec Remediation FINAL — end-to-end performance ledger + same-compiler bisect + optimisation pass.
TSan Baseline Findings — zero warnings on current main.
Remediation Plan — the 11-task plan that produced the fixes.
SEC-018 — wait() idempotency ADR
REV-001 — task_fn panic contract ADR

Gap Analyses #

Performance Archive #

Chronological (most recent first):

2026-04-17 Go-gap round 3 (FAILED) — externalised per-worker DescCache reverted; indirection cost dominated Worker-size savings on all 3 primary targets. Closed plane.
2026-04-17 Go-gap round 2 (FAILED) — lifo-rotate + batched submitBatch both reverted; closed-plane reference for future rounds.
2026-04-16 Go-gap contended (DescCache landing) — nested_fanout_4x +81.26%; contended_spawn_8x +35.98%; contended_cpu_10us +31.71%.
2026-04-15 AppSec Remediation Perf Ledger — BASELINE → per-step → FINAL, same-compiler bisect, -Dsingle-pool optimisation data.
2026-04-15 Direct Runtime Comparison
2026-04-15 Post-Gen-Tag Profile
2026-04-14 Scratch Fast-Path + Idle Queue (reverted)

Handoffs & Reviews #

Quick Links #