Struct ConcurrentHdrHistogram 

pub struct ConcurrentHdrHistogram { /* private fields */ }

Concurrent HDR histogram. All operations are lock-free.

Implementations

impl ConcurrentHdrHistogram

pub fn new(significant_digits: u32) -> Self

New histogram with the given significant-digit precision and default major-bucket capacity (32, tracking values past 4e12 at 3 sig-digits).

Examples found in repository

examples/sample_app.rs (line 134)

fn concurrent_feed_handlers() {
    use std::sync::Arc;
    use std::thread;
    use subms_hdr_histogram::ConcurrentHdrHistogram;
    println!("\n== concurrent-writes: many feed handlers, one histogram ==");
    let h = Arc::new(ConcurrentHdrHistogram::new(3));
    let threads = 4;
    let per_thread = 50_000u64;
    let mut handles = vec![];
    for _ in 0..threads {
        let h = h.clone();
        handles.push(thread::spawn(move || {
            for i in 0..per_thread {
                h.record((i % 1_000) + 500);
            }
        }));
    }
    for j in handles {
        j.join().unwrap();
    }
    println!(
        "  {} records lock-free, p99={}ns",
        h.count(),
        h.value_at_percentile(0.99)
    );
    assert_eq!(
        h.count(),
        threads as u64 * per_thread,
        "no writes lost under contention"
    );
}

examples/perf_features.rs (line 144)

