Struct SubMsStage 

pub struct SubMsStage { /* private fields */ }

Per-stage sample buffer + recorder. Optionally annotated with a SubMsStageKind that sibling adapters (e.g. subms-otel) use to pick histogram bucket boundaries.

Implementations

impl SubMsStage

pub fn with_kind(&mut self, kind: SubMsStageKind) -> &mut Self

Annotate this stage’s kind so observers can pick fitting histogram buckets. Default is SubMsStageKind::Unspecified. Chainable.

pub fn record(&mut self, ns: u64)

Record an explicit duration in nanoseconds. Also fires the registered observer (if any).

Examples found in repository

examples/perf_main.rs (line 47)

fn main() {
    let mut h = SubMsPerfHarness::new("subms-self-bench", "rust");
    h.input("samples_per_stage", "50000");
    h.add_meta("rust_version", env!("CARGO_PKG_RUST_VERSION"));
    h.add_meta("crate_version", env!("CARGO_PKG_VERSION"));

    // 1. time_closure: cost of `stage.time(|| {})` with an empty closure.
    //    This is the per-iteration overhead any user pays when they wrap
    //    their hot path with `stage.time(...)`.
    {
        let s = h.stage("time_closure", 50_000);
        for _ in 0..50_000 {
            s.time(|| black_box(()));
        }
    }

    // 2. record_ns: cost of `stage.record(ns)` alone. No timer, just the
    //    Vec push. Strict lower bound on per-sample bookkeeping.
    {
        let s = h.stage("record_ns", 50_000);
        for i in 0..50_000u64 {
            s.record(black_box(100 + (i & 63)));
        }
    }

    // 3. summarize: sort + percentile extraction. Cost of producing one
    //    SubMsBenchSummary. We use SubMsTimer in a parallel harness so the
    //    measurement of the measurement isn't recursive.
    {
        let summary_target = build_sample_harness(50_000);
        let s = h.stage("summarize", 100);
        for _ in 0..100 {
            s.time(|| {
                let summary = summarize(black_box(&summary_target));
                black_box(summary);
            });
        }
    }

    // 4. summary_to_json: serialise to the canonical JSON shape. Cost paid
    //    by every CI run that uploads results.
    {
        let summary = summarize(&build_sample_harness(50_000));
        let s = h.stage("summary_to_json", 100);
        for _ in 0..100 {
            s.time(|| {
                let mut buf = Cursor::new(Vec::with_capacity(64 * 1024));
                summary_to_json(black_box(&summary), &mut buf).unwrap();
                let _ = buf.flush();
                black_box(buf);
            });
        }
    }

    // 5. diff_summary: regression-diff math between two SubMsBenchSummary
    //    objects. Cost paid by every PR-time gate.
    {
        let base: SubMsBenchSummary = summarize(&build_sample_harness(50_000));
        let cand: SubMsBenchSummary = summarize(&build_sample_harness(50_000));
        let s = h.stage("diff_summary", 1_000);
        for _ in 0..1_000 {
            s.time(|| {
                let d = subms::diff_summary(black_box(&base), black_box(&cand));
                black_box(d);
            });
        }
    }

    // Cross-check: SubMsTimer itself rolls a quick checkpoint walk so the
    // timer's marking overhead is also visible from this perf JSON's meta.
    let mut t = SubMsTimer::new("self-bench-wall");
    t.mark("stages-complete");
    t.stop("emitting-json");
    h.add_meta("self_bench_wall_ns", &t.elapsed_ns().to_string());

    let summary = summarize(&h);
    summary_to_json(&summary, &mut std::io::stdout()).unwrap();
}

/// Build a SubMsPerfHarness pre-populated with a synthetic stage's worth of
/// samples - used as fodder for the summarize / json / diff stages above.
fn build_sample_harness(n: usize) -> SubMsPerfHarness {
    let mut h = SubMsPerfHarness::new("fixture", "rust");
    let s = h.stage("fixture-stage", n);
    for i in 0..n as u64 {
        // Synthetic log-ish distribution: most samples small, a tail
        // exercises percentile sort + lookup.
        let v = if i % 1000 == 0 {
            10_000 + (i & 1023)
        } else {
            100 + (i & 63)
        };
        s.record(v);
    }
    h
}

pub fn time<F: FnOnce() -> R, R>(&mut self, f: F) -> R

Time a closure and record its duration.

