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