Crate divan

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

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

   [dev-dependencies]
   divan = "0.1.16"
   
   [[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.

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).

---

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

Modules

• counter
  Count values processed in each iteration to measure throughput.

Structs

• AllocProfiler
  Measures GlobalAlloc memory usage.
• Bencher
  Enables contextual benchmarking in #[divan::bench].
• Divan
  The benchmark runner.

Functions

• black_box
  Prevents compiler optimizations on a value.
• black_box_drop
  black_box + drop convenience function.
• main
  Runs all registered benchmarks.

Attribute Macros

• bench
  Registers a benchmarking function.
• bench_group
  Registers a benchmarking group.