On this page
Single-writer engine, many shared structures. The hierarchy below is verified against the code (call sites cited); any change that nests locks in the opposite direction must update this page and the reasoning, or revert.
The order (outer → inner)#
engine mutex (single-writer guard)
→ version-store mutex (MVCC chains)
→ leaf mutexes (brief, never held while acquiring anything else):
transaction-manager registry, gate-table map, per-gate state,
WAL internals, observability maps, worker inflight set,
maintenance claimsCondvar/barrier waits (liveness, not mutex nesting) always run with no outer mutex held: write-gate lanes are acquired without the engine mutex (first lane may block; further domains use try-acquire + conflict), and the group-commit barrier is waited on after dropping the engine guard.
Verified rules#
- Lanes are acquired outside the engine mutex.
lock_for_writefetches the gate Arc under one short acquisition, drops the guard, then blocks on the gate (concurrent.rs). On contention past the first lane the statement fails with a conflict and the executor aborts, releasing lanes — no A-holds-X-wants-Y cycle. - The engine mutex is never acquired while holding the version lock. The fast path takes the version lock alone; the fallback drops it before locking the engine (
committed_read). - The durability barrier runs free of outer locks.
commit_phasesdrops the engine guard beforewait_durable, and the flush runs after dropping barrier state — a slow fsync never wedges commits behind it. - Maintenance claims are leaf-scoped. Single-flight claim per table, released by
Drop; never held across engine acquisition. - Observability locks hash short strings only and are never taken while holding engine, gate, or barrier state.
What would break it#
- Blocking on a gate while holding the engine mutex (inverts 1).
- Taking the engine mutex under the version lock (inverts 2).
- Waiting on the barrier while holding the engine guard (inverts 3 — the test-only
commit_concurrentpath is exempt only because it never runs concurrently).
Was this page helpful? Thanks — noted locally, nothing is sent anywhere.