Read Path
The read path is the code that runs every time your application calls get
or get_as. Its contract is strict: no network call, file read, mutex, sleep,
retry, logging I/O or heap allocation in steady state.
Step by Step
Section titled “Step by Step”- Validate the name against the knob-name character rules with a constant lookup table. Invalid names fail before touching any state.
- Check CLI overrides. The override table is built once at startup and never changes. When there are no overrides, the pointer is null and this step is one branch.
- Load the snapshot.
SnapshotRefis an atomic shared pointer; loading it is one acquire operation plus a reference-count increment that keeps the snapshot alive for the duration of the read. - Look up the knob in an immutable sorted
detent::flat_mapwith transparent comparison, so thestd::string_viewname is used directly without building astd::string. - Evaluate with the precedence rules.
Only a percentage with a hash value pays for SHA-256.
get_as<T>then range-checks theint64intoT. - Count the outcome in a relaxed atomic counter and return.
Why an ordered map
Section titled “Why an ordered map”The knob table is a sorted vector, detent::flat_map, rather than a tree or
a hash table. Lookups binary-search one contiguous array, ordered iteration
makes serializing, diffing and merging snapshots linear passes, and entry
moves never throw, so a refused allocation leaves a table unchanged.
Why Immutable Snapshots
Section titled “Why Immutable Snapshots”Each update builds a brand-new Snapshot and publishes it with a single
release store. Readers that loaded the old pointer keep using the old snapshot
until their read finishes; the shared-pointer reference count frees it after
the last reader lets go. There’s no reader lock, no writer lock on the read
side, and no possibility of seeing half an update.
Pinned Views
Section titled “Pinned Views”read_view() performs the load once and hands you a ClientReadView that
holds the snapshot. Every read through the view sees the same configuration,
and the view stays valid across updates and even after the client is
destroyed.
For managed generations, the view instead holds an immutable evaluator over a memory-mapped image, published by the source’s refresh worker. Acquiring it is again an atomic load, with no filesystem work and no allocation.
Measured Cost
Section titled “Measured Cost”| Benchmark | Result |
|---|---|
detent_read_bench 4 2000000 | 6.71M reads/s across 4 threads, 149.1 ns/read |
detent_hash_bench 5000000 | 198.2 ns per stable_bucket() call |
The concurrency stress test runs readers against a continuously swapping updater, and the suite runs clean under ASan, UBSan and TSan on Linux.