1// Copyright 2015 Google Inc. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15// Support for registering benchmarks for functions.
16
17/* Example usage:
18// Define a function that executes the code to be measured a
19// specified number of times:
20static void BM_StringCreation(benchmark::State& state) {
21 for (auto _ : state)
22 std::string empty_string;
23}
24
25// Register the function as a benchmark
26BENCHMARK(BM_StringCreation);
27
28// Define another benchmark
29static void BM_StringCopy(benchmark::State& state) {
30 std::string x = "hello";
31 for (auto _ : state)
32 std::string copy(x);
33}
34BENCHMARK(BM_StringCopy);
35
36// Augment the main() program to invoke benchmarks if specified
37// via the --benchmarks command line flag. E.g.,
38// my_unittest --benchmark_filter=all
39// my_unittest --benchmark_filter=BM_StringCreation
40// my_unittest --benchmark_filter=String
41// my_unittest --benchmark_filter='Copy|Creation'
42int main(int argc, char** argv) {
43 benchmark::Initialize(&argc, argv);
44 benchmark::RunSpecifiedBenchmarks();
45 return 0;
46}
47
48// Sometimes a family of microbenchmarks can be implemented with
49// just one routine that takes an extra argument to specify which
50// one of the family of benchmarks to run. For example, the following
51// code defines a family of microbenchmarks for measuring the speed
52// of memcpy() calls of different lengths:
53
54static void BM_memcpy(benchmark::State& state) {
55 char* src = new char[state.range(0)]; char* dst = new char[state.range(0)];
56 memset(src, 'x', state.range(0));
57 for (auto _ : state)
58 memcpy(dst, src, state.range(0));
59 state.SetBytesProcessed(state.iterations() * state.range(0));
60 delete[] src; delete[] dst;
61}
62BENCHMARK(BM_memcpy)->Arg(8)->Arg(64)->Arg(512)->Arg(1<<10)->Arg(8<<10);
63
64// The preceding code is quite repetitive, and can be replaced with the
65// following short-hand. The following invocation will pick a few
66// appropriate arguments in the specified range and will generate a
67// microbenchmark for each such argument.
68BENCHMARK(BM_memcpy)->Range(8, 8<<10);
69
70// You might have a microbenchmark that depends on two inputs. For
71// example, the following code defines a family of microbenchmarks for
72// measuring the speed of set insertion.
73static void BM_SetInsert(benchmark::State& state) {
74 set<int> data;
75 for (auto _ : state) {
76 state.PauseTiming();
77 data = ConstructRandomSet(state.range(0));
78 state.ResumeTiming();
79 for (int j = 0; j < state.range(1); ++j)
80 data.insert(RandomNumber());
81 }
82}
83BENCHMARK(BM_SetInsert)
84 ->Args({1<<10, 128})
85 ->Args({2<<10, 128})
86 ->Args({4<<10, 128})
87 ->Args({8<<10, 128})
88 ->Args({1<<10, 512})
89 ->Args({2<<10, 512})
90 ->Args({4<<10, 512})
91 ->Args({8<<10, 512});
92
93// The preceding code is quite repetitive, and can be replaced with
94// the following short-hand. The following macro will pick a few
95// appropriate arguments in the product of the two specified ranges
96// and will generate a microbenchmark for each such pair.
97BENCHMARK(BM_SetInsert)->Ranges({{1<<10, 8<<10}, {128, 512}});
98
99// For more complex patterns of inputs, passing a custom function
100// to Apply allows programmatic specification of an
101// arbitrary set of arguments to run the microbenchmark on.
102// The following example enumerates a dense range on
103// one parameter, and a sparse range on the second.
104static void CustomArguments(benchmark::internal::Benchmark* b) {
105 for (int i = 0; i <= 10; ++i)
106 for (int j = 32; j <= 1024*1024; j *= 8)
107 b->Args({i, j});
108}
109BENCHMARK(BM_SetInsert)->Apply(CustomArguments);
110
111// Templated microbenchmarks work the same way:
112// Produce then consume 'size' messages 'iters' times
113// Measures throughput in the absence of multiprogramming.
114template <class Q> int BM_Sequential(benchmark::State& state) {
115 Q q;
116 typename Q::value_type v;
117 for (auto _ : state) {
118 for (int i = state.range(0); i--; )
119 q.push(v);
120 for (int e = state.range(0); e--; )
121 q.Wait(&v);
122 }
123 // actually messages, not bytes:
124 state.SetBytesProcessed(state.iterations() * state.range(0));
125}
126BENCHMARK_TEMPLATE(BM_Sequential, WaitQueue<int>)->Range(1<<0, 1<<10);
127
128Use `Benchmark::MinTime(double t)` to set the minimum time used to run the
129benchmark. This option overrides the `benchmark_min_time` flag.
130
131void BM_test(benchmark::State& state) {
132 ... body ...
133}
134BENCHMARK(BM_test)->MinTime(2.0); // Run for at least 2 seconds.
135
136In a multithreaded test, it is guaranteed that none of the threads will start
137until all have reached the loop start, and all will have finished before any
138thread exits the loop body. As such, any global setup or teardown you want to
139do can be wrapped in a check against the thread index:
140
141static void BM_MultiThreaded(benchmark::State& state) {
142 if (state.thread_index == 0) {
143 // Setup code here.
144 }
145 for (auto _ : state) {
146 // Run the test as normal.
147 }
148 if (state.thread_index == 0) {
149 // Teardown code here.
150 }
151}
152BENCHMARK(BM_MultiThreaded)->Threads(4);
153
154
155If a benchmark runs a few milliseconds it may be hard to visually compare the
156measured times, since the output data is given in nanoseconds per default. In
157order to manually set the time unit, you can specify it manually:
158
159BENCHMARK(BM_test)->Unit(benchmark::kMillisecond);
160*/
161
162#ifndef BENCHMARK_BENCHMARK_H_
163#define BENCHMARK_BENCHMARK_H_
164
165// The _MSVC_LANG check should detect Visual Studio 2015 Update 3 and newer.
166#if __cplusplus >= 201103L || (defined(_MSVC_LANG) && _MSVC_LANG >= 201103L)
167#define BENCHMARK_HAS_CXX11
168#endif
169
170#include <stdint.h>
171
172#include <algorithm>
173#include <cassert>
174#include <cstddef>
175#include <iosfwd>
176#include <map>
177#include <set>
178#include <string>
179#include <utility>
180#include <vector>
181
182#if defined(BENCHMARK_HAS_CXX11)
183#include <initializer_list>
184#include <type_traits>
185#include <utility>
186#endif
187
188#if defined(_MSC_VER)
189#include <intrin.h> // for _ReadWriteBarrier
190#endif
191
192#ifndef BENCHMARK_HAS_CXX11
193#define BENCHMARK_DISALLOW_COPY_AND_ASSIGN(TypeName) \
194 TypeName(const TypeName&); \
195 TypeName& operator=(const TypeName&)
196#else
197#define BENCHMARK_DISALLOW_COPY_AND_ASSIGN(TypeName) \
198 TypeName(const TypeName&) = delete; \
199 TypeName& operator=(const TypeName&) = delete
200#endif
201
202#if defined(__GNUC__)
203#define BENCHMARK_UNUSED __attribute__((unused))
204#define BENCHMARK_ALWAYS_INLINE __attribute__((always_inline))
205#define BENCHMARK_NOEXCEPT noexcept
206#define BENCHMARK_NOEXCEPT_OP(x) noexcept(x)
207#elif defined(_MSC_VER) && !defined(__clang__)
208#define BENCHMARK_UNUSED
209#define BENCHMARK_ALWAYS_INLINE __forceinline
210#if _MSC_VER >= 1900
211#define BENCHMARK_NOEXCEPT noexcept
212#define BENCHMARK_NOEXCEPT_OP(x) noexcept(x)
213#else
214#define BENCHMARK_NOEXCEPT
215#define BENCHMARK_NOEXCEPT_OP(x)
216#endif
217#define __func__ __FUNCTION__
218#else
219#define BENCHMARK_UNUSED
220#define BENCHMARK_ALWAYS_INLINE
221#define BENCHMARK_NOEXCEPT
222#define BENCHMARK_NOEXCEPT_OP(x)
223#endif
224
225#define BENCHMARK_INTERNAL_TOSTRING2(x) #x
226#define BENCHMARK_INTERNAL_TOSTRING(x) BENCHMARK_INTERNAL_TOSTRING2(x)
227
228#if defined(__GNUC__) || defined(__clang__)
229#define BENCHMARK_BUILTIN_EXPECT(x, y) __builtin_expect(x, y)
230#define BENCHMARK_DEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
231#else
232#define BENCHMARK_BUILTIN_EXPECT(x, y) x
233#define BENCHMARK_DEPRECATED_MSG(msg)
234#define BENCHMARK_WARNING_MSG(msg) \
235 __pragma(message(__FILE__ "(" BENCHMARK_INTERNAL_TOSTRING( \
236 __LINE__) ") : warning note: " msg))
237#endif
238
239#if defined(__GNUC__) && !defined(__clang__)
240#define BENCHMARK_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__)
241#endif
242
243#ifndef __has_builtin
244#define __has_builtin(x) 0
245#endif
246
247#if defined(__GNUC__) || __has_builtin(__builtin_unreachable)
248#define BENCHMARK_UNREACHABLE() __builtin_unreachable()
249#elif defined(_MSC_VER)
250#define BENCHMARK_UNREACHABLE() __assume(false)
251#else
252#define BENCHMARK_UNREACHABLE() ((void)0)
253#endif
254
255namespace benchmark {
256class BenchmarkReporter;
257class MemoryManager;
258
259void Initialize(int* argc, char** argv);
260
261// Report to stdout all arguments in 'argv' as unrecognized except the first.
262// Returns true there is at least on unrecognized argument (i.e. 'argc' > 1).
263bool ReportUnrecognizedArguments(int argc, char** argv);
264
265// Generate a list of benchmarks matching the specified --benchmark_filter flag
266// and if --benchmark_list_tests is specified return after printing the name
267// of each matching benchmark. Otherwise run each matching benchmark and
268// report the results.
269//
270// The second and third overload use the specified 'display_reporter' and
271// 'file_reporter' respectively. 'file_reporter' will write to the file
272// specified
273// by '--benchmark_output'. If '--benchmark_output' is not given the
274// 'file_reporter' is ignored.
275//
276// RETURNS: The number of matching benchmarks.
277size_t RunSpecifiedBenchmarks();
278size_t RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter);
279size_t RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter,
280 BenchmarkReporter* file_reporter);
281
282// Register a MemoryManager instance that will be used to collect and report
283// allocation measurements for benchmark runs.
284void RegisterMemoryManager(MemoryManager* memory_manager);
285
286namespace internal {
287class Benchmark;
288class BenchmarkImp;
289class BenchmarkFamilies;
290
291void UseCharPointer(char const volatile*);
292
293// Take ownership of the pointer and register the benchmark. Return the
294// registered benchmark.
295Benchmark* RegisterBenchmarkInternal(Benchmark*);
296
297// Ensure that the standard streams are properly initialized in every TU.
298int InitializeStreams();
299BENCHMARK_UNUSED static int stream_init_anchor = InitializeStreams();
300
301} // namespace internal
302
303#if (!defined(__GNUC__) && !defined(__clang__)) || defined(__pnacl__) || \
304 defined(__EMSCRIPTEN__)
305#define BENCHMARK_HAS_NO_INLINE_ASSEMBLY
306#endif
307
308// The DoNotOptimize(...) function can be used to prevent a value or
309// expression from being optimized away by the compiler. This function is
310// intended to add little to no overhead.
311// See: https://youtu.be/nXaxk27zwlk?t=2441
312#ifndef BENCHMARK_HAS_NO_INLINE_ASSEMBLY
313template <class Tp>
314inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
315 asm volatile("" : : "r,m"(value) : "memory");
316}
317
318template <class Tp>
319inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp& value) {
320#if defined(__clang__)
321 asm volatile("" : "+r,m"(value) : : "memory");
322#else
323 asm volatile("" : "+m,r"(value) : : "memory");
324#endif
325}
326
327// Force the compiler to flush pending writes to global memory. Acts as an
328// effective read/write barrier
329inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() {
330 asm volatile("" : : : "memory");
331}
332#elif defined(_MSC_VER)
333template <class Tp>
334inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
335 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
336 _ReadWriteBarrier();
337}
338
339inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() { _ReadWriteBarrier(); }
340#else
341template <class Tp>
342inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
343 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
344}
345// FIXME Add ClobberMemory() for non-gnu and non-msvc compilers
346#endif
347
348// This class is used for user-defined counters.
349class Counter {
350 public:
351 enum Flags {
352 kDefaults = 0,
353 // Mark the counter as a rate. It will be presented divided
354 // by the duration of the benchmark.
355 kIsRate = 1U << 0U,
356 // Mark the counter as a thread-average quantity. It will be
357 // presented divided by the number of threads.
358 kAvgThreads = 1U << 1U,
359 // Mark the counter as a thread-average rate. See above.
360 kAvgThreadsRate = kIsRate | kAvgThreads,
361 // Mark the counter as a constant value, valid/same for *every* iteration.
362 // When reporting, it will be *multiplied* by the iteration count.
363 kIsIterationInvariant = 1U << 2U,
364 // Mark the counter as a constant rate.
365 // When reporting, it will be *multiplied* by the iteration count
366 // and then divided by the duration of the benchmark.
367 kIsIterationInvariantRate = kIsRate | kIsIterationInvariant,
368 // Mark the counter as a iteration-average quantity.
369 // It will be presented divided by the number of iterations.
370 kAvgIterations = 1U << 3U,
371 // Mark the counter as a iteration-average rate. See above.
372 kAvgIterationsRate = kIsRate | kAvgIterations,
373
374 // In the end, invert the result. This is always done last!
375 kInvert = 1U << 31U
376 };
377
378 enum OneK {
379 // 1'000 items per 1k
380 kIs1000 = 1000,
381 // 1'024 items per 1k
382 kIs1024 = 1024
383 };
384
385 double value;
386 Flags flags;
387 OneK oneK;
388
389 BENCHMARK_ALWAYS_INLINE
390 Counter(double v = 0., Flags f = kDefaults, OneK k = kIs1000)
391 : value(v), flags(f), oneK(k) {}
392
393 BENCHMARK_ALWAYS_INLINE operator double const&() const { return value; }
394 BENCHMARK_ALWAYS_INLINE operator double&() { return value; }
395};
396
397// A helper for user code to create unforeseen combinations of Flags, without
398// having to do this cast manually each time, or providing this operator.
399Counter::Flags inline operator|(const Counter::Flags& LHS,
400 const Counter::Flags& RHS) {
401 return static_cast<Counter::Flags>(static_cast<int>(LHS) |
402 static_cast<int>(RHS));
403}
404
405// This is the container for the user-defined counters.
406typedef std::map<std::string, Counter> UserCounters;
407
408// TimeUnit is passed to a benchmark in order to specify the order of magnitude
409// for the measured time.
410enum TimeUnit { kNanosecond, kMicrosecond, kMillisecond };
411
412// BigO is passed to a benchmark in order to specify the asymptotic
413// computational
414// complexity for the benchmark. In case oAuto is selected, complexity will be
415// calculated automatically to the best fit.
416enum BigO { oNone, o1, oN, oNSquared, oNCubed, oLogN, oNLogN, oAuto, oLambda };
417
418typedef uint64_t IterationCount;
419
420// BigOFunc is passed to a benchmark in order to specify the asymptotic
421// computational complexity for the benchmark.
422typedef double(BigOFunc)(IterationCount);
423
424// StatisticsFunc is passed to a benchmark in order to compute some descriptive
425// statistics over all the measurements of some type
426typedef double(StatisticsFunc)(const std::vector<double>&);
427
428namespace internal {
429struct Statistics {
430 std::string name_;
431 StatisticsFunc* compute_;
432
433 Statistics(const std::string& name, StatisticsFunc* compute)
434 : name_(name), compute_(compute) {}
435};
436
437struct BenchmarkInstance;
438class ThreadTimer;
439class ThreadManager;
440
441enum AggregationReportMode
442#if defined(BENCHMARK_HAS_CXX11)
443 : unsigned
444#else
445#endif
446{
447 // The mode has not been manually specified
448 ARM_Unspecified = 0,
449 // The mode is user-specified.
450 // This may or may not be set when the following bit-flags are set.
451 ARM_Default = 1U << 0U,
452 // File reporter should only output aggregates.
453 ARM_FileReportAggregatesOnly = 1U << 1U,
454 // Display reporter should only output aggregates
455 ARM_DisplayReportAggregatesOnly = 1U << 2U,
456 // Both reporters should only display aggregates.
457 ARM_ReportAggregatesOnly =
458 ARM_FileReportAggregatesOnly | ARM_DisplayReportAggregatesOnly
459};
460
461} // namespace internal
462
463// State is passed to a running Benchmark and contains state for the
464// benchmark to use.
465class State {
466 public:
467 struct StateIterator;
468 friend struct StateIterator;
469
470 // Returns iterators used to run each iteration of a benchmark using a
471 // C++11 ranged-based for loop. These functions should not be called directly.
472 //
473 // REQUIRES: The benchmark has not started running yet. Neither begin nor end
474 // have been called previously.
475 //
476 // NOTE: KeepRunning may not be used after calling either of these functions.
477 BENCHMARK_ALWAYS_INLINE StateIterator begin();
478 BENCHMARK_ALWAYS_INLINE StateIterator end();
479
480 // Returns true if the benchmark should continue through another iteration.
481 // NOTE: A benchmark may not return from the test until KeepRunning() has
482 // returned false.
483 bool KeepRunning();
484
485 // Returns true iff the benchmark should run n more iterations.
486 // REQUIRES: 'n' > 0.
487 // NOTE: A benchmark must not return from the test until KeepRunningBatch()
488 // has returned false.
489 // NOTE: KeepRunningBatch() may overshoot by up to 'n' iterations.
490 //
491 // Intended usage:
492 // while (state.KeepRunningBatch(1000)) {
493 // // process 1000 elements
494 // }
495 bool KeepRunningBatch(IterationCount n);
496
497 // REQUIRES: timer is running and 'SkipWithError(...)' has not been called
498 // by the current thread.
499 // Stop the benchmark timer. If not called, the timer will be
500 // automatically stopped after the last iteration of the benchmark loop.
501 //
502 // For threaded benchmarks the PauseTiming() function only pauses the timing
503 // for the current thread.
504 //
505 // NOTE: The "real time" measurement is per-thread. If different threads
506 // report different measurements the largest one is reported.
507 //
508 // NOTE: PauseTiming()/ResumeTiming() are relatively
509 // heavyweight, and so their use should generally be avoided
510 // within each benchmark iteration, if possible.
511 void PauseTiming();
512
513 // REQUIRES: timer is not running and 'SkipWithError(...)' has not been called
514 // by the current thread.
515 // Start the benchmark timer. The timer is NOT running on entrance to the
516 // benchmark function. It begins running after control flow enters the
517 // benchmark loop.
518 //
519 // NOTE: PauseTiming()/ResumeTiming() are relatively
520 // heavyweight, and so their use should generally be avoided
521 // within each benchmark iteration, if possible.
522 void ResumeTiming();
523
524 // REQUIRES: 'SkipWithError(...)' has not been called previously by the
525 // current thread.
526 // Report the benchmark as resulting in an error with the specified 'msg'.
527 // After this call the user may explicitly 'return' from the benchmark.
528 //
529 // If the ranged-for style of benchmark loop is used, the user must explicitly
530 // break from the loop, otherwise all future iterations will be run.
531 // If the 'KeepRunning()' loop is used the current thread will automatically
532 // exit the loop at the end of the current iteration.
533 //
534 // For threaded benchmarks only the current thread stops executing and future
535 // calls to `KeepRunning()` will block until all threads have completed
536 // the `KeepRunning()` loop. If multiple threads report an error only the
537 // first error message is used.
538 //
539 // NOTE: Calling 'SkipWithError(...)' does not cause the benchmark to exit
540 // the current scope immediately. If the function is called from within
541 // the 'KeepRunning()' loop the current iteration will finish. It is the users
542 // responsibility to exit the scope as needed.
543 void SkipWithError(const char* msg);
544
545 // Returns true if an error has been reported with 'SkipWithError(...)'.
546 bool error_occurred() const { return error_occurred_; }
547
548 // REQUIRES: called exactly once per iteration of the benchmarking loop.
549 // Set the manually measured time for this benchmark iteration, which
550 // is used instead of automatically measured time if UseManualTime() was
551 // specified.
552 //
553 // For threaded benchmarks the final value will be set to the largest
554 // reported values.
555 void SetIterationTime(double seconds);
556
557 // Set the number of bytes processed by the current benchmark
558 // execution. This routine is typically called once at the end of a
559 // throughput oriented benchmark.
560 //
561 // REQUIRES: a benchmark has exited its benchmarking loop.
562 BENCHMARK_ALWAYS_INLINE
563 void SetBytesProcessed(int64_t bytes) {
564 counters["bytes_per_second"] =
565 Counter(static_cast<double>(bytes), Counter::kIsRate, Counter::kIs1024);
566 }
567
568 BENCHMARK_ALWAYS_INLINE
569 int64_t bytes_processed() const {
570 if (counters.find("bytes_per_second") != counters.end())
571 return static_cast<int64_t>(counters.at("bytes_per_second"));
572 return 0;
573 }
574
575 // If this routine is called with complexity_n > 0 and complexity report is
576 // requested for the
577 // family benchmark, then current benchmark will be part of the computation
578 // and complexity_n will
579 // represent the length of N.
580 BENCHMARK_ALWAYS_INLINE
581 void SetComplexityN(int64_t complexity_n) { complexity_n_ = complexity_n; }
582
583 BENCHMARK_ALWAYS_INLINE
584 int64_t complexity_length_n() const { return complexity_n_; }
585
586 // If this routine is called with items > 0, then an items/s
587 // label is printed on the benchmark report line for the currently
588 // executing benchmark. It is typically called at the end of a processing
589 // benchmark where a processing items/second output is desired.
590 //
591 // REQUIRES: a benchmark has exited its benchmarking loop.
592 BENCHMARK_ALWAYS_INLINE
593 void SetItemsProcessed(int64_t items) {
594 counters["items_per_second"] =
595 Counter(static_cast<double>(items), benchmark::Counter::kIsRate);
596 }
597
598 BENCHMARK_ALWAYS_INLINE
599 int64_t items_processed() const {
600 if (counters.find("items_per_second") != counters.end())
601 return static_cast<int64_t>(counters.at("items_per_second"));
602 return 0;
603 }
604
605 // If this routine is called, the specified label is printed at the
606 // end of the benchmark report line for the currently executing
607 // benchmark. Example:
608 // static void BM_Compress(benchmark::State& state) {
609 // ...
610 // double compress = input_size / output_size;
611 // state.SetLabel(StrFormat("compress:%.1f%%", 100.0*compression));
612 // }
613 // Produces output that looks like:
614 // BM_Compress 50 50 14115038 compress:27.3%
615 //
616 // REQUIRES: a benchmark has exited its benchmarking loop.
617 void SetLabel(const char* label);
618
619 void BENCHMARK_ALWAYS_INLINE SetLabel(const std::string& str) {
620 this->SetLabel(str.c_str());
621 }
622
623 // Range arguments for this run. CHECKs if the argument has been set.
624 BENCHMARK_ALWAYS_INLINE
625 int64_t range(std::size_t pos = 0) const {
626 assert(range_.size() > pos);
627 return range_[pos];
628 }
629
630 BENCHMARK_DEPRECATED_MSG("use 'range(0)' instead")
631 int64_t range_x() const { return range(0); }
632
633 BENCHMARK_DEPRECATED_MSG("use 'range(1)' instead")
634 int64_t range_y() const { return range(1); }
635
636 BENCHMARK_ALWAYS_INLINE
637 IterationCount iterations() const {
638 if (BENCHMARK_BUILTIN_EXPECT(!started_, false)) {
639 return 0;
640 }
641 return max_iterations - total_iterations_ + batch_leftover_;
642 }
643
644 private
645 : // items we expect on the first cache line (ie 64 bytes of the struct)
646 // When total_iterations_ is 0, KeepRunning() and friends will return false.
647 // May be larger than max_iterations.
648 IterationCount total_iterations_;
649
650 // When using KeepRunningBatch(), batch_leftover_ holds the number of
651 // iterations beyond max_iters that were run. Used to track
652 // completed_iterations_ accurately.
653 IterationCount batch_leftover_;
654
655 public:
656 const IterationCount max_iterations;
657
658 private:
659 bool started_;
660 bool finished_;
661 bool error_occurred_;
662
663 private: // items we don't need on the first cache line
664 std::vector<int64_t> range_;
665
666 int64_t complexity_n_;
667
668 public:
669 // Container for user-defined counters.
670 UserCounters counters;
671 // Index of the executing thread. Values from [0, threads).
672 const int thread_index;
673 // Number of threads concurrently executing the benchmark.
674 const int threads;
675
676 private:
677 State(IterationCount max_iters, const std::vector<int64_t>& ranges,
678 int thread_i, int n_threads, internal::ThreadTimer* timer,
679 internal::ThreadManager* manager);
680
681 void StartKeepRunning();
682 // Implementation of KeepRunning() and KeepRunningBatch().
683 // is_batch must be true unless n is 1.
684 bool KeepRunningInternal(IterationCount n, bool is_batch);
685 void FinishKeepRunning();
686 internal::ThreadTimer* timer_;
687 internal::ThreadManager* manager_;
688
689 friend struct internal::BenchmarkInstance;
690};
691
692inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunning() {
693 return KeepRunningInternal(1, /*is_batch=*/false);
694}
695
696inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningBatch(IterationCount n) {
697 return KeepRunningInternal(n, /*is_batch=*/true);
698}
699
700inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningInternal(IterationCount n,
701 bool is_batch) {
702 // total_iterations_ is set to 0 by the constructor, and always set to a
703 // nonzero value by StartKepRunning().
704 assert(n > 0);
705 // n must be 1 unless is_batch is true.
706 assert(is_batch || n == 1);
707 if (BENCHMARK_BUILTIN_EXPECT(total_iterations_ >= n, true)) {
708 total_iterations_ -= n;
709 return true;
710 }
711 if (!started_) {
712 StartKeepRunning();
713 if (!error_occurred_ && total_iterations_ >= n) {
714 total_iterations_ -= n;
715 return true;
716 }
717 }
718 // For non-batch runs, total_iterations_ must be 0 by now.
719 if (is_batch && total_iterations_ != 0) {
720 batch_leftover_ = n - total_iterations_;
721 total_iterations_ = 0;
722 return true;
723 }
724 FinishKeepRunning();
725 return false;
726}
727
728struct State::StateIterator {
729 struct BENCHMARK_UNUSED Value {};
730 typedef std::forward_iterator_tag iterator_category;
731 typedef Value value_type;
732 typedef Value reference;
733 typedef Value pointer;
734 typedef std::ptrdiff_t difference_type;
735
736 private:
737 friend class State;
738 BENCHMARK_ALWAYS_INLINE
739 StateIterator() : cached_(0), parent_() {}
740
741 BENCHMARK_ALWAYS_INLINE
742 explicit StateIterator(State* st)
743 : cached_(st->error_occurred_ ? 0 : st->max_iterations), parent_(st) {}
744
745 public:
746 BENCHMARK_ALWAYS_INLINE
747 Value operator*() const { return Value(); }
748
749 BENCHMARK_ALWAYS_INLINE
750 StateIterator& operator++() {
751 assert(cached_ > 0);
752 --cached_;
753 return *this;
754 }
755
756 BENCHMARK_ALWAYS_INLINE
757 bool operator!=(StateIterator const&) const {
758 if (BENCHMARK_BUILTIN_EXPECT(cached_ != 0, true)) return true;
759 parent_->FinishKeepRunning();
760 return false;
761 }
762
763 private:
764 IterationCount cached_;
765 State* const parent_;
766};
767
768inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::begin() {
769 return StateIterator(this);
770}
771inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::end() {
772 StartKeepRunning();
773 return StateIterator();
774}
775
776namespace internal {
777
778typedef void(Function)(State&);
779
780// ------------------------------------------------------
781// Benchmark registration object. The BENCHMARK() macro expands
782// into an internal::Benchmark* object. Various methods can
783// be called on this object to change the properties of the benchmark.
784// Each method returns "this" so that multiple method calls can
785// chained into one expression.
786class Benchmark {
787 public:
788 virtual ~Benchmark();
789
790 // Note: the following methods all return "this" so that multiple
791 // method calls can be chained together in one expression.
792
793 // Run this benchmark once with "x" as the extra argument passed
794 // to the function.
795 // REQUIRES: The function passed to the constructor must accept an arg1.
796 Benchmark* Arg(int64_t x);
797
798 // Run this benchmark with the given time unit for the generated output report
799 Benchmark* Unit(TimeUnit unit);
800
801 // Run this benchmark once for a number of values picked from the
802 // range [start..limit]. (start and limit are always picked.)
803 // REQUIRES: The function passed to the constructor must accept an arg1.
804 Benchmark* Range(int64_t start, int64_t limit);
805
806 // Run this benchmark once for all values in the range [start..limit] with
807 // specific step
808 // REQUIRES: The function passed to the constructor must accept an arg1.
809 Benchmark* DenseRange(int64_t start, int64_t limit, int step = 1);
810
811 // Run this benchmark once with "args" as the extra arguments passed
812 // to the function.
813 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
814 Benchmark* Args(const std::vector<int64_t>& args);
815
816 // Equivalent to Args({x, y})
817 // NOTE: This is a legacy C++03 interface provided for compatibility only.
818 // New code should use 'Args'.
819 Benchmark* ArgPair(int64_t x, int64_t y) {
820 std::vector<int64_t> args;
821 args.push_back(x);
822 args.push_back(y);
823 return Args(args);
824 }
825
826 // Run this benchmark once for a number of values picked from the
827 // ranges [start..limit]. (starts and limits are always picked.)
828 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
829 Benchmark* Ranges(const std::vector<std::pair<int64_t, int64_t> >& ranges);
830
831 // Run this benchmark once for each combination of values in the (cartesian)
832 // product of the supplied argument lists.
833 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
834 Benchmark* ArgsProduct(const std::vector<std::vector<int64_t> >& arglists);
835
836 // Equivalent to ArgNames({name})
837 Benchmark* ArgName(const std::string& name);
838
839 // Set the argument names to display in the benchmark name. If not called,
840 // only argument values will be shown.
841 Benchmark* ArgNames(const std::vector<std::string>& names);
842
843 // Equivalent to Ranges({{lo1, hi1}, {lo2, hi2}}).
844 // NOTE: This is a legacy C++03 interface provided for compatibility only.
845 // New code should use 'Ranges'.
846 Benchmark* RangePair(int64_t lo1, int64_t hi1, int64_t lo2, int64_t hi2) {
847 std::vector<std::pair<int64_t, int64_t> > ranges;
848 ranges.push_back(std::make_pair(lo1, hi1));
849 ranges.push_back(std::make_pair(lo2, hi2));
850 return Ranges(ranges);
851 }
852
853 // Pass this benchmark object to *func, which can customize
854 // the benchmark by calling various methods like Arg, Args,
855 // Threads, etc.
856 Benchmark* Apply(void (*func)(Benchmark* benchmark));
857
858 // Set the range multiplier for non-dense range. If not called, the range
859 // multiplier kRangeMultiplier will be used.
860 Benchmark* RangeMultiplier(int multiplier);
861
862 // Set the minimum amount of time to use when running this benchmark. This
863 // option overrides the `benchmark_min_time` flag.
864 // REQUIRES: `t > 0` and `Iterations` has not been called on this benchmark.
865 Benchmark* MinTime(double t);
866
867 // Specify the amount of iterations that should be run by this benchmark.
868 // REQUIRES: 'n > 0' and `MinTime` has not been called on this benchmark.
869 //
870 // NOTE: This function should only be used when *exact* iteration control is
871 // needed and never to control or limit how long a benchmark runs, where
872 // `--benchmark_min_time=N` or `MinTime(...)` should be used instead.
873 Benchmark* Iterations(IterationCount n);
874
875 // Specify the amount of times to repeat this benchmark. This option overrides
876 // the `benchmark_repetitions` flag.
877 // REQUIRES: `n > 0`
878 Benchmark* Repetitions(int n);
879
880 // Specify if each repetition of the benchmark should be reported separately
881 // or if only the final statistics should be reported. If the benchmark
882 // is not repeated then the single result is always reported.
883 // Applies to *ALL* reporters (display and file).
884 Benchmark* ReportAggregatesOnly(bool value = true);
885
886 // Same as ReportAggregatesOnly(), but applies to display reporter only.
887 Benchmark* DisplayAggregatesOnly(bool value = true);
888
889 // By default, the CPU time is measured only for the main thread, which may
890 // be unrepresentative if the benchmark uses threads internally. If called,
891 // the total CPU time spent by all the threads will be measured instead.
892 // By default, the only the main thread CPU time will be measured.
893 Benchmark* MeasureProcessCPUTime();
894
895 // If a particular benchmark should use the Wall clock instead of the CPU time
896 // (be it either the CPU time of the main thread only (default), or the
897 // total CPU usage of the benchmark), call this method. If called, the elapsed
898 // (wall) time will be used to control how many iterations are run, and in the
899 // printing of items/second or MB/seconds values.
900 // If not called, the CPU time used by the benchmark will be used.
901 Benchmark* UseRealTime();
902
903 // If a benchmark must measure time manually (e.g. if GPU execution time is
904 // being
905 // measured), call this method. If called, each benchmark iteration should
906 // call
907 // SetIterationTime(seconds) to report the measured time, which will be used
908 // to control how many iterations are run, and in the printing of items/second
909 // or MB/second values.
910 Benchmark* UseManualTime();
911
912 // Set the asymptotic computational complexity for the benchmark. If called
913 // the asymptotic computational complexity will be shown on the output.
914 Benchmark* Complexity(BigO complexity = benchmark::oAuto);
915
916 // Set the asymptotic computational complexity for the benchmark. If called
917 // the asymptotic computational complexity will be shown on the output.
918 Benchmark* Complexity(BigOFunc* complexity);
919
920 // Add this statistics to be computed over all the values of benchmark run
921 Benchmark* ComputeStatistics(std::string name, StatisticsFunc* statistics);
922
923 // Support for running multiple copies of the same benchmark concurrently
924 // in multiple threads. This may be useful when measuring the scaling
925 // of some piece of code.
926
927 // Run one instance of this benchmark concurrently in t threads.
928 Benchmark* Threads(int t);
929
930 // Pick a set of values T from [min_threads,max_threads].
931 // min_threads and max_threads are always included in T. Run this
932 // benchmark once for each value in T. The benchmark run for a
933 // particular value t consists of t threads running the benchmark
934 // function concurrently. For example, consider:
935 // BENCHMARK(Foo)->ThreadRange(1,16);
936 // This will run the following benchmarks:
937 // Foo in 1 thread
938 // Foo in 2 threads
939 // Foo in 4 threads
940 // Foo in 8 threads
941 // Foo in 16 threads
942 Benchmark* ThreadRange(int min_threads, int max_threads);
943
944 // For each value n in the range, run this benchmark once using n threads.
945 // min_threads and max_threads are always included in the range.
946 // stride specifies the increment. E.g. DenseThreadRange(1, 8, 3) starts
947 // a benchmark with 1, 4, 7 and 8 threads.
948 Benchmark* DenseThreadRange(int min_threads, int max_threads, int stride = 1);
949
950 // Equivalent to ThreadRange(NumCPUs(), NumCPUs())
951 Benchmark* ThreadPerCpu();
952
953 virtual void Run(State& state) = 0;
954
955 protected:
956 explicit Benchmark(const char* name);
957 Benchmark(Benchmark const&);
958 void SetName(const char* name);
959
960 int ArgsCnt() const;
961
962 private:
963 friend class BenchmarkFamilies;
964
965 std::string name_;
966 AggregationReportMode aggregation_report_mode_;
967 std::vector<std::string> arg_names_; // Args for all benchmark runs
968 std::vector<std::vector<int64_t> > args_; // Args for all benchmark runs
969 TimeUnit time_unit_;
970 int range_multiplier_;
971 double min_time_;
972 IterationCount iterations_;
973 int repetitions_;
974 bool measure_process_cpu_time_;
975 bool use_real_time_;
976 bool use_manual_time_;
977 BigO complexity_;
978 BigOFunc* complexity_lambda_;
979 std::vector<Statistics> statistics_;
980 std::vector<int> thread_counts_;
981
982 Benchmark& operator=(Benchmark const&);
983};
984
985} // namespace internal
986
987// Create and register a benchmark with the specified 'name' that invokes
988// the specified functor 'fn'.
989//
990// RETURNS: A pointer to the registered benchmark.
991internal::Benchmark* RegisterBenchmark(const char* name,
992 internal::Function* fn);
993
994#if defined(BENCHMARK_HAS_CXX11)
995template <class Lambda>
996internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn);
997#endif
998
999// Remove all registered benchmarks. All pointers to previously registered
1000// benchmarks are invalidated.
1001void ClearRegisteredBenchmarks();
1002
1003namespace internal {
1004// The class used to hold all Benchmarks created from static function.
1005// (ie those created using the BENCHMARK(...) macros.
1006class FunctionBenchmark : public Benchmark {
1007 public:
1008 FunctionBenchmark(const char* name, Function* func)
1009 : Benchmark(name), func_(func) {}
1010
1011 virtual void Run(State& st);
1012
1013 private:
1014 Function* func_;
1015};
1016
1017#ifdef BENCHMARK_HAS_CXX11
1018template <class Lambda>
1019class LambdaBenchmark : public Benchmark {
1020 public:
1021 virtual void Run(State& st) { lambda_(st); }
1022
1023 private:
1024 template <class OLambda>
1025 LambdaBenchmark(const char* name, OLambda&& lam)
1026 : Benchmark(name), lambda_(std::forward<OLambda>(lam)) {}
1027
1028 LambdaBenchmark(LambdaBenchmark const&) = delete;
1029
1030 private:
1031 template <class Lam>
1032 friend Benchmark* ::benchmark::RegisterBenchmark(const char*, Lam&&);
1033
1034 Lambda lambda_;
1035};
1036#endif
1037
1038} // namespace internal
1039
1040inline internal::Benchmark* RegisterBenchmark(const char* name,
1041 internal::Function* fn) {
1042 return internal::RegisterBenchmarkInternal(
1043 ::new internal::FunctionBenchmark(name, fn));
1044}
1045
1046#ifdef BENCHMARK_HAS_CXX11
1047template <class Lambda>
1048internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn) {
1049 using BenchType =
1050 internal::LambdaBenchmark<typename std::decay<Lambda>::type>;
1051 return internal::RegisterBenchmarkInternal(
1052 ::new BenchType(name, std::forward<Lambda>(fn)));
1053}
1054#endif
1055
1056#if defined(BENCHMARK_HAS_CXX11) && \
1057 (!defined(BENCHMARK_GCC_VERSION) || BENCHMARK_GCC_VERSION >= 409)
1058template <class Lambda, class... Args>
1059internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn,
1060 Args&&... args) {
1061 return benchmark::RegisterBenchmark(
1062 name, [=](benchmark::State& st) { fn(st, args...); });
1063}
1064#else
1065#define BENCHMARK_HAS_NO_VARIADIC_REGISTER_BENCHMARK
1066#endif
1067
1068// The base class for all fixture tests.
1069class Fixture : public internal::Benchmark {
1070 public:
1071 Fixture() : internal::Benchmark("") {}
1072
1073 virtual void Run(State& st) {
1074 this->SetUp(st);
1075 this->BenchmarkCase(st);
1076 this->TearDown(st);
1077 }
1078
1079 // These will be deprecated ...
1080 virtual void SetUp(const State&) {}
1081 virtual void TearDown(const State&) {}
1082 // ... In favor of these.
1083 virtual void SetUp(State& st) { SetUp(const_cast<const State&>(st)); }
1084 virtual void TearDown(State& st) { TearDown(const_cast<const State&>(st)); }
1085
1086 protected:
1087 virtual void BenchmarkCase(State&) = 0;
1088};
1089
1090} // namespace benchmark
1091
1092// ------------------------------------------------------
1093// Macro to register benchmarks
1094
1095// Check that __COUNTER__ is defined and that __COUNTER__ increases by 1
1096// every time it is expanded. X + 1 == X + 0 is used in case X is defined to be
1097// empty. If X is empty the expression becomes (+1 == +0).
1098#if defined(__COUNTER__) && (__COUNTER__ + 1 == __COUNTER__ + 0)
1099#define BENCHMARK_PRIVATE_UNIQUE_ID __COUNTER__
1100#else
1101#define BENCHMARK_PRIVATE_UNIQUE_ID __LINE__
1102#endif
1103
1104// Helpers for generating unique variable names
1105#define BENCHMARK_PRIVATE_NAME(n) \
1106 BENCHMARK_PRIVATE_CONCAT(_benchmark_, BENCHMARK_PRIVATE_UNIQUE_ID, n)
1107#define BENCHMARK_PRIVATE_CONCAT(a, b, c) BENCHMARK_PRIVATE_CONCAT2(a, b, c)
1108#define BENCHMARK_PRIVATE_CONCAT2(a, b, c) a##b##c
1109// Helper for concatenation with macro name expansion
1110#define BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method) \
1111 BaseClass##_##Method##_Benchmark
1112
1113#define BENCHMARK_PRIVATE_DECLARE(n) \
1114 static ::benchmark::internal::Benchmark* BENCHMARK_PRIVATE_NAME(n) \
1115 BENCHMARK_UNUSED
1116
1117#define BENCHMARK(n) \
1118 BENCHMARK_PRIVATE_DECLARE(n) = \
1119 (::benchmark::internal::RegisterBenchmarkInternal( \
1120 new ::benchmark::internal::FunctionBenchmark(#n, n)))
1121
1122// Old-style macros
1123#define BENCHMARK_WITH_ARG(n, a) BENCHMARK(n)->Arg((a))
1124#define BENCHMARK_WITH_ARG2(n, a1, a2) BENCHMARK(n)->Args({(a1), (a2)})
1125#define BENCHMARK_WITH_UNIT(n, t) BENCHMARK(n)->Unit((t))
1126#define BENCHMARK_RANGE(n, lo, hi) BENCHMARK(n)->Range((lo), (hi))
1127#define BENCHMARK_RANGE2(n, l1, h1, l2, h2) \
1128 BENCHMARK(n)->RangePair({{(l1), (h1)}, {(l2), (h2)}})
1129
1130#ifdef BENCHMARK_HAS_CXX11
1131
1132// Register a benchmark which invokes the function specified by `func`
1133// with the additional arguments specified by `...`.
1134//
1135// For example:
1136//
1137// template <class ...ExtraArgs>`
1138// void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
1139// [...]
1140//}
1141// /* Registers a benchmark named "BM_takes_args/int_string_test` */
1142// BENCHMARK_CAPTURE(BM_takes_args, int_string_test, 42, std::string("abc"));
1143#define BENCHMARK_CAPTURE(func, test_case_name, ...) \
1144 BENCHMARK_PRIVATE_DECLARE(func) = \
1145 (::benchmark::internal::RegisterBenchmarkInternal( \
1146 new ::benchmark::internal::FunctionBenchmark( \
1147 #func "/" #test_case_name, \
1148 [](::benchmark::State& st) { func(st, __VA_ARGS__); })))
1149
1150#endif // BENCHMARK_HAS_CXX11
1151
1152// This will register a benchmark for a templatized function. For example:
1153//
1154// template<int arg>
1155// void BM_Foo(int iters);
1156//
1157// BENCHMARK_TEMPLATE(BM_Foo, 1);
1158//
1159// will register BM_Foo<1> as a benchmark.
1160#define BENCHMARK_TEMPLATE1(n, a) \
1161 BENCHMARK_PRIVATE_DECLARE(n) = \
1162 (::benchmark::internal::RegisterBenchmarkInternal( \
1163 new ::benchmark::internal::FunctionBenchmark(#n "<" #a ">", n<a>)))
1164
1165#define BENCHMARK_TEMPLATE2(n, a, b) \
1166 BENCHMARK_PRIVATE_DECLARE(n) = \
1167 (::benchmark::internal::RegisterBenchmarkInternal( \
1168 new ::benchmark::internal::FunctionBenchmark(#n "<" #a "," #b ">", \
1169 n<a, b>)))
1170
1171#ifdef BENCHMARK_HAS_CXX11
1172#define BENCHMARK_TEMPLATE(n, ...) \
1173 BENCHMARK_PRIVATE_DECLARE(n) = \
1174 (::benchmark::internal::RegisterBenchmarkInternal( \
1175 new ::benchmark::internal::FunctionBenchmark( \
1176 #n "<" #__VA_ARGS__ ">", n<__VA_ARGS__>)))
1177#else
1178#define BENCHMARK_TEMPLATE(n, a) BENCHMARK_TEMPLATE1(n, a)
1179#endif
1180
1181#define BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1182 class BaseClass##_##Method##_Benchmark : public BaseClass { \
1183 public: \
1184 BaseClass##_##Method##_Benchmark() : BaseClass() { \
1185 this->SetName(#BaseClass "/" #Method); \
1186 } \
1187 \
1188 protected: \
1189 virtual void BenchmarkCase(::benchmark::State&); \
1190 };
1191
1192#define BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1193 class BaseClass##_##Method##_Benchmark : public BaseClass<a> { \
1194 public: \
1195 BaseClass##_##Method##_Benchmark() : BaseClass<a>() { \
1196 this->SetName(#BaseClass "<" #a ">/" #Method); \
1197 } \
1198 \
1199 protected: \
1200 virtual void BenchmarkCase(::benchmark::State&); \
1201 };
1202
1203#define BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1204 class BaseClass##_##Method##_Benchmark : public BaseClass<a, b> { \
1205 public: \
1206 BaseClass##_##Method##_Benchmark() : BaseClass<a, b>() { \
1207 this->SetName(#BaseClass "<" #a "," #b ">/" #Method); \
1208 } \
1209 \
1210 protected: \
1211 virtual void BenchmarkCase(::benchmark::State&); \
1212 };
1213
1214#ifdef BENCHMARK_HAS_CXX11
1215#define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, ...) \
1216 class BaseClass##_##Method##_Benchmark : public BaseClass<__VA_ARGS__> { \
1217 public: \
1218 BaseClass##_##Method##_Benchmark() : BaseClass<__VA_ARGS__>() { \
1219 this->SetName(#BaseClass "<" #__VA_ARGS__ ">/" #Method); \
1220 } \
1221 \
1222 protected: \
1223 virtual void BenchmarkCase(::benchmark::State&); \
1224 };
1225#else
1226#define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(n, a) \
1227 BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(n, a)
1228#endif
1229
1230#define BENCHMARK_DEFINE_F(BaseClass, Method) \
1231 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1232 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1233
1234#define BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a) \
1235 BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1236 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1237
1238#define BENCHMARK_TEMPLATE2_DEFINE_F(BaseClass, Method, a, b) \
1239 BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1240 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1241
1242#ifdef BENCHMARK_HAS_CXX11
1243#define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, ...) \
1244 BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1245 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1246#else
1247#define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, a) \
1248 BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a)
1249#endif
1250
1251#define BENCHMARK_REGISTER_F(BaseClass, Method) \
1252 BENCHMARK_PRIVATE_REGISTER_F(BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method))
1253
1254#define BENCHMARK_PRIVATE_REGISTER_F(TestName) \
1255 BENCHMARK_PRIVATE_DECLARE(TestName) = \
1256 (::benchmark::internal::RegisterBenchmarkInternal(new TestName()))
1257
1258// This macro will define and register a benchmark within a fixture class.
1259#define BENCHMARK_F(BaseClass, Method) \
1260 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1261 BENCHMARK_REGISTER_F(BaseClass, Method); \
1262 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1263
1264#define BENCHMARK_TEMPLATE1_F(BaseClass, Method, a) \
1265 BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1266 BENCHMARK_REGISTER_F(BaseClass, Method); \
1267 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1268
1269#define BENCHMARK_TEMPLATE2_F(BaseClass, Method, a, b) \
1270 BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1271 BENCHMARK_REGISTER_F(BaseClass, Method); \
1272 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1273
1274#ifdef BENCHMARK_HAS_CXX11
1275#define BENCHMARK_TEMPLATE_F(BaseClass, Method, ...) \
1276 BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1277 BENCHMARK_REGISTER_F(BaseClass, Method); \
1278 void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1279#else
1280#define BENCHMARK_TEMPLATE_F(BaseClass, Method, a) \
1281 BENCHMARK_TEMPLATE1_F(BaseClass, Method, a)
1282#endif
1283
1284// Helper macro to create a main routine in a test that runs the benchmarks
1285#define BENCHMARK_MAIN() \
1286 int main(int argc, char** argv) { \
1287 ::benchmark::Initialize(&argc, argv); \
1288 if (::benchmark::ReportUnrecognizedArguments(argc, argv)) return 1; \
1289 ::benchmark::RunSpecifiedBenchmarks(); \
1290 } \
1291 int main(int, char**)
1292
1293// ------------------------------------------------------
1294// Benchmark Reporters
1295
1296namespace benchmark {
1297
1298struct CPUInfo {
1299 struct CacheInfo {
1300 std::string type;
1301 int level;
1302 int size;
1303 int num_sharing;
1304 };
1305
1306 enum Scaling {
1307 UNKNOWN,
1308 ENABLED,
1309 DISABLED
1310 };
1311
1312 int num_cpus;
1313 double cycles_per_second;
1314 std::vector<CacheInfo> caches;
1315 Scaling scaling;
1316 std::vector<double> load_avg;
1317
1318 static const CPUInfo& Get();
1319
1320 private:
1321 CPUInfo();
1322 BENCHMARK_DISALLOW_COPY_AND_ASSIGN(CPUInfo);
1323};
1324
1325// Adding Struct for System Information
1326struct SystemInfo {
1327 std::string name;
1328 static const SystemInfo& Get();
1329
1330 private:
1331 SystemInfo();
1332 BENCHMARK_DISALLOW_COPY_AND_ASSIGN(SystemInfo);
1333};
1334
1335// BenchmarkName contains the components of the Benchmark's name
1336// which allows individual fields to be modified or cleared before
1337// building the final name using 'str()'.
1338struct BenchmarkName {
1339 std::string function_name;
1340 std::string args;
1341 std::string min_time;
1342 std::string iterations;
1343 std::string repetitions;
1344 std::string time_type;
1345 std::string threads;
1346
1347 // Return the full name of the benchmark with each non-empty
1348 // field separated by a '/'
1349 std::string str() const;
1350};
1351
1352// Interface for custom benchmark result printers.
1353// By default, benchmark reports are printed to stdout. However an application
1354// can control the destination of the reports by calling
1355// RunSpecifiedBenchmarks and passing it a custom reporter object.
1356// The reporter object must implement the following interface.
1357class BenchmarkReporter {
1358 public:
1359 struct Context {
1360 CPUInfo const& cpu_info;
1361 SystemInfo const& sys_info;
1362 // The number of chars in the longest benchmark name.
1363 size_t name_field_width;
1364 static const char* executable_name;
1365 Context();
1366 };
1367
1368 struct Run {
1369 static const int64_t no_repetition_index = -1;
1370 enum RunType { RT_Iteration, RT_Aggregate };
1371
1372 Run()
1373 : run_type(RT_Iteration),
1374 error_occurred(false),
1375 iterations(1),
1376 threads(1),
1377 time_unit(kNanosecond),
1378 real_accumulated_time(0),
1379 cpu_accumulated_time(0),
1380 max_heapbytes_used(0),
1381 complexity(oNone),
1382 complexity_lambda(),
1383 complexity_n(0),
1384 report_big_o(false),
1385 report_rms(false),
1386 counters(),
1387 has_memory_result(false),
1388 allocs_per_iter(0.0),
1389 max_bytes_used(0) {}
1390
1391 std::string benchmark_name() const;
1392 BenchmarkName run_name;
1393 RunType run_type;
1394 std::string aggregate_name;
1395 std::string report_label; // Empty if not set by benchmark.
1396 bool error_occurred;
1397 std::string error_message;
1398
1399 IterationCount iterations;
1400 int64_t threads;
1401 int64_t repetition_index;
1402 int64_t repetitions;
1403 TimeUnit time_unit;
1404 double real_accumulated_time;
1405 double cpu_accumulated_time;
1406
1407 // Return a value representing the real time per iteration in the unit
1408 // specified by 'time_unit'.
1409 // NOTE: If 'iterations' is zero the returned value represents the
1410 // accumulated time.
1411 double GetAdjustedRealTime() const;
1412
1413 // Return a value representing the cpu time per iteration in the unit
1414 // specified by 'time_unit'.
1415 // NOTE: If 'iterations' is zero the returned value represents the
1416 // accumulated time.
1417 double GetAdjustedCPUTime() const;
1418
1419 // This is set to 0.0 if memory tracing is not enabled.
1420 double max_heapbytes_used;
1421
1422 // Keep track of arguments to compute asymptotic complexity
1423 BigO complexity;
1424 BigOFunc* complexity_lambda;
1425 int64_t complexity_n;
1426
1427 // what statistics to compute from the measurements
1428 const std::vector<internal::Statistics>* statistics;
1429
1430 // Inform print function whether the current run is a complexity report
1431 bool report_big_o;
1432 bool report_rms;
1433
1434 UserCounters counters;
1435
1436 // Memory metrics.
1437 bool has_memory_result;
1438 double allocs_per_iter;
1439 int64_t max_bytes_used;
1440 };
1441
1442 // Construct a BenchmarkReporter with the output stream set to 'std::cout'
1443 // and the error stream set to 'std::cerr'
1444 BenchmarkReporter();
1445
1446 // Called once for every suite of benchmarks run.
1447 // The parameter "context" contains information that the
1448 // reporter may wish to use when generating its report, for example the
1449 // platform under which the benchmarks are running. The benchmark run is
1450 // never started if this function returns false, allowing the reporter
1451 // to skip runs based on the context information.
1452 virtual bool ReportContext(const Context& context) = 0;
1453
1454 // Called once for each group of benchmark runs, gives information about
1455 // cpu-time and heap memory usage during the benchmark run. If the group
1456 // of runs contained more than two entries then 'report' contains additional
1457 // elements representing the mean and standard deviation of those runs.
1458 // Additionally if this group of runs was the last in a family of benchmarks
1459 // 'reports' contains additional entries representing the asymptotic
1460 // complexity and RMS of that benchmark family.
1461 virtual void ReportRuns(const std::vector<Run>& report) = 0;
1462
1463 // Called once and only once after ever group of benchmarks is run and
1464 // reported.
1465 virtual void Finalize() {}
1466
1467 // REQUIRES: The object referenced by 'out' is valid for the lifetime
1468 // of the reporter.
1469 void SetOutputStream(std::ostream* out) {
1470 assert(out);
1471 output_stream_ = out;
1472 }
1473
1474 // REQUIRES: The object referenced by 'err' is valid for the lifetime
1475 // of the reporter.
1476 void SetErrorStream(std::ostream* err) {
1477 assert(err);
1478 error_stream_ = err;
1479 }
1480
1481 std::ostream& GetOutputStream() const { return *output_stream_; }
1482
1483 std::ostream& GetErrorStream() const { return *error_stream_; }
1484
1485 virtual ~BenchmarkReporter();
1486
1487 // Write a human readable string to 'out' representing the specified
1488 // 'context'.
1489 // REQUIRES: 'out' is non-null.
1490 static void PrintBasicContext(std::ostream* out, Context const& context);
1491
1492 private:
1493 std::ostream* output_stream_;
1494 std::ostream* error_stream_;
1495};
1496
1497// Simple reporter that outputs benchmark data to the console. This is the
1498// default reporter used by RunSpecifiedBenchmarks().
1499class ConsoleReporter : public BenchmarkReporter {
1500 public:
1501 enum OutputOptions {
1502 OO_None = 0,
1503 OO_Color = 1,
1504 OO_Tabular = 2,
1505 OO_ColorTabular = OO_Color | OO_Tabular,
1506 OO_Defaults = OO_ColorTabular
1507 };
1508 explicit ConsoleReporter(OutputOptions opts_ = OO_Defaults)
1509 : output_options_(opts_),
1510 name_field_width_(0),
1511 prev_counters_(),
1512 printed_header_(false) {}
1513
1514 virtual bool ReportContext(const Context& context);
1515 virtual void ReportRuns(const std::vector<Run>& reports);
1516
1517 protected:
1518 virtual void PrintRunData(const Run& report);
1519 virtual void PrintHeader(const Run& report);
1520
1521 OutputOptions output_options_;
1522 size_t name_field_width_;
1523 UserCounters prev_counters_;
1524 bool printed_header_;
1525};
1526
1527class JSONReporter : public BenchmarkReporter {
1528 public:
1529 JSONReporter() : first_report_(true) {}
1530 virtual bool ReportContext(const Context& context);
1531 virtual void ReportRuns(const std::vector<Run>& reports);
1532 virtual void Finalize();
1533
1534 private:
1535 void PrintRunData(const Run& report);
1536
1537 bool first_report_;
1538};
1539
1540class BENCHMARK_DEPRECATED_MSG(
1541 "The CSV Reporter will be removed in a future release") CSVReporter
1542 : public BenchmarkReporter {
1543 public:
1544 CSVReporter() : printed_header_(false) {}
1545 virtual bool ReportContext(const Context& context);
1546 virtual void ReportRuns(const std::vector<Run>& reports);
1547
1548 private:
1549 void PrintRunData(const Run& report);
1550
1551 bool printed_header_;
1552 std::set<std::string> user_counter_names_;
1553};
1554
1555// If a MemoryManager is registered, it can be used to collect and report
1556// allocation metrics for a run of the benchmark.
1557class MemoryManager {
1558 public:
1559 struct Result {
1560 Result() : num_allocs(0), max_bytes_used(0) {}
1561
1562 // The number of allocations made in total between Start and Stop.
1563 int64_t num_allocs;
1564
1565 // The peak memory use between Start and Stop.
1566 int64_t max_bytes_used;
1567 };
1568
1569 virtual ~MemoryManager() {}
1570
1571 // Implement this to start recording allocation information.
1572 virtual void Start() = 0;
1573
1574 // Implement this to stop recording and fill out the given Result structure.
1575 virtual void Stop(Result* result) = 0;
1576};
1577
1578inline const char* GetTimeUnitString(TimeUnit unit) {
1579 switch (unit) {
1580 case kMillisecond:
1581 return "ms";
1582 case kMicrosecond:
1583 return "us";
1584 case kNanosecond:
1585 return "ns";
1586 }
1587 BENCHMARK_UNREACHABLE();
1588}
1589
1590inline double GetTimeUnitMultiplier(TimeUnit unit) {
1591 switch (unit) {
1592 case kMillisecond:
1593 return 1e3;
1594 case kMicrosecond:
1595 return 1e6;
1596 case kNanosecond:
1597 return 1e9;
1598 }
1599 BENCHMARK_UNREACHABLE();
1600}
1601
1602} // namespace benchmark
1603
1604#endif // BENCHMARK_BENCHMARK_H_
1605