README.md

Calliper

Calliper is a Callgrind-based benchmarking harness with few-too-many knobs sticking out.

State: There's still a lot to do, but Calliper should be usable now. Note that I plan to break API prior to 1.0.0 arbitrarily in minor versions.

Table of contents

• Table of contents
  • Usage
  • Examples
  • License
  • Acknowledgmenets

Usage

To use Calliper, you must have Valgrind installed.

To write your first benchmark with Calliper, add the following to your Cargo.toml:

[dev-dependencies]
calliper = "0.1.4"

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

Then, create a file at $PROJECT/benches/my_first_calliper_benchmark.rs with the following contents:

use calliper::utils::black_box;
use calliper::{Runner, Scenario};

#[inline(never)]
#[no_mangle]
fn binary_search_impl(haystack: &[u8], needle: u8) -> Result<usize, usize> {
    haystack.binary_search(&needle)
}
fn bench_binary_search() {
    let range = (0..255).collect::<Vec<_>>();
    let _ = black_box(binary_search_impl(black_box(&range), black_box(253)));
}

#[inline(never)]
#[no_mangle]
fn linear_search_impl(haystack: &[u8], needle: u8) -> Option<usize> {
    haystack.iter().position(|n| *n == needle)
}

fn bench_linear_search() {
    let range = (0..255).collect::<Vec<_>>();
    black_box(linear_search_impl(black_box(&range), black_box(253)));
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runner = Runner::default();
    let benches = [
        Scenario::new(bench_linear_search),
        Scenario::new(bench_binary_search),
    ];
    if let Some(results) = runner.run(&benches)? {
        for res in results.into_iter() {
            println!("{}", res.parse());
        }
    }
    Ok(())
}

Now the benchmark can be executed with cargo bench.

More sophisticated examples can be found in benches folder of this repository.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Acknowledgements

Calliper is inspired by Iai benchmarking harness.