memory-ordering
The Release/Acquire pair the ring rests on, and what a change to any atomic ordering owes in evidence. Use when touching any Ordering in ring or kernel, when adding an atomic, when writing or changing
SKILL.md.claude/skills/memory-ordering/SKILL.md
GitHubMemory ordering
The ring's correctness rests on one Release store and one Acquire load.
Relaxed there passes every test on an x86 laptop and corrupts data on AArch64.
That sentence is the whole skill. Everything below follows from it.
What a change to an ordering owes
A litmus test that fails under the weaker ordering. Not a test that passes
under the stronger one — every test passes under the stronger one, which is why
a green run proves nothing and why this is stated as an obligation rather than a
suggestion. CONTRIBUTING.md requires it.
The test lives in ring/tests/litmus.rs and runs in release mode on AArch64 in
CI. Write it as a stress test with a stated repeat count and a stated failure
signature, and check that it actually goes red when you weaken the ordering, by
weakening the ordering and running it before you commit either.
Where the coverage ends
The litmus job is stress, not model checking. RustMC is what actually explores
what RC11 permits, and it is E0-P16, open — M5 arrived at E0-B12 and the
checker did not, so "lands at M5" is a sentence that stopped being true. Until
it exists the AArch64 unit tests plus the litmus job are the coverage, and the
gap is real — say so rather than implying the ring is verified.
Two things about that gap are now settled rather than open. The checker cannot
share this tree's toolchain — the pinned rustc bundles LLVM 22.1.8 and RustMC
requires LLVM 21 — so it brings its own, under RFC 0022. And it will not run the
litmus tests: cargo rustmc test explores a crate's test targets exhaustively,
so a model check needs its own small tests, two threads and a couple of entries,
beside the stress ones rather than instead of them. If you are writing a new
Release/Acquire pair, you owe a stress test today and a small exhaustible
test whenever E0-P16 lands; write the stress one so that shrinking it later is
a matter of constants rather than a rewrite.
The suite has three deliberate defects behind cargo features, and one of them
is a gate: mutate-no-doorbell-fence, on the x86-64 runner only. The two
that weaken a publishing store to Relaxed were gates for one run and the suite
passed with them on, on the arm runner. Do not re-add them as gates without new
evidence — that result is the measured size of the gap, and it is what E0-P16
exists to close.
Which runner catches a defect is a property of which reordering it depends on,
not of how serious it is. Store-load is the one reordering total store order
performs and the one AArch64 forbids — stlr/ldar are RCsc, so a
Store-Release followed by a Load-Acquire is already ordered there. So the
doorbell fence is caught on x86 and invisible on arm, which is the exact inverse
of every other ordering in this crate. Check which machine can see a defect
before deciding which job should assert it.
The rule that follows: if you weaken an ordering and the litmus suite stays green, you have learned nothing. Green there is not evidence the ordering was unnecessary; it is evidence the suite is a sampler.
Reviewing concurrent code here
- x86-64 total store order hides the entire class of bug this code is exposed to. A result from a local x86 run is not evidence about ordering.
- Name the pairing. Every
Releasehas anAcquirethat it synchronises with; if you cannot point at the partner, the ordering is decoration. SeqCstused to avoid thinking about the pairing is a finding. It is slower and it hides which invariant was intended.- Cursors on the same cache line are the first suspect when a submission
benchmark comes in high —
claims/0001-ring-submit-latency.tomlrecords that as its own first debugging step.