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