docs(cycle_bench): document Stats fields and use Display instead of ::format()

- Add /// doc comments on Stats {n, best_ms, mean_ms, stdev_ms}
  clarifying units, semantics, and Bessel's correction.
- Replace pub fn format(&self) -> String with impl fmt::Display for
  Stats, idiomatic and lets println! use {} directly.
- Update three call sites accordingly.
This commit is contained in:
Moudy 2026-05-18 16:37:11 +02:00
parent 28db42315b
commit b84a3e8b44
3 changed files with 16 additions and 10 deletions

View File

@ -581,7 +581,7 @@ fn print_table(results: &[BenchResult], prove: bool) {
let sw = 8_usize; let sw = 8_usize;
let exec_w = results let exec_w = results
.iter() .iter()
.map(|r| r.exec_stats.format().len()) .map(|r| r.exec_stats.to_string().len())
.max() .max()
.unwrap_or(0) .unwrap_or(0)
.max("exec_ms (best / mean ± stdev)".len()); .max("exec_ms (best / mean ± stdev)".len());
@ -594,11 +594,7 @@ fn print_table(results: &[BenchResult], prove: bool) {
for r in results { for r in results {
println!( println!(
"{:<pw$} {:<iw$} {:>cw$} {:>sw$} {:<exec_w$}", "{:<pw$} {:<iw$} {:>cw$} {:>sw$} {:<exec_w$}",
r.program, r.program, r.instruction, r.user_cycles, r.segments, r.exec_stats,
r.instruction,
r.user_cycles,
r.segments,
r.exec_stats.format(),
); );
} }

View File

@ -118,5 +118,5 @@ pub fn print_verify(r: &VerifyBenchResult) {
r.proof_bytes r.proof_bytes
); );
println!(" journal_bytes : {}", r.journal_bytes); println!(" journal_bytes : {}", r.journal_bytes);
println!(" verify_ms : {}", r.stats.format()); println!(" verify_ms : {}", r.stats);
} }

View File

@ -4,13 +4,20 @@
//! bench READMEs print) and mean +/- stdev (the figure the fee model wants, since //! bench READMEs print) and mean +/- stdev (the figure the fee model wants, since
//! it cares about the steady-state cost not a single fastest sample). //! it cares about the steady-state cost not a single fastest sample).
use std::fmt;
use serde::Serialize; use serde::Serialize;
#[derive(Debug, Serialize, Clone, Copy, Default)] #[derive(Debug, Serialize, Clone, Copy, Default)]
pub struct Stats { pub struct Stats {
/// Number of samples in the aggregate (excluding warmup).
pub n: usize, pub n: usize,
/// Lowest sample (ms). Strips OS jitter; matches the bench README "best of N" figure.
pub best_ms: f64, pub best_ms: f64,
/// Arithmetic mean of samples (ms).
pub mean_ms: f64, pub mean_ms: f64,
/// Sample standard deviation of samples (ms), computed with Bessel's correction (n-1).
/// 0.0 when n < 2.
pub stdev_ms: f64, pub stdev_ms: f64,
} }
@ -43,10 +50,13 @@ impl Stats {
stdev_ms, stdev_ms,
} }
} }
}
/// Format as `best / mean ± stdev (n=N)` for table display. /// `best / mean ± stdev (n=N)` for table display.
pub fn format(&self) -> String { impl fmt::Display for Stats {
format!( fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:.2} / {:.2} ± {:.2} (n={})", "{:.2} / {:.2} ± {:.2} (n={})",
self.best_ms, self.mean_ms, self.stdev_ms, self.n, self.best_ms, self.mean_ms, self.stdev_ms, self.n,
) )