criterion/
macros.rs

Help
1//! Contains macros which together define a benchmark harness that can be used
2//! in place of the standard benchmark harness. This allows the user to run
3//! Criterion.rs benchmarks with `cargo bench`.
4
5/// Macro used to define a benchmark group for the benchmark harness; see the
6/// criterion_main! macro for more details.
7///
8/// This is used to define a benchmark group; a collection of related benchmarks
9/// which share a common configuration. Accepts two forms which can be seen
10/// below.
11///
12/// # Examples:
13///
14/// Complete form:
15///
16/// ```
17/// # #[macro_use]
18/// # extern crate criterion;
19/// # use criterion::Criterion;
20/// # fn bench_method1(c: &mut Criterion) {
21/// # }
22/// #
23/// # fn bench_method2(c: &mut Criterion) {
24/// # }
25/// #
26/// criterion_group!{
27///     name = benches;
28///     config = Criterion::default();
29///     targets = bench_method1, bench_method2
30/// }
31/// #
32/// # fn main() {}
33/// ```
34///
35/// In this form, all of the options are clearly spelled out. This expands to
36/// a function named benches, which uses the given config expression to create
37/// an instance of the Criterion struct. This is then passed by mutable
38/// reference to the targets.
39///
40/// Compact Form:
41///
42/// ```
43/// # #[macro_use]
44/// # extern crate criterion;
45/// # use criterion::Criterion;
46/// # fn bench_method1(c: &mut Criterion) {
47/// # }
48/// #
49/// # fn bench_method2(c: &mut Criterion) {
50/// # }
51/// #
52/// criterion_group!(benches, bench_method1, bench_method2);
53/// #
54/// # fn main() {}
55/// ```
56/// In this form, the first parameter is the name of the group and subsequent
57/// parameters are the target methods. The Criterion struct will be created using
58/// the `Criterion::default()` function. If you wish to customize the
59/// configuration, use the complete form and provide your own configuration
60/// function.
61#[macro_export]
62macro_rules! criterion_group {
63    (name = $name:ident; config = $config:expr; targets = $( $target:path ),+ $(,)*) => {
64        pub fn $name() {
65            let mut criterion: $crate::Criterion = $config
66                .configure_from_args();
67            $(
68                $target(&mut criterion);
69            )+
70        }
71    };
72    ($name:ident, $( $target:path ),+ $(,)*) => {
73        criterion_group!{
74            name = $name;
75            config = $crate::Criterion::default();
76            targets = $( $target ),+
77        }
78    }
79}
80
81/// Macro which expands to a benchmark harness.
82///
83/// Currently, using Criterion.rs requires disabling the benchmark harness
84/// generated automatically by rustc. This can be done like so:
85///
86/// ```toml
87/// [[bench]]
88/// name = "my_bench"
89/// harness = false
90/// ```
91///
92/// In this case, `my_bench` must be a rust file inside the 'benches' directory,
93/// like so:
94///
95/// `benches/my_bench.rs`
96///
97/// Since we've disabled the default benchmark harness, we need to add our own:
98///
99/// ```ignore
100/// #[macro_use]
101/// extern crate criterion;
102/// use criterion::Criterion;
103/// fn bench_method1(c: &mut Criterion) {
104/// }
105///
106/// fn bench_method2(c: &mut Criterion) {
107/// }
108///
109/// criterion_group!(benches, bench_method1, bench_method2);
110/// criterion_main!(benches);
111/// ```
112///
113/// The `criterion_main` macro expands to a `main` function which runs all of the
114/// benchmarks in the given groups.
115///
116#[macro_export]
117macro_rules! criterion_main {
118    ( $( $group:path ),+ $(,)* ) => {
119        fn main() {
120            $(
121                $group();
122            )+
123
124            $crate::Criterion::default()
125                .configure_from_args()
126                .final_summary();
127        }
128    }
129}
criterion/macros.rs

criterion/
macros.rs
