Skip to main content

Module concurrency

Module concurrency 

Available on non-WebAssembly only.
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 + Send

SPECIFICATION.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 and Scope::spawn reports its bound unsatisfied. A !Send adapter — 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 with EventStore + Send compiles, 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 be Send if it crosses a thread boundary, and here it does not. The handle crosses; the future is created on the contender’s thread by block_on and driven to completion there. tokio::spawn would 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_variant emits pub trait SendEventStore: Send, so every adapter implementing the Send flavour satisfies EventStore + Send already, and the weaker bound additionally admits a store whose handle is Send while 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 is F::Store: Send and never &F::Store: Send. It was measured firing when that discipline slipped: capturing the reader’s handle by reference in observe_while_writing gives <F as Fixture>::Store cannot be shared between threads safely, and the fix is a move closure rather than a bound. The Arc<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::scope guarantees every thread has joined before it returns, so a contender may borrow from the rule’s own frame. tokio::spawn cannot 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.

EmitterWrapperAdapter needs
emit_concurrency_tokio (default)#[tokio::test(flavor = "multi_thread")]tokio with macros, rt-multi-thread
emit_concurrency_blocking#[test] + block_onnothing

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§

ConcurrentFixture
A Fixture whose handles can cross a thread boundary.