Divan

Comfy benchmarking for Rust projects, brought to you by Nikolai Vazquez.

Sponsor

If you or your company find Divan valuable, consider sponsoring on GitHub or donating via PayPal. Sponsorships help me progress on what's possible with benchmarking in Rust.

Guide

A guide is being worked on. In the meantime, see:

• Announcement post
• "Proving Performance" FOSDEM talk

Getting Started

Divan 0.1.21 requires Rust 1.80.0 or later.

1. Add the following to your project's Cargo.toml:

   [dev-dependencies]
   divan = "0.1.21"
   
   [[bench]]
   name = "example"
   harness = false

2. Create a benchmarks file at benches/example.rs¹ with your benchmarking code:

   fn main() {
       // Run registered benchmarks.
       divan::main();
   }
   
   // Register a `fibonacci` function and benchmark it over multiple cases.
   #[divan::bench(args = [1, 2, 4, 8, 16, 32])]
   fn fibonacci(n: u64) -> u64 {
       if n <= 1 {
           1
       } else {
           fibonacci(n - 2) + fibonacci(n - 1)
       }
   }

3. Run your benchmarks with cargo bench:

   example       fastest  │ slowest  │ median   │ mean     │ samples │ iters
   ╰─ fibonacci           │          │          │          │         │
      ├─ 1       0.626 ns │ 1.735 ns │ 0.657 ns │ 0.672 ns │ 100     │ 819200
      ├─ 2       2.767 ns │ 3.154 ns │ 2.788 ns │ 2.851 ns │ 100     │ 204800
      ├─ 4       6.816 ns │ 7.671 ns │ 7.061 ns │ 7.167 ns │ 100     │ 102400
      ├─ 8       57.31 ns │ 62.51 ns │ 57.96 ns │ 58.55 ns │ 100     │ 12800
      ├─ 16      2.874 µs │ 3.812 µs │ 2.916 µs │ 3.006 µs │ 100     │ 200
      ╰─ 32      6.267 ms │ 6.954 ms │ 6.283 ms │ 6.344 ms │ 100     │ 100

See #[divan::bench] for info on benchmark function registration.

Checking benchmarks in CI

If you want to run each benchmarked function only once (to check that they don't panic without measuring their performance), you can run the benchmark runner crate with the --test parameter. You can do so by running either

cargo bench -- --test

or

cargo test --benches

Examples

Practical example benchmarks can be found in the examples/benches directory. These can be benchmarked locally by running:

git clone https://github.com/nvzqz/divan.git
cd divan

cargo bench -q -p examples --all-features

More thorough usage examples can be found in the #[divan::bench] documentation.

License

Like the Rust project, this library may be used under either the MIT License or Apache License (Version 2.0).

Footnotes

1. Within your crate directory, i.e. $CARGO_MANIFEST_DIR ↩