fn main() -> io::Result<()> {
    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("..")
        .join(".subms")
        .join("features")
        .join("rust.json");
    let existing = std::fs::read_to_string(&path).unwrap_or_default();
    let mut manifest = SubMsFeatureManifest::load_str("rust", &existing);
    // Stamp the box these numbers came from. The bench runs wherever it is
    // invoked, so an unstamped manifest is indistinguishable from a fleet
    // capture; the renderer will not publish one it cannot attribute.
    let (source, instance) = SubMsP99Source::from_env();
    manifest.set_p99_source(source, instance.as_deref());

    // The baseline: base `record`, the per-op write path. Every feature is
    // classified against the cost of the write it is decorating.
    let mut base = HdrHistogram::new(CANON_D);
    let base_p50 = keyed(|i| base.record(value_at(i)), true);
    eprintln!("base record p50: {base_p50}ns");

    // ---------- concurrent-writes: atomic buckets, &self record ----------
    #[cfg(feature = "concurrent-writes")]
    {
        use subms_hdr_histogram::ConcurrentHdrHistogram;
        let sw = sweep("concurrent-writes/record", |d| {
            let c = ConcurrentHdrHistogram::new(d);
            keyed(|i| c.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let c = ConcurrentHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| c.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = c.value_at_percentile(99.0), false),
        );
        manifest.set_feature("concurrent-writes", cat, &p99, &reason);
    }

    // ---------- dual-recorder: hot/stable pair, swap and drain ----------
    #[cfg(feature = "dual-recorder")]
    {
        use subms_hdr_histogram::DualRecorder;
        // Swept on the interval read, not on `record`. The record is the same
        // atomic write the concurrent feature already covers; the swap-and-drain
        // is what a dual recorder is FOR, and it is O(buckets).
        let sw = sweep("dual-recorder/interval", |d| {
            let r = DualRecorder::new(d);
            for i in 0..sub_count(d) {
                r.record(value_at(i));
            }
            bulk(|| (), |()| _ = r.get_interval_histogram(), true)
        });
        // PINNED structural. The drain is O(buckets) from the source in BOTH
        // ports, but it is DESTRUCTIVE, so repeating it measures an already-empty
        // histogram rather than the drain: after the first rep each side has
        // nothing left to copy. Refilling between reps would put the refill
        // inside the timed region, which is the bug the ART port shipped. The
        // two ports disagree precisely here for that reason - Rust copies the
        // counter array unconditionally (468us at 262144 buckets) while Java
        // collapses a high-water index and reads 100ns - and neither number is
        // the operation a caller performs. Recording either as hot-path would
        // say a whole-array drain is safe per-op.
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let r = DualRecorder::new(CANON_D);
        for i in 0..OPS {
            r.record(value_at(i));
        }
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| r.record(value_at(i)), false),
        );
        p99.insert(
            "interval_read".to_string(),
            bulk(|| (), |()| _ = r.get_interval_histogram(), false),
        );
        manifest.set_feature("dual-recorder", cat, &p99, &reason);
    }

    // ---------- merge: element-wise add over the bucket arrays ----------
    #[cfg(feature = "merge")]
    {
        use subms_hdr_histogram::merge;
        // Both histograms are built by `setup`, outside the timed region.
        // Repeating the merge grows the destination's counts but does identical
        // work each rep, so the figure is the merge and nothing else.
        let sw = sweep("merge/merge", |d| {
            bulk(
                || (filled(d), filled(d)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                true,
            )
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut p99 = BTreeMap::new();
        p99.insert(
            "merge".to_string(),
            bulk(
                || (filled(CANON_D), filled(CANON_D)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                false,
            ),
        );
        manifest.set_feature("merge", cat, &p99, &reason);
    }

    // ---------- decay: exponentially-weighted counts ----------
    #[cfg(feature = "decay")]
    {
        use subms_hdr_histogram::{Clock, DecayingHdrHistogram};
        // The clock ADVANCES on every read. A frozen clock lets `decay_to_now`
        // early-return and the feature measures as a plain record, which is the
        // opposite of the truth: with time moving, every record first brings the
        // whole counter array up to date, so the write is O(buckets). Freezing
        // the clock here would have published that as hot-path.
        struct TickingClock(std::cell::Cell<u64>);
        impl Clock for TickingClock {
            fn now_ns(&self) -> u64 {
                self.0.set(self.0.get() + 1_000_000);
                self.0.get()
            }
        }
        let halflife = 1_000_000_000;
        let sw = sweep("decay/record", |d| {
            let mut x =
                DecayingHdrHistogram::new(d, halflife, TickingClock(std::cell::Cell::new(0)));
            keyed(|i| x.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut x =
            DecayingHdrHistogram::new(CANON_D, halflife, TickingClock(std::cell::Cell::new(0)));
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| x.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = x.value_at_percentile(99.0), false),
        );
        manifest.set_feature("decay", cat, &p99, &reason);
    }

    // ---------- value-tagging: a parallel histogram per tag ----------
    #[cfg(feature = "value-tagging")]
    {
        use subms_hdr_histogram::TaggedHdrHistogram;
        let sw = sweep("value-tagging/record", |d| {
            let mut t = TaggedHdrHistogram::new(d);
            keyed(|i| t.record(value_at(i), (i % 4) as u8), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut t = TaggedHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| t.record(value_at(i), (i % 4) as u8), false),
        );
        p99.insert(
            "percentile_for_tag".to_string(),
            keyed(|_| _ = t.value_at_percentile_for_tag(99.0, 0), false),
        );
        manifest.set_feature("value-tagging", cat, &p99, &reason);
    }

    // ---------- iterators: linear / logarithmic / percentile walks ----------
    #[cfg(feature = "iterators")]
    {
        // A percentile walk accumulates counts across the bucket array, so it is
        // O(buckets), and the sweep is monotonic and strongly rising. It is not
        // 64x: the walk emits a BOUNDED number of entries (1% steps, ~100 of
        // them) however large the array is, so the per-bucket work amortises
        // better at the top and it measures ~57x over a 128x span - under the
        // classifier's 0.5 guard.
        //
        // `iter_linear` was tried as the swept op instead, on the reasoning that
        // it visits every bucket. It does not: it steps by VALUE unit, so over a
        // 10^7 value range it emits millions of entries and the walk never
        // finished. Wrong op, not a slower one.
        //
        // PINNED structural rather than published as hot-path, which would tell
        // a reader a full percentile walk is safe per-operation. It is not.
        let sw = sweep("iterators/percentiles", |d| {
            let h = filled(d);
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), true)
        });
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let h = filled(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "iter_percentiles".to_string(),
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), false),
        );
        p99.insert(
            "iter_logarithmic".to_string(),
            bulk(|| (), |()| _ = h.iter_logarithmic().count(), false),
        );
        manifest.set_feature("iterators", cat, &p99, &reason);
    }

    std::fs::create_dir_all(path.parent().unwrap())?;
    std::fs::write(&path, manifest.to_json())?;
    io::stdout().write_all(manifest.to_json().as_bytes())?;
    Ok(())
}

pub fn with_majors(significant_digits: u32, majors: u32) -> Self

Explicit major-bucket capacity. Counter array length is sub_count * majors. Records that would land past the last bucket are clamped into the final bucket (no resize possible in a lock-free design).

pub fn sub_count(&self) -> u32

pub fn sub_count_bits(&self) -> u32

pub fn count(&self) -> u64

Examples found in repository

examples/sample_app.rs (line 151)

fn concurrent_feed_handlers() {
    use std::sync::Arc;
    use std::thread;
    use subms_hdr_histogram::ConcurrentHdrHistogram;
    println!("\n== concurrent-writes: many feed handlers, one histogram ==");
    let h = Arc::new(ConcurrentHdrHistogram::new(3));
    let threads = 4;
    let per_thread = 50_000u64;
    let mut handles = vec![];
    for _ in 0..threads {
        let h = h.clone();
        handles.push(thread::spawn(move || {
            for i in 0..per_thread {
                h.record((i % 1_000) + 500);
            }
        }));
    }
    for j in handles {
        j.join().unwrap();
    }
    println!(
        "  {} records lock-free, p99={}ns",
        h.count(),
        h.value_at_percentile(0.99)
    );
    assert_eq!(
        h.count(),
        threads as u64 * per_thread,
        "no writes lost under contention"
    );
}

pub fn max(&self) -> u64

pub fn record(&self, value: u64)

Record a value. Safe from any thread.

Examples found in repository

examples/sample_app.rs (line 142)

fn concurrent_feed_handlers() {
    use std::sync::Arc;
    use std::thread;
    use subms_hdr_histogram::ConcurrentHdrHistogram;
    println!("\n== concurrent-writes: many feed handlers, one histogram ==");
    let h = Arc::new(ConcurrentHdrHistogram::new(3));
    let threads = 4;
    let per_thread = 50_000u64;
    let mut handles = vec![];
    for _ in 0..threads {
        let h = h.clone();
        handles.push(thread::spawn(move || {
            for i in 0..per_thread {
                h.record((i % 1_000) + 500);
            }
        }));
    }
    for j in handles {
        j.join().unwrap();
    }
    println!(
        "  {} records lock-free, p99={}ns",
        h.count(),
        h.value_at_percentile(0.99)
    );
    assert_eq!(
        h.count(),
        threads as u64 * per_thread,
        "no writes lost under contention"
    );
}

examples/perf_features.rs (line 145)

fn main() -> io::Result<()> {
    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("..")
        .join(".subms")
        .join("features")
        .join("rust.json");
    let existing = std::fs::read_to_string(&path).unwrap_or_default();
    let mut manifest = SubMsFeatureManifest::load_str("rust", &existing);
    // Stamp the box these numbers came from. The bench runs wherever it is
    // invoked, so an unstamped manifest is indistinguishable from a fleet
    // capture; the renderer will not publish one it cannot attribute.
    let (source, instance) = SubMsP99Source::from_env();
    manifest.set_p99_source(source, instance.as_deref());

    // The baseline: base `record`, the per-op write path. Every feature is
    // classified against the cost of the write it is decorating.
    let mut base = HdrHistogram::new(CANON_D);
    let base_p50 = keyed(|i| base.record(value_at(i)), true);
    eprintln!("base record p50: {base_p50}ns");

    // ---------- concurrent-writes: atomic buckets, &self record ----------
    #[cfg(feature = "concurrent-writes")]
    {
        use subms_hdr_histogram::ConcurrentHdrHistogram;
        let sw = sweep("concurrent-writes/record", |d| {
            let c = ConcurrentHdrHistogram::new(d);
            keyed(|i| c.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let c = ConcurrentHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| c.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = c.value_at_percentile(99.0), false),
        );
        manifest.set_feature("concurrent-writes", cat, &p99, &reason);
    }

    // ---------- dual-recorder: hot/stable pair, swap and drain ----------
    #[cfg(feature = "dual-recorder")]
    {
        use subms_hdr_histogram::DualRecorder;
        // Swept on the interval read, not on `record`. The record is the same
        // atomic write the concurrent feature already covers; the swap-and-drain
        // is what a dual recorder is FOR, and it is O(buckets).
        let sw = sweep("dual-recorder/interval", |d| {
            let r = DualRecorder::new(d);
            for i in 0..sub_count(d) {
                r.record(value_at(i));
            }
            bulk(|| (), |()| _ = r.get_interval_histogram(), true)
        });
        // PINNED structural. The drain is O(buckets) from the source in BOTH
        // ports, but it is DESTRUCTIVE, so repeating it measures an already-empty
        // histogram rather than the drain: after the first rep each side has
        // nothing left to copy. Refilling between reps would put the refill
        // inside the timed region, which is the bug the ART port shipped. The
        // two ports disagree precisely here for that reason - Rust copies the
        // counter array unconditionally (468us at 262144 buckets) while Java
        // collapses a high-water index and reads 100ns - and neither number is
        // the operation a caller performs. Recording either as hot-path would
        // say a whole-array drain is safe per-op.
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let r = DualRecorder::new(CANON_D);
        for i in 0..OPS {
            r.record(value_at(i));
        }
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| r.record(value_at(i)), false),
        );
        p99.insert(
            "interval_read".to_string(),
            bulk(|| (), |()| _ = r.get_interval_histogram(), false),
        );
        manifest.set_feature("dual-recorder", cat, &p99, &reason);
    }

    // ---------- merge: element-wise add over the bucket arrays ----------
    #[cfg(feature = "merge")]
    {
        use subms_hdr_histogram::merge;
        // Both histograms are built by `setup`, outside the timed region.
        // Repeating the merge grows the destination's counts but does identical
        // work each rep, so the figure is the merge and nothing else.
        let sw = sweep("merge/merge", |d| {
            bulk(
                || (filled(d), filled(d)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                true,
            )
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut p99 = BTreeMap::new();
        p99.insert(
            "merge".to_string(),
            bulk(
                || (filled(CANON_D), filled(CANON_D)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                false,
            ),
        );
        manifest.set_feature("merge", cat, &p99, &reason);
    }

    // ---------- decay: exponentially-weighted counts ----------
    #[cfg(feature = "decay")]
    {
        use subms_hdr_histogram::{Clock, DecayingHdrHistogram};
        // The clock ADVANCES on every read. A frozen clock lets `decay_to_now`
        // early-return and the feature measures as a plain record, which is the
        // opposite of the truth: with time moving, every record first brings the
        // whole counter array up to date, so the write is O(buckets). Freezing
        // the clock here would have published that as hot-path.
        struct TickingClock(std::cell::Cell<u64>);
        impl Clock for TickingClock {
            fn now_ns(&self) -> u64 {
                self.0.set(self.0.get() + 1_000_000);
                self.0.get()
            }
        }
        let halflife = 1_000_000_000;
        let sw = sweep("decay/record", |d| {
            let mut x =
                DecayingHdrHistogram::new(d, halflife, TickingClock(std::cell::Cell::new(0)));
            keyed(|i| x.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut x =
            DecayingHdrHistogram::new(CANON_D, halflife, TickingClock(std::cell::Cell::new(0)));
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| x.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = x.value_at_percentile(99.0), false),
        );
        manifest.set_feature("decay", cat, &p99, &reason);
    }

    // ---------- value-tagging: a parallel histogram per tag ----------
    #[cfg(feature = "value-tagging")]
    {
        use subms_hdr_histogram::TaggedHdrHistogram;
        let sw = sweep("value-tagging/record", |d| {
            let mut t = TaggedHdrHistogram::new(d);
            keyed(|i| t.record(value_at(i), (i % 4) as u8), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut t = TaggedHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| t.record(value_at(i), (i % 4) as u8), false),
        );
        p99.insert(
            "percentile_for_tag".to_string(),
            keyed(|_| _ = t.value_at_percentile_for_tag(99.0, 0), false),
        );
        manifest.set_feature("value-tagging", cat, &p99, &reason);
    }

    // ---------- iterators: linear / logarithmic / percentile walks ----------
    #[cfg(feature = "iterators")]
    {
        // A percentile walk accumulates counts across the bucket array, so it is
        // O(buckets), and the sweep is monotonic and strongly rising. It is not
        // 64x: the walk emits a BOUNDED number of entries (1% steps, ~100 of
        // them) however large the array is, so the per-bucket work amortises
        // better at the top and it measures ~57x over a 128x span - under the
        // classifier's 0.5 guard.
        //
        // `iter_linear` was tried as the swept op instead, on the reasoning that
        // it visits every bucket. It does not: it steps by VALUE unit, so over a
        // 10^7 value range it emits millions of entries and the walk never
        // finished. Wrong op, not a slower one.
        //
        // PINNED structural rather than published as hot-path, which would tell
        // a reader a full percentile walk is safe per-operation. It is not.
        let sw = sweep("iterators/percentiles", |d| {
            let h = filled(d);
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), true)
        });
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let h = filled(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "iter_percentiles".to_string(),
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), false),
        );
        p99.insert(
            "iter_logarithmic".to_string(),
            bulk(|| (), |()| _ = h.iter_logarithmic().count(), false),
        );
        manifest.set_feature("iterators", cat, &p99, &reason);
    }

    std::fs::create_dir_all(path.parent().unwrap())?;
    std::fs::write(&path, manifest.to_json())?;
    io::stdout().write_all(manifest.to_json().as_bytes())?;
    Ok(())
}

pub fn value_at_percentile(&self, q: f64) -> u64

Snapshot-style percentile read. Walks the array with relaxed loads; not linearisable across all concurrent writers but each individual counter read is intact.

Examples found in repository

examples/sample_app.rs (line 152)

fn concurrent_feed_handlers() {
    use std::sync::Arc;
    use std::thread;
    use subms_hdr_histogram::ConcurrentHdrHistogram;
    println!("\n== concurrent-writes: many feed handlers, one histogram ==");
    let h = Arc::new(ConcurrentHdrHistogram::new(3));
    let threads = 4;
    let per_thread = 50_000u64;
    let mut handles = vec![];
    for _ in 0..threads {
        let h = h.clone();
        handles.push(thread::spawn(move || {
            for i in 0..per_thread {
                h.record((i % 1_000) + 500);
            }
        }));
    }
    for j in handles {
        j.join().unwrap();
    }
    println!(
        "  {} records lock-free, p99={}ns",
        h.count(),
        h.value_at_percentile(0.99)
    );
    assert_eq!(
        h.count(),
        threads as u64 * per_thread,
        "no writes lost under contention"
    );
}

examples/perf_features.rs (line 157)

fn main() -> io::Result<()> {
    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("..")
        .join(".subms")
        .join("features")
        .join("rust.json");
    let existing = std::fs::read_to_string(&path).unwrap_or_default();
    let mut manifest = SubMsFeatureManifest::load_str("rust", &existing);
    // Stamp the box these numbers came from. The bench runs wherever it is
    // invoked, so an unstamped manifest is indistinguishable from a fleet
    // capture; the renderer will not publish one it cannot attribute.
    let (source, instance) = SubMsP99Source::from_env();
    manifest.set_p99_source(source, instance.as_deref());

    // The baseline: base `record`, the per-op write path. Every feature is
    // classified against the cost of the write it is decorating.
    let mut base = HdrHistogram::new(CANON_D);
    let base_p50 = keyed(|i| base.record(value_at(i)), true);
    eprintln!("base record p50: {base_p50}ns");

    // ---------- concurrent-writes: atomic buckets, &self record ----------
    #[cfg(feature = "concurrent-writes")]
    {
        use subms_hdr_histogram::ConcurrentHdrHistogram;
        let sw = sweep("concurrent-writes/record", |d| {
            let c = ConcurrentHdrHistogram::new(d);
            keyed(|i| c.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let c = ConcurrentHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| c.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = c.value_at_percentile(99.0), false),
        );
        manifest.set_feature("concurrent-writes", cat, &p99, &reason);
    }

    // ---------- dual-recorder: hot/stable pair, swap and drain ----------
    #[cfg(feature = "dual-recorder")]
    {
        use subms_hdr_histogram::DualRecorder;
        // Swept on the interval read, not on `record`. The record is the same
        // atomic write the concurrent feature already covers; the swap-and-drain
        // is what a dual recorder is FOR, and it is O(buckets).
        let sw = sweep("dual-recorder/interval", |d| {
            let r = DualRecorder::new(d);
            for i in 0..sub_count(d) {
                r.record(value_at(i));
            }
            bulk(|| (), |()| _ = r.get_interval_histogram(), true)
        });
        // PINNED structural. The drain is O(buckets) from the source in BOTH
        // ports, but it is DESTRUCTIVE, so repeating it measures an already-empty
        // histogram rather than the drain: after the first rep each side has
        // nothing left to copy. Refilling between reps would put the refill
        // inside the timed region, which is the bug the ART port shipped. The
        // two ports disagree precisely here for that reason - Rust copies the
        // counter array unconditionally (468us at 262144 buckets) while Java
        // collapses a high-water index and reads 100ns - and neither number is
        // the operation a caller performs. Recording either as hot-path would
        // say a whole-array drain is safe per-op.
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let r = DualRecorder::new(CANON_D);
        for i in 0..OPS {
            r.record(value_at(i));
        }
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| r.record(value_at(i)), false),
        );
        p99.insert(
            "interval_read".to_string(),
            bulk(|| (), |()| _ = r.get_interval_histogram(), false),
        );
        manifest.set_feature("dual-recorder", cat, &p99, &reason);
    }

    // ---------- merge: element-wise add over the bucket arrays ----------
    #[cfg(feature = "merge")]
    {
        use subms_hdr_histogram::merge;
        // Both histograms are built by `setup`, outside the timed region.
        // Repeating the merge grows the destination's counts but does identical
        // work each rep, so the figure is the merge and nothing else.
        let sw = sweep("merge/merge", |d| {
            bulk(
                || (filled(d), filled(d)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                true,
            )
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut p99 = BTreeMap::new();
        p99.insert(
            "merge".to_string(),
            bulk(
                || (filled(CANON_D), filled(CANON_D)),
                |(dst, src)| merge(dst, src).expect("same precision"),
                false,
            ),
        );
        manifest.set_feature("merge", cat, &p99, &reason);
    }

    // ---------- decay: exponentially-weighted counts ----------
    #[cfg(feature = "decay")]
    {
        use subms_hdr_histogram::{Clock, DecayingHdrHistogram};
        // The clock ADVANCES on every read. A frozen clock lets `decay_to_now`
        // early-return and the feature measures as a plain record, which is the
        // opposite of the truth: with time moving, every record first brings the
        // whole counter array up to date, so the write is O(buckets). Freezing
        // the clock here would have published that as hot-path.
        struct TickingClock(std::cell::Cell<u64>);
        impl Clock for TickingClock {
            fn now_ns(&self) -> u64 {
                self.0.set(self.0.get() + 1_000_000);
                self.0.get()
            }
        }
        let halflife = 1_000_000_000;
        let sw = sweep("decay/record", |d| {
            let mut x =
                DecayingHdrHistogram::new(d, halflife, TickingClock(std::cell::Cell::new(0)));
            keyed(|i| x.record(value_at(i)), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut x =
            DecayingHdrHistogram::new(CANON_D, halflife, TickingClock(std::cell::Cell::new(0)));
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| x.record(value_at(i)), false),
        );
        p99.insert(
            "percentile".to_string(),
            keyed(|_| _ = x.value_at_percentile(99.0), false),
        );
        manifest.set_feature("decay", cat, &p99, &reason);
    }

    // ---------- value-tagging: a parallel histogram per tag ----------
    #[cfg(feature = "value-tagging")]
    {
        use subms_hdr_histogram::TaggedHdrHistogram;
        let sw = sweep("value-tagging/record", |d| {
            let mut t = TaggedHdrHistogram::new(d);
            keyed(|i| t.record(value_at(i), (i % 4) as u8), true)
        });
        let (cat, reason) = classify_feature(&sw, Some(base_p50), None);

        let mut t = TaggedHdrHistogram::new(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "record".to_string(),
            keyed(|i| t.record(value_at(i), (i % 4) as u8), false),
        );
        p99.insert(
            "percentile_for_tag".to_string(),
            keyed(|_| _ = t.value_at_percentile_for_tag(99.0, 0), false),
        );
        manifest.set_feature("value-tagging", cat, &p99, &reason);
    }

    // ---------- iterators: linear / logarithmic / percentile walks ----------
    #[cfg(feature = "iterators")]
    {
        // A percentile walk accumulates counts across the bucket array, so it is
        // O(buckets), and the sweep is monotonic and strongly rising. It is not
        // 64x: the walk emits a BOUNDED number of entries (1% steps, ~100 of
        // them) however large the array is, so the per-bucket work amortises
        // better at the top and it measures ~57x over a 128x span - under the
        // classifier's 0.5 guard.
        //
        // `iter_linear` was tried as the swept op instead, on the reasoning that
        // it visits every bucket. It does not: it steps by VALUE unit, so over a
        // 10^7 value range it emits millions of entries and the walk never
        // finished. Wrong op, not a slower one.
        //
        // PINNED structural rather than published as hot-path, which would tell
        // a reader a full percentile walk is safe per-operation. It is not.
        let sw = sweep("iterators/percentiles", |d| {
            let h = filled(d);
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), true)
        });
        let (cat, reason) = classify_feature(
            &sw,
            Some(base_p50),
            Some(subms::SubMsFeatureCategory::Structural),
        );

        let h = filled(CANON_D);
        let mut p99 = BTreeMap::new();
        p99.insert(
            "iter_percentiles".to_string(),
            bulk(|| (), |()| _ = h.iter_percentiles(1.0).count(), false),
        );
        p99.insert(
            "iter_logarithmic".to_string(),
            bulk(|| (), |()| _ = h.iter_logarithmic().count(), false),
        );
        manifest.set_feature("iterators", cat, &p99, &reason);
    }

    std::fs::create_dir_all(path.parent().unwrap())?;
    std::fs::write(&path, manifest.to_json())?;
    io::stdout().write_all(manifest.to_json().as_bytes())?;
    Ok(())
}

pub fn drain_snapshot(&self) -> Snapshot

Atomically drain every counter and total into a Snapshot, leaving the histogram empty. Used by DualRecorder to harvest the inactive side. Each per-counter swap is independent, so concurrent writers may land their increments in EITHER the drained snapshot OR the now-zeroed live histogram - we never double-count or lose a write.