Struct divan::Divan

pub struct Divan { /* private fields */ }

The benchmark runner.

Implementations

impl Divan

pub fn main(&self)

Perform the configured action.

By default, this will be Divan::run_benches.

pub fn run_benches(&self)

Benchmark registered functions.

pub fn test_benches(&self)

Test registered functions as if the --test flag was used.

Unlike Divan::run_benches, this runs each benchmarked function only once.

pub fn list_benches(&self)

Print registered functions as if the --list flag was used.

impl Divan

Configuration options.

pub fn from_args() -> Self

Creates an instance with options set by parsing CLI arguments.

pub fn config_with_args(self) -> Self

Sets options by parsing CLI arguments.

This may override any previously-set options.

pub fn color(self, yes: impl Into<Option<bool>>) -> Self

Sets whether output should be colored.

This option is equivalent to the --color CLI argument, where None here means “auto”.

pub fn run_ignored(self) -> Self

Also run benchmarks marked #[ignore].

This option is equivalent to the --include-ignored CLI argument.

pub fn run_only_ignored(self) -> Self

Only run benchmarks marked #[ignore].

This option is equivalent to the --ignored CLI argument.

pub fn skip_regex(self, filter: impl SkipRegex) -> Self

Skips benchmarks that match filter as a regular expression pattern.

This option is equivalent to the --skip filter CLI argument, without --exact.

Examples

This method is commonly used with a &str or String:

let filter = "(add|sub)";
let divan = Divan::default().skip_regex(filter);

A pre-built Regex can also be provided:

let filter = regex::Regex::new("(add|sub)").unwrap();
let divan = Divan::default().skip_regex(filter);

Calling this repeatedly will add multiple skip filters:

let divan = Divan::default()
    .skip_regex("(add|sub)")
    .skip_regex("collections.*default");

Panics

Panics if filter is a string and Regex::new fails.

pub fn skip_exact(self, filter: impl Into<String>) -> Self

Skips benchmarks that exactly match filter.

This option is equivalent to the --skip filter --exact CLI arguments.

Examples

This method is commonly used with a &str or String:

let filter = "arithmetic::add";
let divan = Divan::default().skip_exact(filter);

Calling this repeatedly will add multiple skip filters:

let divan = Divan::default()
    .skip_exact("arithmetic::add")
    .skip_exact("collections::vec::default");

pub fn sample_count(self, count: u32) -> Self

Sets the number of sampling iterations.

This option is equivalent to the --sample-count CLI argument.

If a benchmark enables threads, sample count becomes a multiple of the number of threads. This is because each thread operates over the same sample size to ensure there are always N competing threads doing the same amount of work.

pub fn sample_size(self, count: u32) -> Self

Sets the number of iterations inside a single sample.

This option is equivalent to the --sample-size CLI argument.

pub fn threads<T>(self, threads: T) -> Self

where T: IntoIterator<Item = usize>,

Run across multiple threads.

This enables you to measure contention on atomics and locks. A value of 0 indicates available parallelism.

This option is equivalent to the --threads CLI argument or DIVAN_THREADS environment variable.

pub fn min_time(self, time: Duration) -> Self

Sets the time floor for benchmarking a function.

This option is equivalent to the --min-time CLI argument.

pub fn max_time(self, time: Duration) -> Self

Sets the time ceiling for benchmarking a function.

This option is equivalent to the --max-time CLI argument.

pub fn skip_ext_time(self, skip: bool) -> Self

When accounting for min_time or max_time, skip time external to benchmarked functions.

This option is equivalent to the --skip-ext-time CLI argument.

impl Divan

Use Counters to get throughput across all benchmarks.

pub fn counter<C: IntoCounter>(self, counter: C) -> Self

Counts the number of values processed.

pub fn items_count<C: Into<ItemsCount>>(self, count: C) -> Self

Sets the number of items processed.

This option is equivalent to the --items-count CLI argument or DIVAN_ITEMS_COUNT environment variable.

pub fn bytes_count<C: Into<BytesCount>>(self, count: C) -> Self

Sets the number of bytes processed.

This option is equivalent to the --bytes-count CLI argument or DIVAN_BYTES_COUNT environment variable.

pub fn bytes_format(self, format: BytesFormat) -> Self

Determines how BytesCount is scaled in benchmark outputs.

This option is equivalent to the --bytes-format CLI argument or DIVAN_BYTES_FORMAT environment variable.

pub fn chars_count<C: Into<CharsCount>>(self, count: C) -> Self

Sets the number of bytes processed.

This option is equivalent to the --chars-count CLI argument or DIVAN_CHARS_COUNT environment variable.

Trait Implementations

impl Debug for Divan

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

Formats the value using the given formatter.

impl Default for Divan

fn default() -> Divan

Returns the “default value” for a type.