criterion.rs compatibility layer documentation

A compatibility layer for criterion.rs

Overview

codspeed-criterion-compat is a Criterion.rs compatibility layer for CodSpeed that allows you to seamlessly integrate existing Criterion benchmarks with CodSpeed performance measurement.

This crate acts as a drop-in replacement for Criterion, maintaining your existing benchmark code while enabling CodSpeed integration.

Installation

cargo add --dev codspeed-criterion-compat --rename criterion

This will install the codspeed-criterion-compat crate and rename it to criterion in your Cargo.toml. This way, you can keep your existing imports and the compatibility layer will take care of the rest.

Using the compatibility layer won’t change the behavior of your benchmark suite and criterion will still run it as usual.

If you prefer, you can also install codspeed-criterion-compat as is and change your imports to use this new crate name.

Usage

Let’s start with the example from the Criterion.rs documentation, creating a benchmark suite for the Fibonacci function (in benches/my_benchmark.rs):

use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 1,
        1 => 1,
        n => fibonacci(n-1) + fibonacci(n-2),
    }
}

pub fn criterion_benchmark(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, criterion_benchmark);
criterion_main!(benches);

The last step in creating the Criterion benchmark is to add the new benchmark target in your Cargo.toml:

Cargo.toml

[[bench]]
name = "my_benchmark"
harness = false

And that’s it! You can now run your benchmark suite with cargo-codspeed:

terminal

$ cargo codspeed build
    Finished release [optimized] target(s) in 0.12s
    Finished built 1 benchmark suite(s)

$ cargo codspeed run
   Collected 1 benchmark suite(s) to run
     Running my_benchmark
Using codspeed-criterion-compat v1.0.0 compatibility layer
NOTICE: codspeed is enabled, but no performance measurement will be made since it's running in an unknown environment.
Checked: benches/bencher_example.rs::fib_20 (group: benches)
        Done running bencher_example
    Finished running 1 benchmark suite(s)

Compatibility

Not (yet) supported

• iter_custom
• with_filter

Resources

• Official criterion.rs documentation
• Official criterion.rs GitHub repository