[ZweZeya]

Stacked on #8 (test/end-to-end-from-cpp).

What this changes

Turns the one benchmark from #7 into a suite whose results are written to benchmarks/RESULTS.md. It is run by hand and deliberately not added to CI: shared runners are too noisy for timings to mean anything.

Five workloads in benchmarks/workloads/, each one source built as baseline (wtc::queue<T>, lifted and lowered back unchanged), optimized (plus --select-queue-impl) and, where it is safe, direct (spsc_queue<T> by hand, the ceiling):

Workload	Measures
spsc_throughput	one producer, one consumer, flat out (replaces queue_bench.cpp and spsc_direct.cpp)
spsc_latency	push-to-pop latency at a paced 1M items/s: p50, p99, p99.9, max
spsc_payload	a 64-byte user-defined element type
spsc_same_thread	one thread pushes a batch and pops it: no contention, and a case a bounded ring would deadlock on
mpsc_control	two producers: must not be substituted; bounds how much two builds differ by themselves

What keeps the numbers honest:

• run.sh states, per workload, whether the optimized build must be substituted, and fails if it disagrees, so no column can silently measure the wrong program.
• Every workload checks what it received (count, order, contents) and fails rather than reports.
• Variants run interleaved, RUNS times. report.py writes medians, the spread, each run's p99, and the commit, toolchain, machine and pinning.
• RESULTS.md is committed on its own, after a run, so the commit it names is the one that was measured.

The queue in each workload is a global touched only at the call sites (bench.hpp), because a helper taking it would be a use --select-queue-impl cannot retarget.

Results (M1 Pro, macOS, threads not pinned)

	baseline	optimized	direct
spsc_throughput	2.65M/s	8.02M/s (3.0x)	43.6M/s (16.4x)
spsc_payload	2.65M/s	7.41M/s (2.8x)	28.8M/s (10.9x)
spsc_same_thread	3.13M/s	7.58M/s (2.4x)	38.6M/s (12.4x)
spsc_latency p50 / p99	2.6 µs / 992 µs	208 ns / 4.4 µs	166 ns / 1.5 µs

Three things the sessions showed that a single run would have hidden, all written into the README:

• The control is never equal. Its two builds run the same queue code (the optimized one only has the shim's anchor erased), yet the optimized build was ahead by 6, 13 and 18 percent in three sessions, always in that direction and in either run order. That looks systematic (probably binary layout) rather than noise. Either way, a difference that size cannot be credited to the queue, and the report says so.
• Tail latency varies a lot between runs. In one run of five, something else on the machine moved every variant's latency by orders of magnitude at once. Across undisturbed runs the substituted p99 ranged from about 2 to 23 µs. The report therefore lists each run's p99, and the claims in the README and in runtime/spsc_queue.hpp are worded to what all the runs support.
• The gap between optimized and direct is mostly one shared_ptr allocation per pop, kept to match try_pop's interface.

How it was checked

All five workloads are substituted, or kept, as run.sh requires, and every variant's correctness checks passed on every run of three full sessions. check-wtc is unaffected (33 of 33). Not measured yet: pinned runs on Linux, bursty load, memory.

Checklist

• CI is green
• New behaviour has a test; a fixed bug has a test that failed before
• No file moves or renames mixed in with substantive changes
• The pinned LLVM revision is untouched, or this PR does nothing else

🤖 Generated with Claude Code

[apaznikov]

Closing together with the stack below it, since the substitution it measures is replaced in #10. The benchmarks there run under a reservation protocol on the lab's server (reserved cores, siblings offline, governor fixed, turbo off, interleaved repetitions, bootstrap intervals), and #10 adds workloads for the inline queue and for batched pushes. The idea of keeping a generated RESULTS.md with the environment and every run's spread is a good one for that suite; the results of the latest legs are recorded under benchmarks/results/ in #10.