Struct BenchSpec 

pub struct BenchSpec<'a> { /* private fields */ }

BenchSpec specifies various code fragments, most optional, that will be run during a benchmarking run for any supported language.

Examples

Python

BenchSpec::new(r#"
    # This code will be timed for benchmarking
    expensive_transform_function(data)
"#).with_sample_init(r#"
    # This code will be run once per sampling run
    data = db.fetch_random_sample_data()
"#).with_global_init(r#"
    # This code will run only once, when the benchmark is started
    db = connect("db://host/schema")
"#)

Loading code from external files

BenchSpec::new(include_str!("compute_bench.go.in"))
    .with_global_init(include_str!("compute_global_init.go.in"))

The .in suffix is entirely optional, but customarily indicates partial code that requires preprocessing and can’t be run independently.

Code Fragments

Timed

BenchSpec::new() / BenchSpec::from(&str)

Timed execution. This is the benchmark itself. Executed in a loop by Criterion hundreds to thousands of times per sampling run.

Sample Initialization

BenchSpec::with_sample_init()

(Optional) Not timed. Executed once per sampling run. (Re-)initializes starting conditions for a benchmark: e.g. generating random, unsorted data for a sort algorithm.

Global Initialization

BenchSpec::with_global_init()

(Optional) Not timed. Executed once, before benchmarking starts.

Example usage: Load or generate constant data. Instantiate required resources, like a database connection (or, in Zig, an allocator).

Imports

BenchSpec::with_imports()

(Optional) Not timed. Placed in the language-specific location for importing modules, including header files, etc.

Declarations

BenchSpec::with_declarations()

(Optional) Not timed. Placed at the top level of the benchmark harness, outside of any functions, for languages that do not allow certain declarations inside function bodies (otherwise Global Initialization could be used).

Variable Scope

From widest to narrowest scope

• Imports: should only contain #include/import/use/etc. statements; available to all other scopes
• Declarations: variables declared in this scope are available to all fragments
• Global: variables declared in this scope are available to sample and timed fragments
• Sample: all Global-declared variables are in scope
• Timed: all variables declared in Global and Sample fragments are in scope

Implementations

impl<'a> BenchSpec<'a>

pub fn new(timed_code: &'a str) -> Self

Create a new Timed code fragment to be benchmarked.

This code will be run hundreds to thousands of times by Criterion during the sampling process. The exact number of iterations is determined during the benchmarking warm-up process, based on Criterion::measurement_time.

pub fn with_global_init(self, code: &'a str) -> Self

Add a Global initializer for the benchmark.

This code will be run exactly one time, when the benchmark is started. It can declare variables, which will remain in scope for all other benchmark code.

pub fn with_sample_init(self, code: &'a str) -> Self

Add a Sample initializer for the benchmark.

This code will be called each time Criterion begins a sampling run. The number of sampling runs is determined by Criterion::sample_size. Any variables declared in a Global initializer are in scope.

pub fn with_declarations(self, code: &'a str) -> Self

Add constants or forward Declarations for the benchmark.

This fragment will be placed at the top level of the benchmark harness, after imports but before the Global initializer fragment is run. This fragment is not necessary for many languages but is useful for languages like C that may require forward declarations.

Depending on the languages rule about statements outside functions, this code may (e.g. Python or Ruby) or may not (e.g. C or Go) contain executable statements.

pub fn with_imports(self, code: &'a str) -> Self

Add Imports for the benchmark.

This fragment will be placed in the appropriate position to import modules (or the language-appropriate terminology) into the scope of all other code fragments. This fragment is only required for languages that do allow imports in function bodies or within arbitrary blocks (e.g. Go)

Trait Implementations

impl<'a> Clone for BenchSpec<'a>

fn clone(&self) -> BenchSpec<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for BenchSpec<'a>

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

Formats the value using the given formatter.

impl<'a> From<&'a str> for BenchSpec<'a>

fn from(timed_code: &'a str) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for BenchSpec<'a>

fn eq(&self, other: &BenchSpec<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Copy for BenchSpec<'a>

impl<'a> Eq for BenchSpec<'a>

impl<'a> StructuralPartialEq for BenchSpec<'a>