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