Examples found in repository

examples/perf_main.rs (line 38)

fn main() {
    let mut h = SubMsPerfHarness::new("subms-self-bench", "rust");
    h.input("samples_per_stage", "50000");
    h.add_meta("rust_version", env!("CARGO_PKG_RUST_VERSION"));
    h.add_meta("crate_version", env!("CARGO_PKG_VERSION"));

    // 1. time_closure: cost of `stage.time(|| {})` with an empty closure.
    //    This is the per-iteration overhead any user pays when they wrap
    //    their hot path with `stage.time(...)`.
    {
        let s = h.stage("time_closure", 50_000);
        for _ in 0..50_000 {
            s.time(|| black_box(()));
        }
    }

    // 2. record_ns: cost of `stage.record(ns)` alone. No timer, just the
    //    Vec push. Strict lower bound on per-sample bookkeeping.
    {
        let s = h.stage("record_ns", 50_000);
        for i in 0..50_000u64 {
            s.record(black_box(100 + (i & 63)));
        }
    }

    // 3. summarize: sort + percentile extraction. Cost of producing one
    //    SubMsBenchSummary. We use SubMsTimer in a parallel harness so the
    //    measurement of the measurement isn't recursive.
    {
        let summary_target = build_sample_harness(50_000);
        let s = h.stage("summarize", 100);
        for _ in 0..100 {
            s.time(|| {
                let summary = summarize(black_box(&summary_target));
                black_box(summary);
            });
        }
    }

    // 4. summary_to_json: serialise to the canonical JSON shape. Cost paid
    //    by every CI run that uploads results.
    {
        let summary = summarize(&build_sample_harness(50_000));
        let s = h.stage("summary_to_json", 100);
        for _ in 0..100 {
            s.time(|| {
                let mut buf = Cursor::new(Vec::with_capacity(64 * 1024));
                summary_to_json(black_box(&summary), &mut buf).unwrap();
                let _ = buf.flush();
                black_box(buf);
            });
        }
    }

    // 5. diff_summary: regression-diff math between two SubMsBenchSummary
    //    objects. Cost paid by every PR-time gate.
    {
        let base: SubMsBenchSummary = summarize(&build_sample_harness(50_000));
        let cand: SubMsBenchSummary = summarize(&build_sample_harness(50_000));
        let s = h.stage("diff_summary", 1_000);
        for _ in 0..1_000 {
            s.time(|| {
                let d = subms::diff_summary(black_box(&base), black_box(&cand));
                black_box(d);
            });
        }
    }

    // Cross-check: SubMsTimer itself rolls a quick checkpoint walk so the
    // timer's marking overhead is also visible from this perf JSON's meta.
    let mut t = SubMsTimer::new("self-bench-wall");
    t.mark("stages-complete");
    t.stop("emitting-json");
    h.add_meta("self_bench_wall_ns", &t.elapsed_ns().to_string());

    let summary = summarize(&h);
    summary_to_json(&summary, &mut std::io::stdout()).unwrap();
}

pub fn warm_then_time<F: FnMut(usize)>( &mut self, warmup: usize, measured: usize, op: F, )

Warm, then record measured timed samples of op. Runs op for warmup untimed iterations first, then times measured more. op receives the iteration index on both passes (warmup: 0..warmup, measured: 0..measured); index a shorter input with i % len.

On this AOT-compiled side the warmup mainly primes caches and the branch predictor. The Java counterpart warmThenTime carries the real weight: it drives HotSpot to C2 (and lets escape analysis elide short-lived allocations) before any sample is recorded, without which a JIT-cold low-iteration stage reads orders of magnitude slow. The two harnesses expose the method symmetrically so a bench reads the same in either language.

pub fn with_pacing(&mut self, target_ops_per_second: f64) -> SubMsPacedStage<'_>

Wrap the stage in a coordinated-omission-corrected paced recorder. Each SubMsPacedStage::time call blocks until its intended slot, runs the workload, then records latency from the intended start time, which folds queue delay into the per-op number - the correction HdrHistogram exists for.

let mut h = SubMsPerfHarness::new("queue", "rust");
let stage = h.stage("offer", 100_000);
let mut paced = stage.with_pacing(10_000.0); // target 10k ops/sec
for _ in 0..100_000 { paced.time(|| do_work()); }

pub fn name(&self) -> &str

pub fn samples(&self) -> &[u64]