Struct GroupConfig 

#[non_exhaustive]
pub struct GroupConfig {

    pub max_rounds: usize,
    pub min_rounds: usize,
    pub warmup_time: Duration,
    pub max_time: Duration,
    pub min_iterations: usize,
    pub max_iterations: usize,
    pub cache_firewall: bool,
    pub cache_firewall_bytes: usize,
    pub baseline_only: Option<bool>,
    pub expect_sub_ns: bool,
    pub sort_by_speed: bool,
    pub auto_rounds: bool,
    pub target_precision: f64,
    pub max_wall_time: Duration,
    pub noise_threshold: f64,
    pub bootstrap_resamples: usize,
    pub cold_start: bool,
    pub sample_target_ns: u64,
    pub min_sample_ns: u64,
    pub linear_sampling: bool,
    pub stack_jitter: bool,
}

Configuration for a benchmark group’s execution.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

max_rounds: usize

Target number of measurement rounds.

min_rounds: usize

Minimum number of rounds before max_time is checked. Guarantees at least this many measurements even on slow benchmarks. Default: 5.

warmup_time: Duration

Warmup time before measurement begins.

max_time: Duration

Maximum total time for the group (measured in benchmark time, not wall time).

min_iterations: usize

Minimum iterations per sample.

max_iterations: usize

Maximum iterations per sample (default: 10M, high enough for sub-ns operations).

cache_firewall: bool

Whether to spoil CPU cache between samples.

When true, reads a large buffer between benchmarks in each round to evict hot cache lines. This prevents one benchmark’s output from remaining in L1/L2 where the next benchmark picks it up for free.

Default: false. Most microbenchmarks measure hot-path code where pointer-chasing (Box, Arc, vtable dispatch) stays in cache. The firewall penalizes these unfairly. Enable it when benchmarks touch different memory regions and you want cold-cache behavior.

cache_firewall_bytes: usize

Cache firewall size in bytes (default: 2 MiB, enough to spoil L2).

baseline_only: Option<bool>

Only compare against the baseline (first benchmark) in reports.

When false (default for <= 3 benchmarks), shows all pairwise comparisons. When true (default for > 3 benchmarks), only compares each benchmark against the first. Full pairwise data is always available in JSON output.

Set explicitly to override the auto-detection.

expect_sub_ns: bool

Suppress “likely optimized away” warnings for sub-nanosecond benchmarks.

Set to true when you know your benchmark genuinely runs in sub-ns time (e.g., a constant return or a single branch-predicted check).

sort_by_speed: bool

Sort benchmarks by speed (fastest first) in report output.

Default: false (definition order). When true, the table rows are sorted by mean time ascending.

auto_rounds: bool

Stop early when results are precise enough.

When true (default), measurement stops before rounds if the relative CI half-width drops below target_precision for all benchmarks. This saves time on clean systems and uses more rounds on noisy ones.

target_precision: f64

Target relative precision for auto-rounds (default: 0.02 = 2%).

Measurement stops when 1.96 * stddev / (sqrt(n) * mean) drops below this threshold — i.e., the 95% CI half-width is less than this fraction of the mean.

max_wall_time: Duration

Hard wall-clock time limit for the entire group (including gate waits).

Default: 120 seconds. Prevents runaway benchmarks from blocking CI or interactive use indefinitely. This is a safety net, not a tuning parameter — if you’re hitting it, your benchmarks are too slow or the system is too noisy.

noise_threshold: f64

Noise threshold for practical significance (default: 0.01 = 1%).

When set, a difference is only reported as significant if the entire 95% CI falls outside ±noise_threshold of zero (relative to baseline). This prevents “statistically significant but unmeasurably small” reports from triggering CI failures or green/red coloring.

Set to 0.0 to disable (pure CI-based significance).

bootstrap_resamples: usize

Number of bootstrap resamples for confidence intervals (default: 10,000).

Higher values give more precise CI bounds at the tails. 10K is fine for 95% CIs; increase to 100K for 99% CIs or extreme quantile work.

cold_start: bool

Cold-start measurement mode.

When true, forces min_iterations = 1, max_iterations = 1, and cache_firewall = true. Each sample is a single cold call with L2 cache spoiled between samples. Results reflect first-call performance, not hot-loop throughput.

Use for: CLI tools, serverless cold starts, first-request latency.

sample_target_ns: u64

Target time per sample in nanoseconds (default: 1,000,000 = 1ms).

The engine estimates how many iterations fit in this duration and uses that count for all samples. Lower values = shorter samples = less exposure to system noise per sample, but more timer overhead per iteration. Higher values = better amortization of timer overhead, but more context switches per sample on noisy systems.

