criterion/
macros.rs

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 function group for the benchmark harness; see the
6/// [`criterion_main!`](crate::criterion_main) macro for more details.
7///
8/// This is used to define a function group; a collection of functions to call with a common
9/// Criterion configuration. Accepts two forms which can be seen below.
10///
11/// Note that the group name given here is not important, it must simply be
12/// unique. Note also that this macro is not related to the
13/// [`Criterion::benchmark_group`](crate::Criterion::benchmark_group)  function
14/// or the [`BenchmarkGroup`](crate::BenchmarkGroup) type.
15///
16/// # Examples:
17///
18/// Complete form:
19///
20/// ```
21/// # use criterion::{criterion_group, Criterion};
22/// # fn bench_method1(c: &mut Criterion) {
23/// # }
24/// #
25/// # fn bench_method2(c: &mut Criterion) {
26/// # }
27/// #
28/// criterion_group!{
29///     name = benches;
30///     config = Criterion::default();
31///     targets = bench_method1, bench_method2
32/// }
33/// #
34/// # fn main() {}
35/// ```
36///
37/// In this form, all of the options are clearly spelled out. This expands to
38/// a function named `benches`, which uses the given config expression to create
39/// an instance of the [`Criterion`](crate::Criterion) struct. This is then
40/// passed by mutable reference to the targets.
41///
42/// Compact Form:
43///
44/// ```
45/// # use criterion::{criterion_group, 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        #[doc="The function which runs the benchmarks."]
65        pub fn $name() {
66            let mut criterion: $crate::Criterion<_> = $config
67                .configure_from_args();
68            $(
69                $target(&mut criterion);
70            )+
71        }
72    };
73    ($name:ident, $( $target:path ),+ $(,)*) => {
74        $crate::criterion_group!{
75            name = $name;
76            config = $crate::Criterion::default();
77            targets = $( $target ),+
78        }
79    }
80}
81
82/// Macro which expands to a benchmark harness.
83///
84/// Currently, using Criterion.rs requires disabling the benchmark harness
85/// generated automatically by rustc. This can be done like so:
86///
87/// ```toml
88/// [[bench]]
89/// name = "my_bench"
90/// harness = false
91/// ```
92///
93/// In this case, `my_bench` must be a rust file inside the 'benches' directory,
94/// like so:
95///
96/// `benches/my_bench.rs`
97///
98/// Since we've disabled the default benchmark harness, we need to add our own:
99///
100/// ```no_run
101/// use criterion::{criterion_group, criterion_main, Criterion};
102/// fn bench_method1(c: &mut Criterion) {
103/// }
104///
105/// fn bench_method2(c: &mut Criterion) {
106/// }
107///
108/// criterion_group!(benches, bench_method1, bench_method2);
109/// criterion_main!(benches);
110/// ```
111///
112/// The `criterion_main` macro expands to a `main` function which runs all of the
113/// benchmarks in the given groups.
114///
115#[macro_export]
116macro_rules! criterion_main {
117    ( $( $group:path ),+ $(,)* ) => {
118        fn main() {
119            $(
120                $group();
121            )+
122
123            $crate::Criterion::default()
124                .configure_from_args()
125                .final_summary();
126        }
127    }
128}
criterion/macros.rs

criterion/
macros.rs
