Expand description
SharedHistogram - cross-process bucketed counter for
distribution tracking.
Fixed-bucket histogram: caller supplies N bucket boundaries at
create time. record(value) finds the right bucket via binary
search and atomically increments its counter. Useful for
latency distributions, request-size distributions, queue-depth
sampling - anything where N distributed processes need to
aggregate “how many in each bucket” into one shared view.
§Bucket semantics
For boundaries [b0, b1, b2, ..., bN-1]:
- Bucket 0: values
value < b0 - Bucket i (1..N-1): values
b{i-1} <= value < bi - Bucket N: values
value >= b{N-1}(the overflow bucket)
So a histogram with K boundaries has K+1 buckets.
§Layout
Single MMF file:
+---------------------------+
| HistogramHeader (64B) |
| magic, n_boundaries |
| total_count: AtomicU64 |
+---------------------------+
| boundaries [u64; N] | ascending; verified at open
+---------------------------+
| counters [AtomicU64; N+1] | one per bucket
+---------------------------+§Concurrency
Each bucket’s counter is its own AtomicU64. record uses
fetch_add(1, AcqRel) to atomically increment; multiple
recorders contend only on the SAME bucket’s cache line
(different buckets are fully concurrent).
§Percentile estimation
percentile(p) walks buckets accumulating counts until p of the
total is covered, then linearly interpolates within the target
bucket. For coarse boundaries the estimate has bucket-width
granularity; for log-spaced boundaries that’s typically <1
decade error which suffices for latency dashboards.