NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #1997 most downloaded on crates.io
A collection of histogram data structures
Latest stable
1.6.5
Last release 19 days ago
03 Nov 2026
Ships unpredictably
gaps range from 8 days to 10 months
Rarely documented
notes for 14 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
63 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
chore: bump to 1.6.5-alpha.0 for next development iteration by @thinkingfish in https://github.com/iopsystems/histogram/pull/56
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.6.4...v1.6.5
On x86_64, AtomicHistogram and AtomicHistogram32 compute the bucket
index in add and increment as lower_bin_count + log_bin * upper_bin_divisions + offset in u64, the form used before 1.6.4, and
keep the counter slice's bounds check as the range check. On other
targets, and in Histogram and Histogram32 everywhere, the 1.6.4 form
is unchanged. Results and errors are unchanged.
Single-thread recording throughput of the atomic path, as two ratios:
1.6.4 over 1.6.3, and the pre-1.6.4 form over the 1.6.4 form. Grouping
powers 3, 7 and 12; values uniform in 50,000..150,000 and log-uniform over
1..2^40; median of 5 interleaved 2-second runs per cell. The atomic path
is both a histogram::AtomicHistogram used directly and one shared
metriken AtomicCounterHistogram.
| Host | 1.6.4 / 1.6.3 | Pre-1.6.4 form / 1.6.4 form |
|---|---|---|
| AMD Threadripper 1950X (Zen 1), VM | 0.95 to 0.97 | 1.03 to 1.06 |
| AMD Threadripper 3970X (Zen 2), VM | 0.88 to 0.97 | 1.02 to 1.15 |
| AMD Ryzen 7 7840HS (Zen 4) | 0.99 to 1.04 | 0.97 to 1.03 |
| Raspberry Pi 4 (Cortex-A72) | 0.94 to 1.09 | 0.95 to 1.02 |
| Raspberry Pi 5 (Cortex-A76) | 1.04 to 1.09 | 0.95 to 1.02 |
| Apple M3 Ultra | 1.17 to 1.26 | 0.74 to 0.96 |
On Zen 4 the pre-1.6.4 form was 1.00x to 1.03x on the direct
AtomicHistogram and 0.97x to 1.01x on the shared metriken histogram. On
the Pi 4, 1.6.4 was 1.03x to 1.09x of 1.6.3 on the direct histogram and
0.94x to 0.99x on the shared one. The aarch64 rows are why the pre-1.6.4
form is limited to x86_64. Histogram throughput was the same with either
index form on every host (0.986 to 1.013); its code is identical in the
two builds, so it serves as the control.
The 1.6.4 entry's statement that the atomic histogram was unchanged was measured on one Intel host (Core i5-13500H). It does not hold on Zen 1 or Zen 2. This change has not been measured on Intel.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
chore: bump to 1.6.4-alpha.0 for next development iteration by @brayniac in https://github.com/iopsystems/histogram/pull/53
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.6.3...v1.6.4
(s << grouping_power) + (value >> s), the cancelled form of the
lower-bins plus log-bin times divisions plus offset formula, and lets the
counter slice's own bounds check serve as the range check. The hot path
loses a multiply, a subtraction, three field reads, the zero guard on the
leading-zero count and the explicit maximum test; results and errors are
unchanged. On a mixed linear/logarithmic stream, increment is 12% (u64)
to 16% (u32) faster on one x86 host; the atomic histogram is unchanged
because its locked add dominates.chore: bump to 1.6.3-alpha.0 for next development iteration by @brayniac in https://github.com/iopsystems/histogram/pull/50
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.6.2...v1.6.3
Config whose max is 2^max_value_power,
the encoding histogram 0.8.2 through 0.11.3 wrote when
max_value_power < 64, and decodes it as the current config
(2^max_value_power - 1). Since 1.6.0 such a config was rejected as
having inconsistent derived fields, so a histogram serialized by those
versions with max_value_power < 64, and anything containing it, failed
to decode. Every other inconsistent derived field is still rejected.chore: bump to 1.6.2-alpha.0 for next development iteration by @thinkingfish in https://github.com/iopsystems/histogram/pull/46
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.6.1...v1.6.2
increment() and add() on AtomicHistogram, AtomicHistogram32,
Histogram and Histogram32, the value-to-index and index-to-range
computations, as_slice() and as_mut_slice(), the Bucket getters,
Config::{grouping_power, max_value_power, total_buckets}, and next() on
the dense, sparse and cumulative bucket iterators and the cumulative
quantile-range iterator are #[inline], so a caller in another crate can
inline them, and the index computations they call, without LTO.
increment(), add() and the iterators' next() call other non-inline
functions, so rustc compiled them as out-of-line calls from another crate;
the small getters were already inlined as leaf functions and are annotated
for consistency.
Measured with #[inline] on AtomicHistogram::{increment, add} and the
value-to-index computation only, from a downstream crate on a Ryzen 7 7840HS
without LTO, median of 5 interleaved 2-second runs per arm, values in
million recorded values per second per thread:
| Path | Threads | 1.6.1 | 1.6.1 + inline recording path | 1.6.1 with fat LTO |
|---|---|---|---|---|
one AtomicHistogram per thread, through an inline wrapper |
1 | 406 | 555 | 561 |
one AtomicHistogram per thread, through an inline wrapper |
8 | 345 | 486 | 483 |
one shared AtomicHistogram, through metriken |
1 | 398 | 497 | 600 |
one shared AtomicHistogram, through metriken |
8 | 37 | 36 | 36 |
The shared-histogram path went through metriken's AtomicHistogram
wrapper, whose own increment() was an out-of-line call that the patch does
not touch. LTO also removed that call, which we take to explain the
difference between the last two columns: the per-thread path, whose wrapper
is inline, matches LTO. With eight threads on one histogram, inlining
changed nothing; we attribute that to contention on the shared cache line.
chore: bump to 1.6.1-alpha.0 for next development iteration by @thinkingfish in https://github.com/iopsystems/histogram/pull/41
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.6.0...v1.6.1
quantiles(), quantile_bucket(),
quantile_buckets_into() on Histogram and Histogram32) scan counters in
32-wide chunks summed in u64, which the compiler vectorizes, test the empty
ends of the array with an OR reduction instead of element by element, and
derive the occupied bounds and total in one pass over the occupied range. A
lane-wise OR accumulated in that pass decides once per report whether any
counter is at or above 2⁵⁹; only then is the occupied range re-summed in
u128 and the rank walk widened per counter, so results stay exact for
every total. Recording is unchanged and still keeps no running totals or
bounds.quantiles() clamps the nearest-rank target to the observation count. With
totals near 2⁶⁴ and above, floating-point rounding could request a rank past
the last bucket and silently drop that quantile from the result map.chore: bump to 1.5.1-alpha.0 for next development iteration by @brayniac in https://github.com/iopsystems/histogram/pull/26
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.5.0...v1.6.0
checked_sum() on Histogram and Histogram32 aggregates a batch of
completed windows or per-writer histograms into one fresh owned result. Every
configuration is validated before allocation; addition and per-bucket overflow
detection are fused into one pass per source, and a failing private result is
discarded. On x86 an AVX2 specialization is selected at runtime after the
CPU feature check; other hosts use the portable path.checked_add_assign() on Histogram and Histogram32: allocation-free
in-place merge with two-pass overflow validation and no partial mutation on
failure. The u32 validation pass reduces per-bucket overflow flags so large
arrays can vectorize.reset() on Histogram and Histogram32 clears every bucket in place while
preserving configuration and the existing allocation.load_into() and drain_into() on AtomicHistogram and AtomicHistogram32
fill an existing dense destination, rejecting incompatible configurations
before any mutation.quantile_bucket() and quantile_buckets_into() on
Histogram and Histogram32. Batches preserve request order and duplicates,
validate before writing, and share one forward rank scan.shrink_to_fit() on owned sparse and cumulative histograms, with both
u64 and u32 counters, to reduce spare vector capacity before retention.quantile_bucket() and quantile_buckets_into() queries on
owned and borrowed cumulative histograms, for both u64 and u32 counters.
Batch queries preserve request order and duplicates using caller-provided storage.Error::InsufficientOutputCapacity reports the required and available output
slots when a caller-provided query buffer is too short.u128 totals, validation and rank semantics are unchanged.Config and rebuilds dense, sparse and cumulative
histograms through their validating constructors; cumulative means are
recomputed from validated counts. Serialized field names and legacy JSON and
bincode round trips are preserved.Config construction rejects bucket geometries whose index or count fields
cannot fit u32 before arithmetic can overflow.QuantileResult: Add into_entries by @Lorak-mmk in https://github.com/iopsystems/histogram/pull/24
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.4.1...v1.5.0
QuantilesResult::into_entries() — consumes the result and returns the
quantile-to-bucket BTreeMap by value, allowing iterator transformations
without borrowing from the original result.Add mean() to borrowed CumulativeRO Ref views by @thinkingfish in https://github.com/iopsystems/histogram/pull/21
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.4.0...v1.4.1
mean() on the borrowed CumulativeROHistogramRef /
CumulativeROHistogram32Ref views. The mean is stored on the view
(computed once at construction, or carried over from the owned
histogram's cached value), so mean() is a cheap field access exposed
just like count() — no per-call streaming computation — letting a
zero-alloc reducer fold it in directly. Returns None for an empty
histogram.CumulativeROHistogramRef / CumulativeROHistogram32Ref no longer
implement Eq (they now carry an f64 mean); PartialEq is retained.Midpoint-based mean() on CumulativeROHistogram / CumulativeROHistogram32 — the mean of all observations, estimated from bucket midpoints, computed onc
mean() on CumulativeROHistogram / CumulativeROHistogram32
— the mean of all observations, estimated from bucket midpoints, computed
once at construction time across from_parts, From<&Histogram>, and
From<&SparseHistogram>. Returns None for an empty histogram.CumulativeROHistogram / CumulativeROHistogram32 no longer implement Eq
(they now store an f64 mean); PartialEq is retained. The borrowed
*Ref view types are unaffected.Plan: borrowed-view types for zero-allocation percentile queries by @thinkingfish in https://github.com/iopsystems/histogram/pull/16
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.3.0...v1.3.1
CumulativeROHistogramRef<'a> / CumulativeROHistogram32Ref<'a> and
SparseHistogramRef<'a> / SparseHistogram32Ref<'a> — borrowed views over
histogram storage that mirror the read-only API surface of the owned types.
Lets columnar consumers compute quantiles directly off &[u32] slices
without per-snapshot allocation or revalidation.from_parts_unchecked constructor on each ref type for hot-path use where
invariants are already known to hold; from_parts validates as before.as_ref() on CumulativeROHistogram* and SparseHistogram* returning the
matching ref view; From<&Owned> for OwnedRef<'_> for trait-based conversion.SampleQuantiles impl on each ref type.Add Notebook Kit site for h2histogram.org (alternative to #10) by @thinkingfish in https://github.com/iopsystems/histogram/pull/11
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.2.0...v1.3.0
Histogram32, AtomicHistogram32, SparseHistogram32, and
CumulativeROHistogram32 — u32-counter sibling types for all four histogram
variants, generated from shared declarative macrosCount and AtomicCount traits abstracting the bucket counter width
(implemented for u32/u64 and their atomic counterparts)From conversions (u32 → u64) for all four histogram
familiesTryFrom conversions (u64 → u32) for Histogram,
SparseHistogram, and CumulativeROHistogramTryFrom paths for the snapshot pipeline:
Histogram → CumulativeROHistogram32, Histogram → SparseHistogram32,
and SparseHistogram → CumulativeROHistogram32Histogram and AtomicHistogramrezolus_memory example comparing Histogram, SparseHistogram, and
CumulativeROHistogram memory footprints from Rezolus parquet recordingslib.rsCumulativeROHistogram cache-line threshold for linear-vs-binary search is
now count-type-dependent (64 / size_of::<C>()); total_count and
individual_count continue to return u64Add CumulativeROHistogram for fast quantile queries by @thinkingfish in https://github.com/iopsystems/histogram/pull/7
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.1.0...v1.2.0
CumulativeROHistogram, a read-only histogram variant with cumulative
(prefix-sum) counts that enables O(log n) quantile lookups via binary search
(with a linear-scan fallback for cache-line-sized data)From<&Histogram> and From<&SparseHistogram> conversions for constructing
a CumulativeROHistogramCumulativeROHistogram for analytics use
caseschore: bump to 1.0.1-alpha.0 for next development iteration by @brayniac in https://github.com/iopsystems/histogram/pull/2
Full Changelog: https://github.com/iopsystems/histogram/compare/v1.0.0...v1.1.0
SampleQuantiles trait with quantiles() and quantile() methods, implemented
for both Histogram and SparseHistogramQuantilesResult struct returning a BTreeMap<Quantile, Bucket> with
total_count, min, and max bucket metadataQuantile newtype wrapping validated f64 in 0.0..=1.0, implementing
Ord/Eq for use as a BTreeMap keyError::InvalidQuantile variant for quantile validation errorsHistogram::percentiles() and Histogram::percentile() — use SampleQuantiles
trait methods insteadSparseHistogram::percentiles() and SparseHistogram::percentile() — use
SampleQuantiles trait methods insteadError::InvalidPercentile — use Error::InvalidQuantile insteadrelease: v1.0.0 by @brayniac in https://github.com/iopsystems/histogram/pull/1
Full Changelog: https://github.com/iopsystems/histogram/commits/v1.0.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.