Struct RunInitial 

pub struct RunInitial { /* private fields */ }

The first stage of configuring a benchmark run, with all type parameters unknown.

Implementations

impl RunInitial

pub fn groups(self, n: NonZero<usize>) -> Self

Divides the threads used for benchmarking into n equal groups. Defaults to 1 group.

The callbacks will be informed of which group they are executing for, and the total number of groups, via a RunMeta parameter.

Attempting to execute a run of a thread pool that is not evenly divisible by n will result in a panic.

pub fn prepare_thread<'a, F, ThreadState>( self, f: F, ) -> RunWithThreadState<'a, ThreadState>

where F: Fn(PrepareThread<'_>) -> ThreadState + Send + Sync + 'a,

Sets the callback used to prepare thread-scoped state for each thread used for benchmarking.

The thread-scoped state is later passed by shared reference to the “prepare iteration” callback when preparing each iteration.

Builder Order: This method can only be called on RunInitial. After calling this, you must use methods from RunWithThreadState for subsequent configuration.

Examples

use par_bench::Run;

let run = Run::new().prepare_thread(|_| "thread_state").iter(|_| {
    // Thread state is used internally; iter gets unit type by default
    std::hint::black_box(42);
});

pub fn prepare_iter<'a, F, IterState>( self, f: F, ) -> RunWithIterState<'a, (), IterState>

where F: Fn(PrepareIter<'_, ()>) -> IterState + Send + Sync + 'a,

Sets the callback used to prepare iteration-scoped state for each benchmark iteration.

Sets the callback used to prepare iteration-scoped state for each benchmark iteration.

This callback receives a shared reference to the thread-scoped state.

Every iteration is prepared before any iteration is executed.

Builder Order: This method can only be called on a RunInitial (no thread state). After calling this, you must use methods from RunWithIterState for subsequent configuration.

Examples

use par_bench::Run;

let run = Run::new().prepare_iter(|_| vec![1, 2, 3]).iter(|mut args| {
    // Use the per-iteration vector
    let iter_vec = args.take_iter_state();
    std::hint::black_box(iter_vec.len());
});

If you wish to specify a thread preparation function to provide state for each thread or iteration, do both before calling this method.

pub fn measure_wrapper<'a, FBegin, FEnd, MeasureWrapperState, MeasureOutput>( self, f_begin: FBegin, f_end: FEnd, ) -> RunWithWrapperState<'a, (), (), MeasureWrapperState, MeasureOutput>

where FBegin: Fn(MeasureWrapperBegin<'_, ()>) -> MeasureWrapperState + Send + Sync + 'a, FEnd: Fn(MeasureWrapperState) -> MeasureOutput + Send + Sync + 'a, MeasureOutput: Send + 'static,

Sets the callbacks used to wrap the measured part of a benchmark run, encompassing the execution (but not the preparation) of every iteration.

The f_begin callback is called before the first iteration of each thread, and the f_end callback is called after the last iteration of each thread. Any return value from the former is passed to the latter.

If you wish to specify a thread or iteration preparation function to provide state for each iteration, do it before calling this method.

pub fn iter<'a, F, CleanupState>( self, f: F, ) -> ConfiguredRun<'a, (), (), (), (), CleanupState>

where F: Fn(Iter<'_, (), ()>) -> CleanupState + Send + Sync + 'a,

Sets the callback used to execute the actual benchmark iterations.

This callback may return a value to drop after the measured part of the benchmark run (to exclude any cleanup logic from measurement).

This must be the last step in preparing a benchmark run. After this, the only action permitted is to execute the run.

If you wish to specify a thread or iteration preparation function to provide state for each thread or iteration, or a specify a measurement wrapper function, do all of these before calling this method.

Trait Implementations

impl Debug for RunInitial

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

Formats the value using the given formatter.

impl<'a> ResourceUsageExt<'a, ()> for RunInitial

Available on crate features all_the_time or alloc_tracker only.

type Output = RunWithWrapperState<'a, (), (), ResourceUsageState, ResourceUsageOutput>

The type returned when resource usage tracking is configured.

fn measure_resource_usage<F>( self, operation_name: &'a str, configure: F, ) -> Self::Output

where F: FnOnce(ResourceUsageMeasureBuilder<'a>) -> ResourceUsageMeasureBuilder<'a>,

Configures resource usage tracking for the benchmark run.