The default of 1ms balances these concerns: at 10ns timer resolution, 1ms gives 100,000× resolution headroom while keeping samples short enough that context switches typically fall between samples, not within them.

min_sample_ns: u64

Minimum time per sample in nanoseconds (default: 5,000,000 = 5ms).

Hard floor on sample duration. Forces additional iterations when a single iteration is large enough that sample_target_ns would only fit one or two of them — short samples can’t absorb a single OS interrupt without skewing the result by 5–10%.

Concrete failure mode this guards against: a benchmark with a 500µs per-iteration cost paired with the default 1ms sample_target would run two iterations per sample. A 100µs context switch during that 1ms window swings the sample mean ~10%. Lifting the floor to 5ms pushes the sample to 10 iterations and dilutes the same context switch to ~2%.

Set to 0 to opt out (matches the pre-floor behavior).

linear_sampling: bool

Linear sampling mode for slope regression (default: false).

When enabled, iteration counts vary across rounds (0.2×–2.0× base, cycling every 10 rounds). This enables OLS regression through the origin to separate per-iteration cost from constant overhead — the same technique criterion uses in its Linear sampling mode.

Most impactful for sub-100ns benchmarks where timer/black_box overhead is a significant fraction of the measurement. For slower benchmarks (> 1µs), overhead compensation alone is sufficient.

stack_jitter: bool

Stack alignment jitter (default: true when precise-timing enabled).

Shifts the stack pointer by a random offset (0..4096 bytes, 16-byte aligned) before each sample. This varies cache-line alignment of stack variables across samples, defeating systematic bias from lucky/unlucky alignment (Mytkowicz et al., ASPLOS 2009).

Adds ~1-2µs overhead per sample from the recursive trampoline. Negligible for samples > 10µs, but disable for sub-µs measurements where the trampoline overhead would dominate.

Implementations

impl GroupConfig

pub fn max_rounds(&mut self, max_rounds: usize) -> &mut Self

pub fn min_rounds(&mut self, min_rounds: usize) -> &mut Self

pub fn warmup_time(&mut self, dur: Duration) -> &mut Self

pub fn max_time(&mut self, dur: Duration) -> &mut Self

pub fn cache_firewall(&mut self, enabled: bool) -> &mut Self

pub fn cache_firewall_bytes(&mut self, bytes: usize) -> &mut Self

pub fn sort_by_speed(&mut self, enabled: bool) -> &mut Self

pub fn baseline_only(&mut self, enabled: bool) -> &mut Self

pub fn expect_sub_ns(&mut self, enabled: bool) -> &mut Self

pub fn auto_rounds(&mut self, enabled: bool) -> &mut Self

pub fn target_precision(&mut self, precision: f64) -> &mut Self

pub fn max_wall_time(&mut self, dur: Duration) -> &mut Self

pub fn noise_threshold(&mut self, threshold: f64) -> &mut Self

Set the noise threshold for practical significance (default: 0.01 = 1%).

Changes smaller than this (as a fraction of baseline) are reported as “within noise” even if statistically significant. Set to 0.0 to disable.

pub fn bootstrap_resamples(&mut self, n: usize) -> &mut Self

Set the number of bootstrap resamples (default: 10,000).

pub fn cold_start(&mut self, enabled: bool) -> &mut Self

Enable cold-start mode: 1 call/sample with L2 cache spoiling.

Measures first-call performance, not hot-loop throughput.

pub fn sample_target_ns(&mut self, ns: u64) -> &mut Self

Set the target sample duration in nanoseconds (default: 1,000,000 = 1ms).

Lower = less noise exposure per sample (good for noisy systems). Higher = better timer overhead amortization (good for sub-ns benchmarks).

pub fn min_sample_ns(&mut self, ns: u64) -> &mut Self

Set the minimum sample duration in nanoseconds (default: 5,000,000 = 5ms).

Independent floor on sample duration. Set to 0 to disable.

pub fn linear_sampling(&mut self, enabled: bool) -> &mut Self

Enable linear sampling mode for slope regression.

pub fn stack_jitter(&mut self, enabled: bool) -> &mut Self

Enable or disable stack alignment jitter (default: true with precise-timing).

Randomizes stack pointer alignment before each sample to defeat cache-line alignment bias. Disable for sub-µs benchmarks where the ~1-2µs trampoline overhead would dominate.

Trait Implementations

impl Clone for GroupConfig

fn clone(&self) -> GroupConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GroupConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GroupConfig

fn default() -> Self

Returns the “default value” for a type.