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