Struct Bench

pub struct Bench { /* private fields */ }

Benchmark.

This struct holds a single “bench” you wish to run. See the main crate documentation for more information.

Implementations

impl Bench

pub fn new<S>(name: S) -> Self

where S: AsRef<str>,

New.

Instantiate a new benchmark with a name. The name can be anything, but is intended to represent the method call itself, like foo::bar(10).

Note: the names should be unique across all benchmarks, as they serve as the key used when pulling “history”. If you have two totally different benchmarks named the same thing, the run-to-run change reporting won’t make any sense. ;)

Examples

use brunch::Bench;
use dactyl::{NiceU8, NiceU16};

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(0)")
        .run(|| NiceU8::from(0_u8)),
);

Panics

This method will panic if the name is empty.

pub const fn spacer() -> Self

Spacer.

This will render as a linebreak when printing results, useful if you want to add visual separation between two different benchmarks.

Examples

use brunch::Bench;
use dactyl::{NiceU8, NiceU16};

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(0)")
        .run(|| NiceU8::from(0_u8)),

    Bench::spacer(),

    Bench::new("dactyl::NiceU16::from(0)")
        .run(|| NiceU16::from(0_u16)),
);

pub const fn with_timeout(self, timeout: Duration) -> Self

With Time Limit.

By default, benches stop after reaching 2500 samples or 10 seconds, whichever comes first.

This method can be used to override the time limit portion of that equation.

Note: the minimum cutoff time is half a second.

Examples

use brunch::Bench;
use dactyl::NiceU8;
use std::time::Duration;

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(0)")
        .with_timeout(Duration::from_secs(1))
        .run(|| NiceU8::from(0_u8))
);

pub const fn with_samples(self, samples: u32) -> Self

With Sample Limit.

By default, benches stop after reaching 2500 samples or 10 seconds, whichever comes first.

This method can be used to override the sample limit portion of that equation.

Generally the default is a good sample size, but if your bench takes a while to complete, you might want to use this method to shorten it up.

Note: the minimum number of samples is 100, but you should aim for at least 150-200, because that minimum is applied after outliers have been removed from the set.

Examples

use brunch::Bench;
use dactyl::NiceU8;

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(0)")
        .with_samples(50_000)
        .run(|| NiceU8::from(0_u8))
);

impl Bench

pub fn run<F, O>(self, cb: F) -> Self

where F: FnMut() -> O,

Run Benchmark!

Use this method to execute a benchmark for a callback that does not require any external arguments.

Examples

use brunch::Bench;
use dactyl::NiceU8;

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(0)")
        .run(|| NiceU8::from(0_u8))
);

pub fn run_seeded<F, I, O>(self, seed: I, cb: F) -> Self

where F: FnMut(I) -> O, I: Clone,

Run Seeded Benchmark!

Use this method to execute a benchmark for a callback seeded with the provided value.

For seeds that don’t implement Clone, use Bench::run_seeded_with instead.

Examples

use brunch::Bench;
use dactyl::NiceU8;

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(13)")
        .run_seeded(13_u8, |v| NiceU8::from(v))
);

pub fn run_seeded_with<F1, F2, I, O>(self, seed: F1, cb: F2) -> Self

where F1: FnMut() -> I, F2: FnMut(I) -> O,

Run Callback-Seeded Benchmark!

Use this method to execute a benchmark for a callback seeded with the result of the provided method.

For seeds that implement Clone, use Bench::run_seeded instead.

Examples

use brunch::Bench;
use dactyl::NiceU8;

fn make_num() -> u8 { 13_u8 }

brunch::benches!(
    Bench::new("dactyl::NiceU8::from(13)")
        .run_seeded_with(make_num, |v| NiceU8::from(v))
);

Trait Implementations

impl Debug for Bench

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

Formats the value using the given formatter.

impl Extend<Bench> for Benches

fn extend<T: IntoIterator<Item = Bench>>(&mut self, iter: T)

Extend.

Insert Benches en-masse.

Examples

use brunch::{Benches, Bench};

let mut benches = Benches::default();
benches.extend([
    Bench::new("String::len").run(|| "Hello World".len()),
    Bench::spacer(),
]);
benches.finish();

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.