Skip to main content

Module bench

Module bench 

Available on crate feature bench only.
Expand description

The benchmark family: a fourth macro family, and deliberately not a bar.

§A benchmark is not a conformance rule, and the enforcement is structural

CF-34 says performance MUST be measured by a separate harness and that the harness MUST NOT be part of the conformance bar. Its own Rule: line reads none — the harness is not the bar, which is the clause’s whole content — so there was nothing to add to suite.rs, and adding it would have violated the clause it claims to serve.

That claim is made a property of the tree rather than a sentence in a report. This module carries its own enumeration, for_each_event_store_benchmark!, beside the scenarios it names, exactly as for_each_model_rule! and for_each_concurrency_rule! do and for the reason concurrency.rs states: cargo xtask spec-trace scans suite.rs for pub async fn, so anything written there owes a clause. Nothing here is registered in for_each_event_store_rule!, registry::no_orphan_rules sees the same set either side of this module’s arrival, and xtask’s RULE_FILES does not name this file.

A benchmark result can never turn a merge red. There is no threshold anywhere, on any budget: the shipped emitters assert that a scenario completed and that its record accounts for every attempt it made, and nothing else. A wall-clock assertion passes on the author’s machine, fails on a loaded runner, and teaches contributors to re-run until green — which is CF-33’s argument for having no watchdog either.

§The testkit never reads a clock. The caller’s emitter does.

CF-33 forbids a clock anywhere under crates/happenstance-testkit/src, and cargo run -p xtask -- lint-clock enforces it by scanning every file in that directory — this one included. That is not an obstacle worked around; it lands CF-23 and CF-33 on the same seam. The harness defines and drives the workload and reports counts; the caller’s emitter observes it and owns the timer, along with warm-up, repetition and whatever it wants to do with the number.

So the measurement dependency belongs to the caller too. criterion, divan and a CSV writer are all things an adapter author puts in their dev-dependencies; this crate’s stay happenstance-core and futures-core, which is the discipline .kb/decisions/0010-the-suite-must-prove-itself.md records. crates/happenstance-testkit/tests/memory_benchmarks.rs writes such an emitter, in the caller’s crate, where a clock is allowed.

§What is measured, and why it is these three

Fixed by two consumers rather than chosen freely. RUNBOOK.md’s phase-8 work item names append throughput, conditional append under contention, and replay of N events with and without a tag filter. ADR-0012 names this same instrument as the evidence that could lift its &[Event] marker, and specifies “a realistic batch and rejection mix” — so scenarios::conditional_append_under_contention reports the committed and rejected counts separately, and distinguishes a condition violation from a store failure the way concurrency::Attempt does. A run in which every contender wins is a valid measurement of the wrong thing, and the record is what makes that legible instead of averaging it away.

n, k and N are BenchmarkParams supplied at the call site, because no constant in this crate can be right for both a Vec behind an RwLock and a file under BEGIN IMMEDIATE.

§Contention without a Send bound

The concurrency family buys thread-level contention with F::Store: EventStore + Send. This family does not copy that: it binds Fixture and nothing more, so the shape stays honest for the !Send flavour the whole two-trait design exists for. k append futures are built before any of them is polled and then driven round-robin on one thread — the shape the position-visibility and re-entrancy rules already use. An adapter that wants thread-level contention supplies it through its own emitter.

§Usage

ⓘ
happenstance_testkit::event_store_benchmarks!(MyFixture::new());

Behind the off-by-default bench feature, so cargo test --features bench. The module is additionally absent on wasm32-unknown-unknown: a Cargo feature is not target-scoped, so --all-features would otherwise reach a target with no threads and no host clock.

Modules§

scenarios
The three scenarios, in the order the runbook names them.

Structs§

BenchmarkParams
The workload sizes a benchmark run uses, chosen by the caller.
BenchmarkPass
One measured pass within a scenario.
BenchmarkRecord
What one benchmark scenario produced.