Struct Bencher 

pub struct Bencher { /* private fields */ }

The Bencher provides iteration control for benchmarks.

The benchmark body calls exactly one iter* method once. That method runs warmup and measurement in full before it returns. Each sample holds per-iteration means over one batch of calls.

Implementations

impl Bencher

pub fn attach_runtime(&mut self, rt: Arc<Runtime>)

Attach the runtime that iter_async runs on.

The #[flux::bench] wrapper attaches the runtime it builds.

pub fn attach_runtime_error(&mut self, message: impl Into<String>)

Record a runtime build error. finish returns it as MeasureError::AsyncRuntime.

pub fn iter_async<T, F, Fut>(&mut self, f: F)

where F: FnMut() -> Fut, Fut: Future<Output = T>,

Measure an async closure. Each batch awaits n calls inside one block_on.

The timer covers creating and awaiting each future. It runs on the attached runtime. Without one, it builds a current-thread runtime once and keeps it. Call it from sync code or from a body that drive_async_body runs. A call inside a runtime context records MeasureError::AsyncRuntime and runs nothing.

pub fn iter_async_standalone<T, F, Fut>(&mut self, f: F)

where F: FnMut() -> Fut, Fut: Future<Output = T>,

👎Deprecated:

use iter_async

Measure an async closure. Same as iter_async.

impl Bencher

pub fn iter_with_setup<T, S, F, R>(&mut self, setup: S, routine: F)

where S: FnMut() -> T, F: FnMut(T) -> R,

Measure routine on fresh inputs from setup. Setup time is excluded.

Same as iter_batched(setup, routine, BatchSize::SmallInput).

pub fn iter_batched<T, S, F, R>( &mut self, setup: S, routine: F, size: BatchSize, )

where S: FnMut() -> T, F: FnMut(T) -> R,

Measure routine on inputs it takes by value. Setup time is excluded.

setup runs once per call. It builds each batch of inputs untimed. size sets the inputs per batch. One timer covers the routine over a batch. Outputs drop after the timer stops.

pub fn iter_batched_ref<T, S, F, R>( &mut self, setup: S, routine: F, size: BatchSize, )

where S: FnMut() -> T, F: FnMut(&mut T) -> R,

Measure routine on inputs it borrows mutably. Setup time is excluded.

Same batching as iter_batched. Inputs and outputs drop after the timer stops.

pub fn iter_batched_shared<T, S, F, R>( &mut self, batch_size: u64, setup: S, routine: F, )

where S: FnMut() -> T, F: FnMut(&T) -> R,

Measure routine on a shared input that setup rebuilds every batch_size calls.

batch_size sets only the setup cadence. A value of 0 rises to 1. Each sample calls setup ceil(iters_per_sample / batch_size) times, untimed.

impl Bencher

pub fn iter_custom<F>(&mut self, routine: F)

where F: FnMut(u64) -> Duration,

Measure a routine that times itself.

routine(iters) runs iters calls and returns the time they took. The engine runs warmup, sizes the samples, and calls it once per batch. The returned time is the sample total. No engine timer overhead is removed from it. Allocation counters cover the whole routine call. Cycle counts are 0.

impl Bencher

pub fn iter<T, F>(&mut self, f: F)

where F: FnMut() -> T,

Measure f. This call runs warmup and every sample.

One timer pair covers a whole batch of calls. Each sample holds the per-iteration mean of that batch.

impl Bencher

pub fn new(track_allocations: bool) -> Self

Create a Bencher with the default config and the given allocation tracking.

pub fn with_config(config: MeasureConfig) -> Self

Create a Bencher from a measurement config.

The config is normalized first: see MeasureConfig::normalized.

pub fn throughput(&mut self, throughput: Throughput)

Set the work one routine call processes. Reports turn it into a rate per second.

Call it anywhere in the body. The last call wins. It overrides throughput_bytes or throughput_elements on #[flux::bench] and #[flux::group].

pub fn with_sample_sink(self, sink: impl SampleSink + 'static) -> Self

Send each recorded sample to sink during measurement.

The sink runs between samples, outside every timed region. Samples still land in the result as before.

pub fn with_sample_count(track_allocations: bool, sample_count: usize) -> Self

Create a Bencher that targets sample_count samples. Other values are defaults.

The count has no upper cap. Values below MIN_SAMPLE_COUNT rise to it.

pub fn for_config( track_allocations: bool, sample_count: usize, iters_per_sample: Option<u64>, ) -> Self

Create a Bencher from sample values. Times and iteration limits are defaults.

Some(n) iterations per sample selects fixed mode. None selects time-based mode.

pub fn with_fixed_iters_per_sample(self, iters: u64) -> Self

Fix the iterations per sample. This selects fixed mode: no warmup, no estimation.

A value of 0 rises to 1.

pub fn config(&self) -> &MeasureConfig

The normalized measurement config

pub fn fixed_iters_per_sample(&self) -> Option<u64>

Fixed iterations per sample, if fixed mode is on

pub fn target_samples(&self) -> usize

Target sample count

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

Collected samples

pub fn iteration_count(&self) -> u64

Routine calls in the measurement phase so far. Warmup calls are excluded.

pub fn record_error(&mut self, error: MeasureError)

Record an error for finish to return. The first error wins.

pub fn finish(self) -> Result<BenchmarkResult, MeasureError>

Assemble the result, or return the first error the body caused.