Module bench
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§
- Benchmark
Params - The workload sizes a benchmark run uses, chosen by the caller.
- Benchmark
Pass - One measured pass within a scenario.
- Benchmark
Record - What one benchmark scenario produced.