Real-time front end: atomic scalars, pooled snapshots, allocation-free takeSnapshot()

[facontidavide]

Summary

Replaces the snapshot front end with a design that never allocates on the snapshot thread after warm-up and never makes it wait for control work.

• Atomic scalars, one priority-inheriting write mutex. Scalar LoggedValue::set()/get() are wait-free relaxed atomics. Non-scalar values and scopedWrite() transactions share one PTHREAD_PRIO_INHERIT mutex with the snapshot thread.
• Snapshot pool. The first takeSnapshot() freezes the schema and reserves 64 slots. Later snapshots serialize directly into a free slot; sinks receive a reference-counted SnapshotRef instead of a copy.
• Publication instead of locking. Sink links and the enable mask are read through seq_cst atomics with an entry/exit epoch. Removing a sink or destroying a value publishes the change and waits only for a reader already inside; the snapshot thread never waits for control work.

Full write-up with diagram, measurements, review verdicts and the protobuf direction: https://claude.ai/code/artifact/e7f74b15-45a3-4ac5-93cd-7f132cceb882

Results

	before	after
heap allocations per snapshot (warm)	2 per sink	0 (exact, 60,000 calls)
mutexes on the snapshot path	shared_mutex + 2 structure mutexes	1 PI write mutex
p50 takeSnapshot(), 501 fields / 8 KB, 2 sinks, 2 transaction writers, pinned	~33 µs (Plan 3)	~30–36 µs (tied, 3 interleaved reps)

A 60 s compressed MCAP soak at 1 kHz: zero allocations, zero drops, 60,010 records validated by the mcap CLI.

API changes

• scopedWrite() new; Mutex now aliases the exclusive WriteMutex (no lock_shared()).
• Scalar getMutablePtr()/getConstPtr() deprecated in favor of set()/get(); LoggedValue no longer movable.
• New setPoolCapacity(), setPayloadCapacity(), setStrictMode(), stats(), poolExhausted(), droppedSnapshots(sink), DataSinkBase::storeErrors().
• DataSinkBase(queue_capacity); pushSnapshot removed; derived destructors must call stopThread(); callback-only retainSnapshot().
• MCAPSink and ROS2PublisherSink are Pimpl now (ABI change). finishQueueAndStop() no longer polls; stopping twice is harmless.
• Eight sinks per channel. Control operations must run outside writer guards and serializer callbacks.

See CHANGELOG.rst and the README "Real-time snapshot contract" section for the full list.

Test hardening

Running the suite under 16 CPU hogs exposed ~25 legacy tests that slept a fixed time hoping the sink worker had delivered; four failed under load. All now drain through DummySink::flush(). Also fixed: a lost-wakeup race in the pool contention test, an allocation counter blind to over-aligned operator new (the pool slot array is alignas(64)), a TSAN false positive from the vendored queue's fences (file-scoped suppression), several assertions that could not fail, and missing coverage for proxy move semantics, ValuePtr::detach() and removal overlapping a reader inside its epoch.

One production defect found in the process: MCAPSink::stopRecording()/addChannel() dereferenced a null writer after the recording was already stopped.

Verification

• Debug 131 / Release, ASAN+UBSAN, TSAN 130 tests: all pass (one privileged PI test skipped without CAP_SYS_NICE).
• Loaded stress: Debug ×15, TSAN ×5, ASAN ×3 under 16 busy-loop processes, zero failures.
• Mutation check: deleting the quiescence wait from removeDataSink() fails the overlap test on the first run.

Follow-ups considered and closed

Recorded in docs/superpowers/reviews/2026-09-11-frontend-refactoring-followups.md: the earlier "median regression" does not reproduce; immediate blocking instead of the 2 µs spin doubles blocking acquisitions for no gain; weaker atomic ordering has nothing to win on x86-64; the stop/join/drain/restart backend needs more lifecycle code than it removes.

Proposed next direction (not in this PR): protobuf output as a transcoding mode inside MCAPSink, keeping the real-time path unchanged.

🤖 Generated with Claude Code

[facontidavide]

Added a same-machine benchmark comparison of main vs this branch: docs/benchmarks/2026-09-12-main-vs-lockfree-frontend.md.

Measure	main	PR
Hot loop, 1000 doubles per snapshot	2,388 ns	774 ns
Hot loop, 1000 Pose structs	9,382 ns	5,059 ns
1 kHz probe, allocations per call, 1 sink	2	0
1 kHz probe, allocations per call, 4 sinks	8	0
1 kHz probe, p99.9, 4 sinks + 2 writers	110–132 µs	71–110 µs

Pinned to CPUs 2–7, runs interleaved, Release builds, GCC 15.2. Medians at a paced 1 kHz are within noise; the report lists caveats (frequency scaling, hybrid cores, 3 reps).