Constant BUSY_TIMEOUT_MS
pub const BUSY_TIMEOUT_MS: u64 = 15_000;event-store or projection-store only.Expand description
How long a connection waits for a contended write lock before giving up, in milliseconds.
Finite and generous, and both halves are load-bearing. With many
connections on one file, BEGIN IMMEDIATE on a busy database returns
SQLITE_BUSY immediately unless a handler is configured, and that error
becomes an adapter failure rather than the contention it actually is. An
unbounded handler is the opposite mistake: there is no watchdog anywhere in
the conformance suite and there must not be one, so an unbounded wait
converts a livelock into a hung job that names no rule.
§Fifteen seconds, and why it is not five
ADR-0022 §11 set this to five seconds on a measurement that reported
busy = 0 in every row of its 64-contender table, and rested the value on
that zero: “the timeout did real work and never ran out”. That premise
is falsified. experiments/busy-timeout-margin — built to make §11’s own
re-open condition fireable, because nothing in the tree had ever reported a
busy count — recorded busy > 0 at the shipped CONTENDERS = 64 in one
launch of seven, with a margin of only 1.31x–1.38x on the plateau and every
wait figure a lower bound.
The consequence is not an unsound store. committed stays correct in every
row, so what fails is liveness, in the one place CF-33 guarantees the
suite cannot diagnose it: SQLITE_BUSY → AppendError::Store →
Attempt::Failed → a red rule telling an adapter author their store is
wrong when nothing about it is. That chain was true when this value was
chosen; ADR-0077 has since cut its second link, and the section below says
what that changed.
Fifteen was then measured rather than reasoned, on this adapter rather than on the experiment’s candidate — which is what closes that experiment’s own first caveat. Serialised so that all 64 contenders get the whole machine, which is the worst case this host can produce:
BUSY_TIMEOUT_MS | red launches |
|---|---|
| 5,000 | 7 of 8 |
| 15,000 | 0 of 16 |
| 30,000 | 0 of 8 |
It costs nothing in the healthy path, which is the argument that decided it over staying put: the handler returns the instant the lock is acquired, so the cap bounds only the pathological tail. Measured at the gate’s own parallelism, passing runs took 4.91–5.65 s at five seconds and 4.99–5.40 s at fifteen — indistinguishable. What the raise does buy is paid by a genuinely stuck writer, which now takes 15 s rather than 5 s to report; that path is rare and ends in a red rule rather than a hang.
Thirty seconds was rejected: also clean here, but with no measured gain over fifteen on this host, and it triples the pathological wait. The core sweep is what makes fifteen defensible off this host rather than lucky — fewer cores measured better, by about 450x from twenty cores to one, so a smaller CI runner sits in the safer regime rather than the riskier one.
§What this does not fix, and what did
Raising the cap lowered the rate at which a momentarily contended store
and a wrong one arrived as the same failed Attempt; it could not remove
the conflation, because CF-33 is [FROZEN] and denies a rule the clock that
would tell them apart. The channel did: ADR-0077 added
AppendError::Busy, and a BEGIN IMMEDIATE that runs out this timeout now
reports through it — see begin_error in the event store — so the
concurrency rules accept the refusal as legitimate, under structural floors,
rather than failing the adapter for it.
The value still matters, and for the same reason it was raised. A busy
contender is not a commit: the rules still require at least one commit and a
store where every contender is busy has made no progress, and an application
retrying Busy pays for every one it receives. Fifteen seconds keeps
Busy for a writer genuinely stuck behind another rather than for one
that merely queued behind 63 others.