devnw-thread-pool
fork of gitlab.com/devnw/zig/thread-pool for zig 0.17
Star
Fork
Watch
devnw-thread-pool docs api-reference.md
5.2 kB · 132 lines
Markdown
at main

API Reference #

This page summarizes the public surface exported from src/root.zig.

Primary Types #

  • thread_pool.ThreadPool: owned pool handle with submission, waiting, shutdown, and stats methods
  • thread_pool.Config: pool configuration
  • thread_pool.SubmitOptions: per-submit behavior such as backpressure, lane, waitability, and timeout
  • thread_pool.TaskHandle: opaque handle returned by waitable submissions
  • thread_pool.WaitGroup: task-group completion primitive
  • thread_pool.CancellationToken: cooperative cancellation flag
  • thread_pool.Stats: snapshot of task counts, latencies, queue depths, memory, and worker-local stats

ThreadPool Methods #

  • ThreadPool.init(allocator, config): create a pool
  • ThreadPool.deinit(): shut down and release all owned resources
  • ThreadPool.submit(task_fn, ctx, options): enqueue a single task, optionally blocking on backpressure
  • ThreadPool.trySubmit(task_fn, ctx, options): never blocks; returns error.QueueFull or error.TaskPoolExhausted instead
  • ThreadPool.submitBatch(tasks, options): enqueue a slice of thread_pool.BatchTask
  • ThreadPool.wait(handle): wait for a handle created with SubmitOptions.waitable = true
  • ThreadPool.waitGroup(): create a fresh wait group for grouping submissions
  • ThreadPool.shutdown(mode, timeout_ns): stop the pool with either drain or cancel semantics
  • ThreadPool.statsSnapshot(): read a consistent stats view
  • ThreadPool.purgeWorkerCaches(): purge per-worker scratch buffers when the pool is quiescent
  • ThreadPool.registerSubmitter(): claim a per-submitter queue slot for this thread to enable the per-submitter fast path on dedicated submitter threads. Returns !usize (the slot index) or error.NoSubmitterSlots when the 64-slot bitmap is full. Idempotent per-thread — callers should pair each registerSubmitter() with exactly one releaseSubmitter() per registration. TLS state is pool-scoped (F-001) so the same thread can safely register on multiple pools.
  • ThreadPool.releaseSubmitter(idx): release a previously-registered submitter slot. Idempotent (F-005) — a double-release on the same idx bails via an atomic CAS on the free-mask rather than racing the drain. Out-of-range idx is silently ignored. Only clears the caller thread's TLS slot if this thread was the original owner.

Config Highlights #

Common fields:

  • min_threads, max_threads
  • queue_capacity, local_queue_capacity
  • inject_batch_size
  • scheduler_variant
  • allow_blocking_lane, blocking_workers
  • worker_scratch_cap_bytes
  • idle_park_after_ns, idle_purge_after_ns
  • timestamp_mode
  • steal_batch_size

Important constraint: Config.validate() is intended for normalized configs. If you are validating a hand-built config outside ThreadPool.init(), call config.normalized().validate() rather than validating the raw struct.

Scheduler Variants #

  • global_queue
  • work_stealing
  • lane_extension

Submit Options #

SubmitOptions supports:

  • waitable
  • wait_group
  • cancellation_token
  • backpressure
  • timeout_ns
  • lane

Backpressure policies:

  • return_error
  • block
  • block_with_timeout

Task lanes:

  • default
  • blocking

Queue Implementations #

Public queue types are exported for low-level testing and experimentation:

  • thread_pool.BoundedRing
  • thread_pool.WorkDeque
  • thread_pool.RingQueue

Stats Snapshot #

Stats includes:

  • lifecycle counts: submitted, started, completed, cancelled
  • queue state: queue_depth_current, queue_depth_peak
  • worker activity: steals, steal_failures, wakeups, parks
  • memory: process RSS plus pool allocation counters
  • latencies: task wait and execution summaries
  • per-worker scratch and queue stats

See DESIGN.md for the implementation-level meaning of each field.

Build Options #

Passed as -D<name>[=<value>] to zig build. All are optional; defaults are the safe production settings.

Option Default Purpose
-Dtsan false Enable ThreadSanitizer on unit, integration, stress, and fuzz artifacts. Forces the stress suite from ReleaseFast to Debug so races are not optimised away before TSan observes them.
-Dsingle-pool false Elide the F-001 per-pool TLS identity check on the hot submit path at compile time. UNSAFE when a process hosts more than one ThreadPool — restores the pre-F-001 cross-pool OOB hazard. Reclaims 6–17% throughput on contended_spawn_8x / cpu_work_100us / mixed_fast_slow for genuinely single-pool workloads. See AppSec FINAL.md § Optimisation pass.
-Doptimize={Debug,ReleaseSafe,ReleaseFast,ReleaseSmall} Debug Standard Zig optimisation mode. Benchmarks are configured to always build under ReleaseFast regardless of this flag.

Two build steps surface TSan directly:

  • zig build test-all -Dtsan — all test suites under TSan (Debug only).
  • zig build fuzz -Dtsan [-Dsingle-pool=true] — fuzz harness under TSan; drive iteration count with FUZZ_SEED / FUZZ_ITERATIONS env vars.