Skip to main content

BUSY_TIMEOUT_MS

Constant BUSY_TIMEOUT_MS 

pub const BUSY_TIMEOUT_MS: u64 = 15_000;
Available on crate features 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_MSred launches
5,0007 of 8
15,0000 of 16
30,0000 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.