calliper 0.1.4

Fine-grained benchmarking made easy.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

<h1 align="center">Calliper</h1>
Calliper is a Callgrind-based benchmarking harness with few-too-many knobs sticking out.

[![Docs](https://docs.rs/calliper/badge.svg)](https://docs.rs/calliper)

**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](#table-of-contents)
  - [Usage](#usage)
  - [Examples](#examples)
  - [License](#license)
  - [Acknowledgmenets](#acknowledgements)

## Usage
To use Calliper, you must have [Valgrind](https://valgrind.org/) installed. 

To write your first benchmark with Calliper, add the following to your `Cargo.toml`:
```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:

```rust
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](LICENSE-APACHE) or
   https://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
   https://opensource.org/licenses/MIT)

at your option.

## Acknowledgements
Calliper is inspired by [Iai benchmarking harness](https://github.com/bheisler/iai).