1// Support for registering benchmarks for functions.
2
3/* Example usage:
4// Define a function that executes the code to be measured a
5// specified number of times:
6static void BM_StringCreation(benchmark::State& state) {
7 while (state.KeepRunning())
8 std::string empty_string;
9}
10
11// Register the function as a benchmark
12BENCHMARK(BM_StringCreation);
13
14// Define another benchmark
15static void BM_StringCopy(benchmark::State& state) {
16 std::string x = "hello";
17 while (state.KeepRunning())
18 std::string copy(x);
19}
20BENCHMARK(BM_StringCopy);
21
22// Augment the main() program to invoke benchmarks if specified
23// via the --benchmarks command line flag. E.g.,
24// my_unittest --benchmark_filter=all
25// my_unittest --benchmark_filter=BM_StringCreation
26// my_unittest --benchmark_filter=String
27// my_unittest --benchmark_filter='Copy|Creation'
28int main(int argc, char** argv) {
29 benchmark::Initialize(&argc, argv);
30 benchmark::RunSpecifiedBenchmarks();
31 return 0;
32}
33
34// Sometimes a family of microbenchmarks can be implemented with
35// just one routine that takes an extra argument to specify which
36// one of the family of benchmarks to run. For example, the following
37// code defines a family of microbenchmarks for measuring the speed
38// of memcpy() calls of different lengths:
39
40static void BM_memcpy(benchmark::State& state) {
41 char* src = new char[state.range(0)]; char* dst = new char[state.range(0)];
42 memset(src, 'x', state.range(0));
43 while (state.KeepRunning())
44 memcpy(dst, src, state.range(0));
45 state.SetBytesProcessed(int64_t(state.iterations()) *
46 int64_t(state.range(0)));
47 delete[] src; delete[] dst;
48}
49BENCHMARK(BM_memcpy)->Arg(8)->Arg(64)->Arg(512)->Arg(1<<10)->Arg(8<<10);
50
51// The preceding code is quite repetitive, and can be replaced with the
52// following short-hand. The following invocation will pick a few
53// appropriate arguments in the specified range and will generate a
54// microbenchmark for each such argument.
55BENCHMARK(BM_memcpy)->Range(8, 8<<10);
56
57// You might have a microbenchmark that depends on two inputs. For
58// example, the following code defines a family of microbenchmarks for
59// measuring the speed of set insertion.
60static void BM_SetInsert(benchmark::State& state) {
61 while (state.KeepRunning()) {
62 state.PauseTiming();
63 set<int> data = ConstructRandomSet(state.range(0));
64 state.ResumeTiming();
65 for (int j = 0; j < state.range(1); ++j)
66 data.insert(RandomNumber());
67 }
68}
69BENCHMARK(BM_SetInsert)
70 ->Args({1<<10, 1})
71 ->Args({1<<10, 8})
72 ->Args({1<<10, 64})
73 ->Args({1<<10, 512})
74 ->Args({8<<10, 1})
75 ->Args({8<<10, 8})
76 ->Args({8<<10, 64})
77 ->Args({8<<10, 512});
78
79// The preceding code is quite repetitive, and can be replaced with
80// the following short-hand. The following macro will pick a few
81// appropriate arguments in the product of the two specified ranges
82// and will generate a microbenchmark for each such pair.
83BENCHMARK(BM_SetInsert)->Ranges({{1<<10, 8<<10}, {1, 512}});
84
85// For more complex patterns of inputs, passing a custom function
86// to Apply allows programmatic specification of an
87// arbitrary set of arguments to run the microbenchmark on.
88// The following example enumerates a dense range on
89// one parameter, and a sparse range on the second.
90static void CustomArguments(benchmark::internal::Benchmark* b) {
91 for (int i = 0; i <= 10; ++i)
92 for (int j = 32; j <= 1024*1024; j *= 8)
93 b->Args({i, j});
94}
95BENCHMARK(BM_SetInsert)->Apply(CustomArguments);
96
97// Templated microbenchmarks work the same way:
98// Produce then consume 'size' messages 'iters' times
99// Measures throughput in the absence of multiprogramming.
100template <class Q> int BM_Sequential(benchmark::State& state) {
101 Q q;
102 typename Q::value_type v;
103 while (state.KeepRunning()) {
104 for (int i = state.range(0); i--; )
105 q.push(v);
106 for (int e = state.range(0); e--; )
107 q.Wait(&v);
108 }
109 // actually messages, not bytes:
110 state.SetBytesProcessed(
111 static_cast<int64_t>(state.iterations())*state.range(0));
112}
113BENCHMARK_TEMPLATE(BM_Sequential, WaitQueue<int>)->Range(1<<0, 1<<10);
114
115Use `Benchmark::MinTime(double t)` to set the minimum time used to run the
116benchmark. This option overrides the `benchmark_min_time` flag.
117
118void BM_test(benchmark::State& state) {
119 ... body ...
120}
121BENCHMARK(BM_test)->MinTime(2.0); // Run for at least 2 seconds.
122
123In a multithreaded test, it is guaranteed that none of the threads will start
124until all have called KeepRunning, and all will have finished before KeepRunning
125returns false. As such, any global setup or teardown you want to do can be
126wrapped in a check against the thread index:
127
128static void BM_MultiThreaded(benchmark::State& state) {
129 if (state.thread_index == 0) {
130 // Setup code here.
131 }
132 while (state.KeepRunning()) {
133 // Run the test as normal.
134 }
135 if (state.thread_index == 0) {
136 // Teardown code here.
137 }
138}
139BENCHMARK(BM_MultiThreaded)->Threads(4);
140
141
142If a benchmark runs a few milliseconds it may be hard to visually compare the
143measured times, since the output data is given in nanoseconds per default. In
144order to manually set the time unit, you can specify it manually:
145
146BENCHMARK(BM_test)->Unit(benchmark::kMillisecond);
147*/
148
149#ifndef BENCHMARK_BENCHMARK_API_H_
150#define BENCHMARK_BENCHMARK_API_H_
151
152#include <assert.h>
153#include <stddef.h>
154#include <stdint.h>
155
156#include <string>
157#include <vector>
158
159#include "macros.h"
160
161#if defined(BENCHMARK_HAS_CXX11)
162#include <type_traits>
163#include <utility>
164#endif
165
166namespace benchmark {
167class BenchmarkReporter;
168
169void Initialize(int* argc, char** argv);
170
171// Generate a list of benchmarks matching the specified --benchmark_filter flag
172// and if --benchmark_list_tests is specified return after printing the name
173// of each matching benchmark. Otherwise run each matching benchmark and
174// report the results.
175//
176// The second and third overload use the specified 'console_reporter' and
177// 'file_reporter' respectively. 'file_reporter' will write to the file
178// specified
179// by '--benchmark_output'. If '--benchmark_output' is not given the
180// 'file_reporter' is ignored.
181//
182// RETURNS: The number of matching benchmarks.
183size_t RunSpecifiedBenchmarks();
184size_t RunSpecifiedBenchmarks(BenchmarkReporter* console_reporter);
185size_t RunSpecifiedBenchmarks(BenchmarkReporter* console_reporter,
186 BenchmarkReporter* file_reporter);
187
188// If this routine is called, peak memory allocation past this point in the
189// benchmark is reported at the end of the benchmark report line. (It is
190// computed by running the benchmark once with a single iteration and a memory
191// tracer.)
192// TODO(dominic)
193// void MemoryUsage();
194
195namespace internal {
196class Benchmark;
197class BenchmarkImp;
198class BenchmarkFamilies;
199
200template <class T>
201struct Voider {
202 typedef void type;
203};
204
205template <class T, class = void>
206struct EnableIfString {};
207
208template <class T>
209struct EnableIfString<T, typename Voider<typename T::basic_string>::type> {
210 typedef int type;
211};
212
213void UseCharPointer(char const volatile*);
214
215// Take ownership of the pointer and register the benchmark. Return the
216// registered benchmark.
217Benchmark* RegisterBenchmarkInternal(Benchmark*);
218
219// Ensure that the standard streams are properly initialized in every TU.
220int InitializeStreams();
221BENCHMARK_UNUSED static int stream_init_anchor = InitializeStreams();
222
223} // end namespace internal
224
225// The DoNotOptimize(...) function can be used to prevent a value or
226// expression from being optimized away by the compiler. This function is
227// intended to add little to no overhead.
228// See: https://youtu.be/nXaxk27zwlk?t=2441
229#if defined(__GNUC__)
230template <class Tp>
231inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
232 asm volatile("" : : "g"(value) : "memory");
233}
234// Force the compiler to flush pending writes to global memory. Acts as an
235// effective read/write barrier
236inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() {
237 asm volatile("" : : : "memory");
238}
239#else
240template <class Tp>
241inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
242 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
243}
244// FIXME Add ClobberMemory() for non-gnu compilers
245#endif
246
247// TimeUnit is passed to a benchmark in order to specify the order of magnitude
248// for the measured time.
249enum TimeUnit { kNanosecond, kMicrosecond, kMillisecond };
250
251// BigO is passed to a benchmark in order to specify the asymptotic
252// computational
253// complexity for the benchmark. In case oAuto is selected, complexity will be
254// calculated automatically to the best fit.
255enum BigO { oNone, o1, oN, oNSquared, oNCubed, oLogN, oNLogN, oAuto, oLambda };
256
257// BigOFunc is passed to a benchmark in order to specify the asymptotic
258// computational complexity for the benchmark.
259typedef double(BigOFunc)(int);
260
261namespace internal {
262class ThreadTimer;
263class ThreadManager;
264
265#if defined(BENCHMARK_HAS_CXX11)
266enum ReportMode : unsigned {
267#else
268enum ReportMode {
269#endif
270 RM_Unspecified, // The mode has not been manually specified
271 RM_Default, // The mode is user-specified as default.
272 RM_ReportAggregatesOnly
273};
274}
275
276// State is passed to a running Benchmark and contains state for the
277// benchmark to use.
278class State {
279 public:
280 // Returns true if the benchmark should continue through another iteration.
281 // NOTE: A benchmark may not return from the test until KeepRunning() has
282 // returned false.
283 bool KeepRunning() {
284 if (BENCHMARK_BUILTIN_EXPECT(!started_, false)) {
285 StartKeepRunning();
286 }
287 bool const res = total_iterations_++ < max_iterations;
288 if (BENCHMARK_BUILTIN_EXPECT(!res, false)) {
289 FinishKeepRunning();
290 }
291 return res;
292 }
293
294 // REQUIRES: timer is running and 'SkipWithError(...)' has not been called
295 // by the current thread.
296 // Stop the benchmark timer. If not called, the timer will be
297 // automatically stopped after KeepRunning() returns false for the first time.
298 //
299 // For threaded benchmarks the PauseTiming() function only pauses the timing
300 // for the current thread.
301 //
302 // NOTE: The "real time" measurement is per-thread. If different threads
303 // report different measurements the largest one is reported.
304 //
305 // NOTE: PauseTiming()/ResumeTiming() are relatively
306 // heavyweight, and so their use should generally be avoided
307 // within each benchmark iteration, if possible.
308 void PauseTiming();
309
310 // REQUIRES: timer is not running and 'SkipWithError(...)' has not been called
311 // by the current thread.
312 // Start the benchmark timer. The timer is NOT running on entrance to the
313 // benchmark function. It begins running after the first call to KeepRunning()
314 //
315 // NOTE: PauseTiming()/ResumeTiming() are relatively
316 // heavyweight, and so their use should generally be avoided
317 // within each benchmark iteration, if possible.
318 void ResumeTiming();
319
320 // REQUIRES: 'SkipWithError(...)' has not been called previously by the
321 // current thread.
322 // Skip any future iterations of the 'KeepRunning()' loop in the current
323 // thread and report an error with the specified 'msg'. After this call
324 // the user may explicitly 'return' from the benchmark.
325 //
326 // For threaded benchmarks only the current thread stops executing and future
327 // calls to `KeepRunning()` will block until all threads have completed
328 // the `KeepRunning()` loop. If multiple threads report an error only the
329 // first error message is used.
330 //
331 // NOTE: Calling 'SkipWithError(...)' does not cause the benchmark to exit
332 // the current scope immediately. If the function is called from within
333 // the 'KeepRunning()' loop the current iteration will finish. It is the users
334 // responsibility to exit the scope as needed.
335 void SkipWithError(const char* msg);
336
337 // REQUIRES: called exactly once per iteration of the KeepRunning loop.
338 // Set the manually measured time for this benchmark iteration, which
339 // is used instead of automatically measured time if UseManualTime() was
340 // specified.
341 //
342 // For threaded benchmarks the final value will be set to the largest
343 // reported values.
344 void SetIterationTime(double seconds);
345
346 // Set the number of bytes processed by the current benchmark
347 // execution. This routine is typically called once at the end of a
348 // throughput oriented benchmark. If this routine is called with a
349 // value > 0, the report is printed in MB/sec instead of nanoseconds
350 // per iteration.
351 //
352 // REQUIRES: a benchmark has exited its KeepRunning loop.
353 BENCHMARK_ALWAYS_INLINE
354 void SetBytesProcessed(size_t bytes) { bytes_processed_ = bytes; }
355
356 BENCHMARK_ALWAYS_INLINE
357 size_t bytes_processed() const { return bytes_processed_; }
358
359 // If this routine is called with complexity_n > 0 and complexity report is
360 // requested for the
361 // family benchmark, then current benchmark will be part of the computation
362 // and complexity_n will
363 // represent the length of N.
364 BENCHMARK_ALWAYS_INLINE
365 void SetComplexityN(int complexity_n) { complexity_n_ = complexity_n; }
366
367 BENCHMARK_ALWAYS_INLINE
368 int complexity_length_n() { return complexity_n_; }
369
370 // If this routine is called with items > 0, then an items/s
371 // label is printed on the benchmark report line for the currently
372 // executing benchmark. It is typically called at the end of a processing
373 // benchmark where a processing items/second output is desired.
374 //
375 // REQUIRES: a benchmark has exited its KeepRunning loop.
376 BENCHMARK_ALWAYS_INLINE
377 void SetItemsProcessed(size_t items) { items_processed_ = items; }
378
379 BENCHMARK_ALWAYS_INLINE
380 size_t items_processed() const { return items_processed_; }
381
382 // If this routine is called, the specified label is printed at the
383 // end of the benchmark report line for the currently executing
384 // benchmark. Example:
385 // static void BM_Compress(benchmark::State& state) {
386 // ...
387 // double compress = input_size / output_size;
388 // state.SetLabel(StringPrintf("compress:%.1f%%", 100.0*compression));
389 // }
390 // Produces output that looks like:
391 // BM_Compress 50 50 14115038 compress:27.3%
392 //
393 // REQUIRES: a benchmark has exited its KeepRunning loop.
394 void SetLabel(const char* label);
395
396 // Allow the use of std::string without actually including <string>.
397 // This function does not participate in overload resolution unless StringType
398 // has the nested typename `basic_string`. This typename should be provided
399 // as an injected class name in the case of std::string.
400 template <class StringType>
401 void SetLabel(StringType const& str,
402 typename internal::EnableIfString<StringType>::type = 1) {
403 this->SetLabel(str.c_str());
404 }
405
406 // Range arguments for this run. CHECKs if the argument has been set.
407 BENCHMARK_ALWAYS_INLINE
408 int range(std::size_t pos = 0) const {
409 assert(range_.size() > pos);
410 return range_[pos];
411 }
412
413 BENCHMARK_DEPRECATED_MSG("use 'range(0)' instead")
414 int range_x() const { return range(0); }
415
416 BENCHMARK_DEPRECATED_MSG("use 'range(1)' instead")
417 int range_y() const { return range(1); }
418
419 BENCHMARK_ALWAYS_INLINE
420 size_t iterations() const { return total_iterations_; }
421
422 private:
423 bool started_;
424 bool finished_;
425 size_t total_iterations_;
426
427 std::vector<int> range_;
428
429 size_t bytes_processed_;
430 size_t items_processed_;
431
432 int complexity_n_;
433
434 bool error_occurred_;
435
436 public:
437 // Index of the executing thread. Values from [0, threads).
438 const int thread_index;
439 // Number of threads concurrently executing the benchmark.
440 const int threads;
441 const size_t max_iterations;
442
443 // TODO make me private
444 State(size_t max_iters, const std::vector<int>& ranges, int thread_i,
445 int n_threads, internal::ThreadTimer* timer,
446 internal::ThreadManager* manager);
447
448 private:
449 void StartKeepRunning();
450 void FinishKeepRunning();
451 internal::ThreadTimer* timer_;
452 internal::ThreadManager* manager_;
453 BENCHMARK_DISALLOW_COPY_AND_ASSIGN(State);
454};
455
456namespace internal {
457
458typedef void(Function)(State&);
459
460// ------------------------------------------------------
461// Benchmark registration object. The BENCHMARK() macro expands
462// into an internal::Benchmark* object. Various methods can
463// be called on this object to change the properties of the benchmark.
464// Each method returns "this" so that multiple method calls can
465// chained into one expression.
466class Benchmark {
467 public:
468 virtual ~Benchmark();
469
470 // Note: the following methods all return "this" so that multiple
471 // method calls can be chained together in one expression.
472
473 // Run this benchmark once with "x" as the extra argument passed
474 // to the function.
475 // REQUIRES: The function passed to the constructor must accept an arg1.
476 Benchmark* Arg(int x);
477
478 // Run this benchmark with the given time unit for the generated output report
479 Benchmark* Unit(TimeUnit unit);
480
481 // Run this benchmark once for a number of values picked from the
482 // range [start..limit]. (start and limit are always picked.)
483 // REQUIRES: The function passed to the constructor must accept an arg1.
484 Benchmark* Range(int start, int limit);
485
486 // Run this benchmark once for all values in the range [start..limit] with
487 // specific step
488 // REQUIRES: The function passed to the constructor must accept an arg1.
489 Benchmark* DenseRange(int start, int limit, int step = 1);
490
491 // Run this benchmark once with "args" as the extra arguments passed
492 // to the function.
493 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
494 Benchmark* Args(const std::vector<int>& args);
495
496 // Equivalent to Args({x, y})
497 // NOTE: This is a legacy C++03 interface provided for compatibility only.
498 // New code should use 'Args'.
499 Benchmark* ArgPair(int x, int y) {
500 std::vector<int> args;
501 args.push_back(x);
502 args.push_back(y);
503 return Args(args);
504 }
505
506 // Run this benchmark once for a number of values picked from the
507 // ranges [start..limit]. (starts and limits are always picked.)
508 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
509 Benchmark* Ranges(const std::vector<std::pair<int, int> >& ranges);
510
511 // Equivalent to ArgNames({name})
512 Benchmark* ArgName(const std::string& name);
513
514 // Set the argument names to display in the benchmark name. If not called,
515 // only argument values will be shown.
516 Benchmark* ArgNames(const std::vector<std::string>& names);
517
518 // Equivalent to Ranges({{lo1, hi1}, {lo2, hi2}}).
519 // NOTE: This is a legacy C++03 interface provided for compatibility only.
520 // New code should use 'Ranges'.
521 Benchmark* RangePair(int lo1, int hi1, int lo2, int hi2) {
522 std::vector<std::pair<int, int> > ranges;
523 ranges.push_back(std::make_pair(lo1, hi1));
524 ranges.push_back(std::make_pair(lo2, hi2));
525 return Ranges(ranges);
526 }
527
528 // Pass this benchmark object to *func, which can customize
529 // the benchmark by calling various methods like Arg, Args,
530 // Threads, etc.
531 Benchmark* Apply(void (*func)(Benchmark* benchmark));
532
533 // Set the range multiplier for non-dense range. If not called, the range
534 // multiplier kRangeMultiplier will be used.
535 Benchmark* RangeMultiplier(int multiplier);
536
537 // Set the minimum amount of time to use when running this benchmark. This
538 // option overrides the `benchmark_min_time` flag.
539 // REQUIRES: `t > 0`
540 Benchmark* MinTime(double t);
541
542 // Specify the amount of times to repeat this benchmark. This option overrides
543 // the `benchmark_repetitions` flag.
544 // REQUIRES: `n > 0`
545 Benchmark* Repetitions(int n);
546
547 // Specify if each repetition of the benchmark should be reported separately
548 // or if only the final statistics should be reported. If the benchmark
549 // is not repeated then the single result is always reported.
550 Benchmark* ReportAggregatesOnly(bool v = true);
551
552 // If a particular benchmark is I/O bound, runs multiple threads internally or
553 // if for some reason CPU timings are not representative, call this method. If
554 // called, the elapsed time will be used to control how many iterations are
555 // run, and in the printing of items/second or MB/seconds values. If not
556 // called, the cpu time used by the benchmark will be used.
557 Benchmark* UseRealTime();
558
559 // If a benchmark must measure time manually (e.g. if GPU execution time is
560 // being
561 // measured), call this method. If called, each benchmark iteration should
562 // call
563 // SetIterationTime(seconds) to report the measured time, which will be used
564 // to control how many iterations are run, and in the printing of items/second
565 // or MB/second values.
566 Benchmark* UseManualTime();
567
568 // Set the asymptotic computational complexity for the benchmark. If called
569 // the asymptotic computational complexity will be shown on the output.
570 Benchmark* Complexity(BigO complexity = benchmark::oAuto);
571
572 // Set the asymptotic computational complexity for the benchmark. If called
573 // the asymptotic computational complexity will be shown on the output.
574 Benchmark* Complexity(BigOFunc* complexity);
575
576 // Support for running multiple copies of the same benchmark concurrently
577 // in multiple threads. This may be useful when measuring the scaling
578 // of some piece of code.
579
580 // Run one instance of this benchmark concurrently in t threads.
581 Benchmark* Threads(int t);
582
583 // Pick a set of values T from [min_threads,max_threads].
584 // min_threads and max_threads are always included in T. Run this
585 // benchmark once for each value in T. The benchmark run for a
586 // particular value t consists of t threads running the benchmark
587 // function concurrently. For example, consider:
588 // BENCHMARK(Foo)->ThreadRange(1,16);
589 // This will run the following benchmarks:
590 // Foo in 1 thread
591 // Foo in 2 threads
592 // Foo in 4 threads
593 // Foo in 8 threads
594 // Foo in 16 threads
595 Benchmark* ThreadRange(int min_threads, int max_threads);
596
597 // For each value n in the range, run this benchmark once using n threads.
598 // min_threads and max_threads are always included in the range.
599 // stride specifies the increment. E.g. DenseThreadRange(1, 8, 3) starts
600 // a benchmark with 1, 4, 7 and 8 threads.
601 Benchmark* DenseThreadRange(int min_threads, int max_threads, int stride = 1);
602
603 // Equivalent to ThreadRange(NumCPUs(), NumCPUs())
604 Benchmark* ThreadPerCpu();
605
606 virtual void Run(State& state) = 0;
607
608 // Used inside the benchmark implementation
609 struct Instance;
610
611 protected:
612 explicit Benchmark(const char* name);
613 Benchmark(Benchmark const&);
614 void SetName(const char* name);
615
616 int ArgsCnt() const;
617
618 static void AddRange(std::vector<int>* dst, int lo, int hi, int mult);
619
620 private:
621 friend class BenchmarkFamilies;
622
623 std::string name_;
624 ReportMode report_mode_;
625 std::vector<std::string> arg_names_; // Args for all benchmark runs
626 std::vector<std::vector<int> > args_; // Args for all benchmark runs
627 TimeUnit time_unit_;
628 int range_multiplier_;
629 double min_time_;
630 int repetitions_;
631 bool use_real_time_;
632 bool use_manual_time_;
633 BigO complexity_;
634 BigOFunc* complexity_lambda_;
635 std::vector<int> thread_counts_;
636
637 Benchmark& operator=(Benchmark const&);
638};
639
640} // namespace internal
641
642// Create and register a benchmark with the specified 'name' that invokes
643// the specified functor 'fn'.
644//
645// RETURNS: A pointer to the registered benchmark.
646internal::Benchmark* RegisterBenchmark(const char* name,
647 internal::Function* fn);
648
649#if defined(BENCHMARK_HAS_CXX11)
650template <class Lambda>
651internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn);
652#endif
653
654namespace internal {
655// The class used to hold all Benchmarks created from static function.
656// (ie those created using the BENCHMARK(...) macros.
657class FunctionBenchmark : public Benchmark {
658 public:
659 FunctionBenchmark(const char* name, Function* func)
660 : Benchmark(name), func_(func) {}
661
662 virtual void Run(State& st);
663
664 private:
665 Function* func_;
666};
667
668#ifdef BENCHMARK_HAS_CXX11
669template <class Lambda>
670class LambdaBenchmark : public Benchmark {
671 public:
672 virtual void Run(State& st) { lambda_(st); }
673
674 private:
675 template <class OLambda>
676 LambdaBenchmark(const char* name, OLambda&& lam)
677 : Benchmark(name), lambda_(std::forward<OLambda>(lam)) {}
678
679 LambdaBenchmark(LambdaBenchmark const&) = delete;
680
681 private:
682 template <class Lam>
683 friend Benchmark* ::benchmark::RegisterBenchmark(const char*, Lam&&);
684
685 Lambda lambda_;
686};
687#endif
688
689} // end namespace internal
690
691inline internal::Benchmark* RegisterBenchmark(const char* name,
692 internal::Function* fn) {
693 return internal::RegisterBenchmarkInternal(
694 ::new internal::FunctionBenchmark(name, fn));
695}
696
697#ifdef BENCHMARK_HAS_CXX11
698template <class Lambda>
699internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn) {
700 using BenchType =
701 internal::LambdaBenchmark<typename std::decay<Lambda>::type>;
702 return internal::RegisterBenchmarkInternal(
703 ::new BenchType(name, std::forward<Lambda>(fn)));
704}
705#endif
706
707#if defined(BENCHMARK_HAS_CXX11) && \
708 (!defined(BENCHMARK_GCC_VERSION) || BENCHMARK_GCC_VERSION >= 409)
709template <class Lambda, class... Args>
710internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn,
711 Args&&... args) {
712 return benchmark::RegisterBenchmark(
713 name, [=](benchmark::State& st) { fn(st, args...); });
714}
715#else
716#define BENCHMARK_HAS_NO_VARIADIC_REGISTER_BENCHMARK
717#endif
718
719// The base class for all fixture tests.
720class Fixture : public internal::Benchmark {
721 public:
722 Fixture() : internal::Benchmark("") {}
723
724 virtual void Run(State& st) {
725 this->SetUp(st);
726 this->BenchmarkCase(st);
727 this->TearDown(st);
728 }
729
730 // These will be deprecated ...
731 virtual void SetUp(const State&) {}
732 virtual void TearDown(const State&) {}
733 // ... In favor of these.
734 virtual void SetUp(State& st) { SetUp(const_cast<const State&>(st)); }
735 virtual void TearDown(State& st) { TearDown(const_cast<const State&>(st)); }
736
737 protected:
738 virtual void BenchmarkCase(State&) = 0;
739};
740
741} // end namespace benchmark
742
743// ------------------------------------------------------
744// Macro to register benchmarks
745
746// Check that __COUNTER__ is defined and that __COUNTER__ increases by 1
747// every time it is expanded. X + 1 == X + 0 is used in case X is defined to be
748// empty. If X is empty the expression becomes (+1 == +0).
749#if defined(__COUNTER__) && (__COUNTER__ + 1 == __COUNTER__ + 0)
750#define BENCHMARK_PRIVATE_UNIQUE_ID __COUNTER__
751#else
752#define BENCHMARK_PRIVATE_UNIQUE_ID __LINE__
753#endif
754
755// Helpers for generating unique variable names
756#define BENCHMARK_PRIVATE_NAME(n) \
757 BENCHMARK_PRIVATE_CONCAT(_benchmark_, BENCHMARK_PRIVATE_UNIQUE_ID, n)
758#define BENCHMARK_PRIVATE_CONCAT(a, b, c) BENCHMARK_PRIVATE_CONCAT2(a, b, c)
759#define BENCHMARK_PRIVATE_CONCAT2(a, b, c) a##b##c
760
761#define BENCHMARK_PRIVATE_DECLARE(n) \
762 static ::benchmark::internal::Benchmark* BENCHMARK_PRIVATE_NAME(n) \
763 BENCHMARK_UNUSED
764
765#define BENCHMARK(n) \
766 BENCHMARK_PRIVATE_DECLARE(n) = \
767 (::benchmark::internal::RegisterBenchmarkInternal( \
768 new ::benchmark::internal::FunctionBenchmark(#n, n)))
769
770// Old-style macros
771#define BENCHMARK_WITH_ARG(n, a) BENCHMARK(n)->Arg((a))
772#define BENCHMARK_WITH_ARG2(n, a1, a2) BENCHMARK(n)->Args({(a1), (a2)})
773#define BENCHMARK_WITH_UNIT(n, t) BENCHMARK(n)->Unit((t))
774#define BENCHMARK_RANGE(n, lo, hi) BENCHMARK(n)->Range((lo), (hi))
775#define BENCHMARK_RANGE2(n, l1, h1, l2, h2) \
776 BENCHMARK(n)->RangePair({{(l1), (h1)}, {(l2), (h2)}})
777
778#if __cplusplus >= 201103L
779
780// Register a benchmark which invokes the function specified by `func`
781// with the additional arguments specified by `...`.
782//
783// For example:
784//
785// template <class ...ExtraArgs>`
786// void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
787// [...]
788//}
789// /* Registers a benchmark named "BM_takes_args/int_string_test` */
790// BENCHMARK_CAPTURE(BM_takes_args, int_string_test, 42, std::string("abc"));
791#define BENCHMARK_CAPTURE(func, test_case_name, ...) \
792 BENCHMARK_PRIVATE_DECLARE(func) = \
793 (::benchmark::internal::RegisterBenchmarkInternal( \
794 new ::benchmark::internal::FunctionBenchmark( \
795 #func "/" #test_case_name, \
796 [](::benchmark::State& st) { func(st, __VA_ARGS__); })))
797
798#endif // __cplusplus >= 11
799
800// This will register a benchmark for a templatized function. For example:
801//
802// template<int arg>
803// void BM_Foo(int iters);
804//
805// BENCHMARK_TEMPLATE(BM_Foo, 1);
806//
807// will register BM_Foo<1> as a benchmark.
808#define BENCHMARK_TEMPLATE1(n, a) \
809 BENCHMARK_PRIVATE_DECLARE(n) = \
810 (::benchmark::internal::RegisterBenchmarkInternal( \
811 new ::benchmark::internal::FunctionBenchmark(#n "<" #a ">", n<a>)))
812
813#define BENCHMARK_TEMPLATE2(n, a, b) \
814 BENCHMARK_PRIVATE_DECLARE(n) = \
815 (::benchmark::internal::RegisterBenchmarkInternal( \
816 new ::benchmark::internal::FunctionBenchmark(#n "<" #a "," #b ">", \
817 n<a, b>)))
818
819#if __cplusplus >= 201103L
820#define BENCHMARK_TEMPLATE(n, ...) \
821 BENCHMARK_PRIVATE_DECLARE(n) = \
822 (::benchmark::internal::RegisterBenchmarkInternal( \
823 new ::benchmark::internal::FunctionBenchmark( \
824 #n "<" #__VA_ARGS__ ">", n<__VA_ARGS__>)))
825#else
826#define BENCHMARK_TEMPLATE(n, a) BENCHMARK_TEMPLATE1(n, a)
827#endif
828
829#define BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
830 class BaseClass##_##Method##_Benchmark : public BaseClass { \
831 public: \
832 BaseClass##_##Method##_Benchmark() : BaseClass() { \
833 this->SetName(#BaseClass "/" #Method); \
834 } \
835 \
836 protected: \
837 virtual void BenchmarkCase(::benchmark::State&); \
838 };
839
840#define BENCHMARK_DEFINE_F(BaseClass, Method) \
841 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
842 void BaseClass##_##Method##_Benchmark::BenchmarkCase
843
844#define BENCHMARK_REGISTER_F(BaseClass, Method) \
845 BENCHMARK_PRIVATE_REGISTER_F(BaseClass##_##Method##_Benchmark)
846
847#define BENCHMARK_PRIVATE_REGISTER_F(TestName) \
848 BENCHMARK_PRIVATE_DECLARE(TestName) = \
849 (::benchmark::internal::RegisterBenchmarkInternal(new TestName()))
850
851// This macro will define and register a benchmark within a fixture class.
852#define BENCHMARK_F(BaseClass, Method) \
853 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
854 BENCHMARK_REGISTER_F(BaseClass, Method); \
855 void BaseClass##_##Method##_Benchmark::BenchmarkCase
856
857// Helper macro to create a main routine in a test that runs the benchmarks
858#define BENCHMARK_MAIN() \
859 int main(int argc, char** argv) { \
860 ::benchmark::Initialize(&argc, argv); \
861 ::benchmark::RunSpecifiedBenchmarks(); \
862 }
863
864#endif // BENCHMARK_BENCHMARK_API_H_
865