Struct SubMsPerfHarness 

pub struct SubMsPerfHarness { /* private fields */ }

A workload run. Owns raw samples + metadata only. Analysis and serialisation live in crate::bench - call summarize to lift this into a SubMsBenchSummary.

Implementations

impl SubMsPerfHarness

pub fn new(workload: &str, lang: &str) -> Self

Examples found in repository

examples/perf_main.rs (line 27)

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 set_sample_cap(&mut self, cap: usize) -> &mut Self

Max points kept in each stage’s emitted samples_ns timeline. Default 500; crate::benchmark sets it from crate::SubMsBenchParams::sample_cap. Clamped to at least 1.

pub fn sample_cap(&self) -> usize

The configured samples_ns downsample cap (see Self::set_sample_cap).

pub fn input(&mut self, key: &str, value: &str) -> &mut Self

Examples found in repository

examples/perf_main.rs (line 28)

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 add_meta(&mut self, key: &str, value: &str) -> &mut Self

Set a meta field. Renamed from {@code meta} so the {@link Self::meta} getter can keep its symmetric name with Java’s getter.

Examples found in repository

examples/perf_main.rs (line 29)

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 stage(&mut self, name: &str, capacity: usize) -> &mut SubMsStage

Create a stage; record samples via SubMsStage::time or SubMsStage::record.

Examples found in repository

examples/perf_main.rs (line 36)

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 with_observer(self, observer: Arc<dyn SubMsObserver>) -> Self

Register an observer to receive every recorded sample and the post-bench summary. Replaces any existing observer; updates already- created stages so they fire the new observer too. Returns self for builder-style chaining.

pub fn set_observer( &mut self, observer: Option<Arc<dyn SubMsObserver>>, ) -> &mut Self

Mutable setter for late wiring. None clears the observer.

pub fn observer(&self) -> Option<&Arc<dyn SubMsObserver>>

Read the currently-registered observer, if any. Mostly for tests.

pub fn stage_mut(&mut self, name: &str) -> Option<&mut SubMsStage>

Borrow a previously-created stage by name.

pub fn stage_by_name(&self, name: &str) -> Option<&SubMsStage>

pub fn stages(&self) -> &[SubMsStage]

pub fn workload(&self) -> &str

pub fn lang(&self) -> &str

pub fn inputs(&self) -> &BTreeMap<String, String>

pub fn meta(&self) -> &BTreeMap<String, String>

pub fn timestamp(&self) -> String

ISO-8601 seconds-precision timestamp captured at call time. Matches the on-disk JSON’s timestamp field.

pub fn write_json<W: Write>(&self, out: &mut W) -> Result<()>

Back-compat: summarise + emit JSON in the standard subms JSON shape. New code should call summarize then summary_to_json so the analyser is explicit.

pub fn discard_stage(&mut self, name: &str)

Drop a stage if you never recorded into it.

Trait Implementations

impl SubMsAssertionTarget for SubMsPerfHarness

fn lookup_p99_ns(&self, stage: &str) -> Option<u64>