Module concurrency
Expand description
The parallel half of the suite: contenders on real threads, racing for the same consistency boundary.
§It is additive. It retires nothing.
The plan this module was written from said it would retire
racing_conditional_appends_elect_one_winner.
It does not, and the reversal is on the record rather than in a commit
message: SPECIFICATION.md §7.4 now claims that rule for ES-25, because its
content is the iff seen as two decisions taken from one snapshot, and two
of the three registered mutants it rejects are shapes ES-25’s own Rejects:
paragraph names by hand. Three dispositions were written this phase and all
three were reversed — every one of them by compiling a store rather than by
reading a rule, which is the method §6.1 forbids for adapters and which turns
out to be no more reliable when it is a rule being judged.
So the two live side by side and they answer different questions. The sequential rule fixes the semantics a race must have: which of two decisions taken from one snapshot is allowed to land. It cannot distinguish an atomic check-and-write from a probe followed by an insert, because with one caller at a time there is no second caller to fit between the two halves. This family supplies the second caller.
§There is no timeout, and CF-33 is why
The runbook’s work item asked for one more assertion than is written here: every task terminates within a timeout. It is deliberately absent.
CF-33 is [FROZEN] — no conformance rule may read a clock, measure
elapsed time, or assert on an operation count — and its own Rejects:
paragraph makes exactly the argument that applies to a watchdog on a racing
rule: a wall-clock deadline passes on the author’s machine, fails on a loaded
CI runner, fails under a debug build, and makes the suite’s verdict a
property of the hardware. A flaky conformance suite is worse than no
conformance suite, because it teaches adapter authors to re-run until green.
A watchdog is the most tempting clock in the whole suite precisely because it
looks like a safety feature rather than an assertion.
Liveness rests on the CI job timeout instead. That is a worse message — a
hung job names no rule — and it is the trade CF-33 already made twice, at
harness.rs’s “there is deliberately no watchdog” and at ES-10’s note that a
store which cannot answer hangs rather than failing. The runbook item has
been amended to record it, so the next reader does not re-add it.
§Why the contenders are OS threads and not tasks
A rule body cannot call tokio::spawn. The testkit has no runtime
dependency and must not acquire one: CF-20 and CF-23 exist so that the suite
runs on wasm32 and under a caller-supplied harness, and a tokio in
[dependencies] here would end both. The runtime is the harness’s choice,
and the harness is the emitter.
std::thread::scope needs nothing from anybody. Each contender gets its
own thread and drives its own future with block_on, the
same park-loop the runtime-free emitter uses. That is strictly more hostile
than a work-stealing runtime, because preemption is the operating system’s
and does not wait for a suspension point the store may not have — which
matters most for the in-memory stores whose append bodies contain no
.await at all.
The limitation this buys, named now rather than discovered at phase 10.
A contender drives its future to completion on a bare thread, outside any
ambient reactor. A store whose futures need one — sqlx is the case in this
workspace — cannot be driven that way, and phase 10’s adapter will need the
spawn to become a parameter the harness supplies, exactly as the emitter
already is. Nothing here is designed against that; it is simply not designed
for it either, because no such adapter exists yet and a seam whose only
implementor is imaginary is a guess.
§The bound, and what the compiler said about each part of it
F: Fixture, F::Store: EventStore + SendSPECIFICATION.md CF-22 predicts S: SendEventStore + Send + Sync + 'static
and an Arc<S>. Three of those four turned out not to be needed, and the
method for finding out is memory.rs’s spawns_from_generic: remove each
bound in turn and ask the compiler, rather than writing down the bound that
sounds right.
-
Send— REQUIRED, and it is the whole of what makes this family opt-in. A contender’s handle is moved onto its thread. Remove it andScope::spawnreports its bound unsatisfied. A!Sendadapter — the Cloudflare Durable Object is the workspace’s — is excluded here and must be, which is the property ADR-0001 exists to keep optional. -
SendEventStore— NOT REQUIRED, which is the finding. CF-22 predicts it, the runbook’s work item specifies it, and the first draft of this module was written with it. Replacing it withEventStore + Sendcompiles, every rule unchanged. The reason is worth stating because it is the same observation ADR-0001 is built on, seen from the other side: a future only needs to beSendif it crosses a thread boundary, and here it does not. The handle crosses; the future is created on the contender’s thread byblock_onand driven to completion there.tokio::spawnwould need the future, because it hands a future to a runtime that may move it — which is exactly where CF-22’s prediction comes from, and it is a property of the spawner rather than of the port.So this module binds the weaker flavour, as CLAUDE.md’s fourth constraint asks: the exception it grants is a rule that genuinely needs
Send, and measurement says this one does not. Nothing is lost in practice —trait_variantemitspub trait SendEventStore: Send, so every adapter implementing theSendflavour satisfiesEventStore + Sendalready, and the weaker bound additionally admits a store whose handle isSendwhile its futures are not. -
Sync— NOT REQUIRED, because each contender owns its handle. A handle is moved into its thread rather than shared by reference, so the obligation isF::Store: Sendand never&F::Store: Send. It was measured firing when that discipline slipped: capturing the reader’s handle by reference inobserve_while_writinggives<F as Fixture>::Storecannot be shared between threads safely, and the fix is amoveclosure rather than a bound. TheArc<S>shape CF-22 predicts is what a task-based harness needs; N handles onto one store is the more faithful model of contention anyway, because that is what a connection pool hands out. -
'static— NOT REQUIRED, and this is what scoped threads are for.std::thread::scopeguarantees every thread has joined before it returns, so a contender may borrow from the rule’s own frame.tokio::spawncannot promise that, which is again the spawner rather than the port. Every rule below relies on it: the condition, the events and the query are built once on the rule’s stack and borrowed by all eight contenders.
The direction this can move is the safe one. Should phase 10 need the
contenders to become tasks on a harness-supplied runtime, the bound tightens
to something like CF-22’s prediction, and tightening a bound breaks
invocations. It is recorded here rather than hedged against: nothing is
published, the workspace’s every native adapter implements SendEventStore
and so satisfies either bound, and a bound written for a spawner nobody has
yet is a guess with a where clause.
One bound the port does not carry turns out to shape every rule here.
EventStore::Error has no Send bound (ES-6 is deferred), so a
Result<SequencePosition, AppendError<S::Error>> cannot be returned from a
contender’s thread. Each contender therefore collapses its result to
an Attempt, which is Send by construction. This is the same wall
spawns_from_generic hit and solved the same way — it collapses to a
usize — and it is the line that relaxes if ES-6 is ever settled.
§A busy refusal is an answer, and each rule has a floor under it
Until ADR-0077 every rule here read any answer other than a commit or a
violated condition as a failure. That made a store that was merely
contended, one that timed out on a lock or ran out of serialisation
retries, look exactly like a broken one. ES-43 gave that refusal a channel
of its own, AppendError::Busy, which promises that nothing was written.
So every rule now reads each contender per error. A commit is a win,
ConditionViolated is a loss where a condition exists, and Busy is
neither. Anything else, Store included, still fails the rule.
What stops that from being a tolerance is that each rule’s floor is
structural, not a fraction. At least one contender commits, because a store
where everybody is busy has made no progress. A boundary with no winner has
rejected nobody, because a violation needs a matching event to have landed.
Every committed batch is in the store, and nothing else is. None of those
reads a clock or counts operations, so CF-33 has nothing to object to. And
none says what share of contenders may be busy, which is what CF-34’s
Rejects: forbids. The half ES-43 adds, that a Busy answer left
nothing behind, is
a_busy_append_left_nothing_behind’s,
and BusyAfterWriteStore in the proof artefact is the store it rejects.
§This family carries its own enumeration and its own emitter
CF-22 requires one enumeration per rule family.
for_each_concurrency_rule! is this
one’s, beside the rules it names, for the reason model.rs gives: cargo xtask spec-trace scans suite.rs for pub async fn, and a rule written
there needs a clause of its own.
Fewer wrappers make sense here than in the store families, and that is not
a weakening of CF-23. The emitter is still a parameter; what narrows is
the set a racing family can be driven by — #[wasm_bindgen_test] has no
candidate, because this module does not exist on wasm32.
| Emitter | Wrapper | Adapter needs |
|---|---|---|
emit_concurrency_tokio (default) | #[tokio::test(flavor = "multi_thread")] | tokio with macros, rt-multi-thread |
emit_concurrency_blocking | #[test] + block_on | nothing |
The table is the count, in the crate root’s shape and for its reason:
this paragraph opened with a number that was wrong for as long as its second
row has existed. the_concurrency_page_lists_every_emitter_it_ships holds
these rows to this file’s macro_rules! definitions and refuses a spelled
count here; neither name is a link, because that check reads each cell as a
bare code span. The default
is multi_thread although the parallelism is in std::thread::scope,
because an adapter’s futures may need a multi-threaded reactor even when the
contention does not — and the blocking emitter races exactly as hard, which
makes it the honest default for an adapter with no runtime at all.
Modules§
- rules
- The rules of the concurrency family.
Constants§
- CONTENDERS
- How many contenders a racing rule starts.
Traits§
- Concurrent
Fixture - A
Fixturewhose handles can cross a thread boundary.