Divan

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.

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

• Announcement post
• "Proving Performance" FOSDEM talk

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.

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

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.

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