|
2 | 2 |
|
3 | 3 | <div align="center">Statistics-driven Microbenchmarking in Rust</div> |
4 | 4 |
|
5 | | -<div align="center"> |
6 | | - <a href="https://bheisler.github.io/criterion.rs/book/getting_started.html">Getting Started</a> |
7 | | - | |
8 | | - <a href="https://bheisler.github.io/criterion.rs/book/index.html">User Guide</a> |
9 | | - | |
10 | | - <a href="https://bheisler.github.io/criterion.rs/criterion/">Master API Docs</a> |
11 | | - | |
12 | | - <a href="https://docs.rs/crate/criterion/">Released API Docs</a> |
13 | | - | |
14 | | - <a href="https://github.com/bheisler/criterion.rs/blob/master/CHANGELOG.md">Changelog</a> |
15 | | -</div> |
| 5 | +Due to Brook being missing for extended periods of time, active development of Criterion has moved to a new [Criterion-rs](https://github.com/criterion-rs) organization. Please direct your new PRs and issues to the new [criterion.rs repo](https://github.com/criterion-rs/criterion.rs). |
16 | 6 |
|
17 | | -<div align="center"> |
18 | | - <a href="https://github.com/bheisler/criterion.rs/actions/workflows/ci.yaml"> |
19 | | - <img src="https://img.shields.io/github/checks-status/rgeometry/rgeometry/main?label=tests&logo=github" alt="GitHub branch checks state"> |
20 | | - </a> |
21 | | - | |
22 | | - <a href="https://crates.io/crates/criterion"> |
23 | | - <img src="https://img.shields.io/crates/v/criterion.svg" alt="Crates.io"> |
24 | | - </a> |
25 | | -</div> |
| 7 | +Please provide some time for us to catch up and clean the large amount of pending PRs from this repo. Thank you! |
26 | 8 |
|
27 | | -Criterion.<span></span>rs helps you write fast code by detecting and measuring performance improvements or regressions, even small ones, quickly and accurately. You can optimize with confidence, knowing how each change affects the performance of your code. |
28 | | - |
29 | | -## Table of Contents |
30 | | - |
31 | | -- [Table of Contents](#table-of-contents) |
32 | | - - [Features](#features) |
33 | | - - [Quickstart](#quickstart) |
34 | | - - [Goals](#goals) |
35 | | - - [Contributing](#contributing) |
36 | | - - [Compatibility Policy](#compatibility-policy) |
37 | | - - [Maintenance](#maintenance) |
38 | | - - [License](#license) |
39 | | - - [Related Projects](#related-projects) |
40 | | - - [Criterion.rs Extensions](#criterionrs-extensions) |
41 | | - |
42 | | -### Features |
43 | | - |
44 | | -- __Statistics__: Statistical analysis detects if, and by how much, performance has changed since the last benchmark run |
45 | | -- __Charts__: Uses [gnuplot](http://www.gnuplot.info/) to generate detailed graphs of benchmark results |
46 | | -- __Stable-compatible__: Benchmark your code without installing nightly Rust |
47 | | - |
48 | | -### Quickstart |
49 | | - |
50 | | -In order to generate plots, you must have [gnuplot](http://www.gnuplot.info/) installed. See the gnuplot website for installation instructions. See [Compatibility Policy](#compatibility-policy) for details on the minimum supported Rust version. |
51 | | - |
52 | | -To start with Criterion.<span></span>rs, add the following to your `Cargo.toml` file: |
53 | | - |
54 | | -```toml |
55 | | -[dev-dependencies] |
56 | | -criterion = { version = "0.5", features = ["html_reports"] } |
57 | | - |
58 | | -[[bench]] |
59 | | -name = "my_benchmark" |
60 | | -harness = false |
61 | | -``` |
62 | | - |
63 | | -Next, define a benchmark by creating a file at `$PROJECT/benches/my_benchmark.rs` with the following contents: |
64 | | - |
65 | | -```rust |
66 | | -use std::hint::black_box; |
67 | | -use criterion::{criterion_group, criterion_main, Criterion}; |
68 | | - |
69 | | -fn fibonacci(n: u64) -> u64 { |
70 | | - match n { |
71 | | - 0 => 1, |
72 | | - 1 => 1, |
73 | | - n => fibonacci(n-1) + fibonacci(n-2), |
74 | | - } |
75 | | -} |
76 | | - |
77 | | -fn criterion_benchmark(c: &mut Criterion) { |
78 | | - c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20)))); |
79 | | -} |
80 | | - |
81 | | -criterion_group!(benches, criterion_benchmark); |
82 | | -criterion_main!(benches); |
83 | | -``` |
84 | | - |
85 | | -Finally, run this benchmark with `cargo bench`. You should see output similar to the following: |
86 | | - |
87 | | -``` |
88 | | - Running target/release/deps/example-423eedc43b2b3a93 |
89 | | -fib 20 time: [26.029 us 26.251 us 26.505 us] |
90 | | -Found 11 outliers among 99 measurements (11.11%) |
91 | | - 6 (6.06%) high mild |
92 | | - 5 (5.05%) high severe |
93 | | -``` |
94 | | - |
95 | | -See the [Getting Started](https://bheisler.github.io/criterion.rs/book/getting_started.html) guide for more details. |
96 | | - |
97 | | -### Goals |
98 | | - |
99 | | -The primary goal of Criterion.<span></span>rs is to provide a powerful and statistically rigorous tool for measuring the performance of code, preventing performance regressions and accurately measuring optimizations. Additionally, it should be as programmer-friendly as possible and make it easy to create reliable, useful benchmarks, even for programmers without an advanced background in statistics. |
100 | | - |
101 | | -### Contributing |
102 | | - |
103 | | -First, thank you for contributing. |
104 | | - |
105 | | -One great way to contribute to Criterion.<span></span>rs is to use it for your own benchmarking needs and report your experiences, file and comment on issues, etc. |
106 | | - |
107 | | -Code or documentation improvements in the form of pull requests are also welcome. If you're not |
108 | | -sure what to work on, try checking the |
109 | | -[Beginner label](https://github.com/bheisler/criterion.rs/issues?q=is%3Aissue+is%3Aopen+label%3ABeginner). |
110 | | - |
111 | | -If your issues or pull requests have no response after a few days, feel free to ping me (@bheisler). |
112 | | - |
113 | | -For more details, see the [CONTRIBUTING.md file](https://github.com/bheisler/criterion.rs/blob/master/CONTRIBUTING.md). |
114 | | - |
115 | | -### Compatibility Policy |
116 | | - |
117 | | -Criterion.<span></span>rs supports the last three stable minor releases of Rust. At time of |
118 | | -writing, this means Rust 1.59 or later. Older versions may work, but are not guaranteed. |
119 | | - |
120 | | -Currently, the oldest version of Rust believed to work is 1.57. Future versions of Criterion.<span></span>rs may |
121 | | -break support for such old versions, and this will not be considered a breaking change. If you |
122 | | -require Criterion.<span></span>rs to work on old versions of Rust, you will need to stick to a |
123 | | -specific patch version of Criterion.<span></span>rs. |
124 | | - |
125 | | -### Maintenance |
126 | | - |
127 | | -Criterion.<span></span>rs was originally created by Jorge Aparicio [(@japaric)](https://github.com/japaric) and is currently being maintained by Brook Heisler [(@bheisler)](https://github.com/bheisler). |
128 | | - |
129 | | -### License |
130 | | - |
131 | | -Criterion.<span></span>rs is dual licensed under the Apache 2.0 license and the MIT license. |
132 | | - |
133 | | -### Related Projects |
134 | | - |
135 | | -- [bencher](https://github.com/bluss/bencher) - A port of the libtest benchmark runner to stable Rust |
136 | | -- [criterion](http://www.serpentine.com/criterion/) - The Haskell microbenchmarking library that inspired Criterion.<span></span>rs |
137 | | -- [cargo-benchcmp](https://github.com/BurntSushi/cargo-benchcmp) - Cargo subcommand to compare the output of two libtest or bencher benchmark runs |
138 | | -- [cargo-flamegraph](https://github.com/ferrous-systems/flamegraph) - Cargo subcommand to profile an executable and produce a flamegraph |
139 | | - |
140 | | -### Criterion.rs Extensions |
141 | | - |
142 | | -- [criterion-cycles-per-byte](https://crates.io/crates/criterion-cycles-per-byte) - A custom-measurement plugin that counts the number of CPU cycles used by the benchmark |
143 | | -- [criterion-perf-events](https://crates.io/crates/criterion-perf-events) - A custom-measurement plugin that counts perf events created by the benchmark |
| 9 | +- Berkus |
| 10 | +- Lemmih |
0 commit comments