benchmark  1.9.0
benchmark.h
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 --benchmark_filter 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  benchmark::Shutdown();
46  return 0;
47 }
48 
49 // Sometimes a family of microbenchmarks can be implemented with
50 // just one routine that takes an extra argument to specify which
51 // one of the family of benchmarks to run. For example, the following
52 // code defines a family of microbenchmarks for measuring the speed
53 // of memcpy() calls of different lengths:
54 
55 static void BM_memcpy(benchmark::State& state) {
56  char* src = new char[state.range(0)]; char* dst = new char[state.range(0)];
57  memset(src, 'x', state.range(0));
58  for (auto _ : state)
59  memcpy(dst, src, state.range(0));
60  state.SetBytesProcessed(state.iterations() * 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(state.iterations() * state.range(0));
126 }
127 BENCHMARK_TEMPLATE(BM_Sequential, WaitQueue<int>)->Range(1<<0, 1<<10);
128 
129 Use `Benchmark::MinTime(double t)` to set the minimum time used to run the
130 benchmark. This option overrides the `benchmark_min_time` flag.
131 
132 void BM_test(benchmark::State& state) {
133  ... body ...
134 }
135 BENCHMARK(BM_test)->MinTime(2.0); // Run for at least 2 seconds.
136 
137 In a multithreaded test, it is guaranteed that none of the threads will start
138 until all have reached the loop start, and all will have finished before any
139 thread exits the loop body. As such, any global setup or teardown you want to
140 do can be wrapped in a check against the thread index:
141 
142 static void BM_MultiThreaded(benchmark::State& state) {
143  if (state.thread_index() == 0) {
144  // Setup code here.
145  }
146  for (auto _ : state) {
147  // Run the test as normal.
148  }
149  if (state.thread_index() == 0) {
150  // Teardown code here.
151  }
152 }
153 BENCHMARK(BM_MultiThreaded)->Threads(4);
154 
155 
156 If a benchmark runs a few milliseconds it may be hard to visually compare the
157 measured times, since the output data is given in nanoseconds per default. In
158 order to manually set the time unit, you can specify it manually:
159 
160 BENCHMARK(BM_test)->Unit(benchmark::kMillisecond);
161 */
162 
163 #ifndef BENCHMARK_BENCHMARK_H_
164 #define BENCHMARK_BENCHMARK_H_
165 
166 // The _MSVC_LANG check should detect Visual Studio 2015 Update 3 and newer.
167 #if __cplusplus >= 201103L || (defined(_MSVC_LANG) && _MSVC_LANG >= 201103L)
168 #define BENCHMARK_HAS_CXX11
169 #endif
170 
171 // This _MSC_VER check should detect VS 2017 v15.3 and newer.
172 #if __cplusplus >= 201703L || \
173  (defined(_MSC_VER) && _MSC_VER >= 1911 && _MSVC_LANG >= 201703L)
174 #define BENCHMARK_HAS_CXX17
175 #endif
176 
177 #include <stdint.h>
178 
179 #include <algorithm>
180 #include <cassert>
181 #include <cstddef>
182 #include <iosfwd>
183 #include <limits>
184 #include <map>
185 #include <set>
186 #include <string>
187 #include <utility>
188 #include <vector>
189 
190 #include "benchmark/export.h"
191 
192 #if defined(BENCHMARK_HAS_CXX11)
193 #include <atomic>
194 #include <initializer_list>
195 #include <type_traits>
196 #include <utility>
197 #endif
198 
199 #if defined(_MSC_VER)
200 #include <intrin.h> // for _ReadWriteBarrier
201 #endif
202 
203 #ifndef BENCHMARK_HAS_CXX11
204 #define BENCHMARK_DISALLOW_COPY_AND_ASSIGN(TypeName) \
205  TypeName(const TypeName&); \
206  TypeName& operator=(const TypeName&)
207 #else
208 #define BENCHMARK_DISALLOW_COPY_AND_ASSIGN(TypeName) \
209  TypeName(const TypeName&) = delete; \
210  TypeName& operator=(const TypeName&) = delete
211 #endif
212 
213 #ifdef BENCHMARK_HAS_CXX17
214 #define BENCHMARK_UNUSED [[maybe_unused]]
215 #elif defined(__GNUC__) || defined(__clang__)
216 #define BENCHMARK_UNUSED __attribute__((unused))
217 #else
218 #define BENCHMARK_UNUSED
219 #endif
220 
221 // Used to annotate functions, methods and classes so they
222 // are not optimized by the compiler. Useful for tests
223 // where you expect loops to stay in place churning cycles
224 #if defined(__clang__)
225 #define BENCHMARK_DONT_OPTIMIZE __attribute__((optnone))
226 #elif defined(__GNUC__) || defined(__GNUG__)
227 #define BENCHMARK_DONT_OPTIMIZE __attribute__((optimize(0)))
228 #else
229 // MSVC & Intel do not have a no-optimize attribute, only line pragmas
230 #define BENCHMARK_DONT_OPTIMIZE
231 #endif
232 
233 #if defined(__GNUC__) || defined(__clang__)
234 #define BENCHMARK_ALWAYS_INLINE __attribute__((always_inline))
235 #elif defined(_MSC_VER) && !defined(__clang__)
236 #define BENCHMARK_ALWAYS_INLINE __forceinline
237 #define __func__ __FUNCTION__
238 #else
239 #define BENCHMARK_ALWAYS_INLINE
240 #endif
241 
242 #define BENCHMARK_INTERNAL_TOSTRING2(x) #x
243 #define BENCHMARK_INTERNAL_TOSTRING(x) BENCHMARK_INTERNAL_TOSTRING2(x)
244 
245 // clang-format off
246 #if (defined(__GNUC__) && !defined(__NVCC__) && !defined(__NVCOMPILER)) || defined(__clang__)
247 #define BENCHMARK_BUILTIN_EXPECT(x, y) __builtin_expect(x, y)
248 #define BENCHMARK_DEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
249 #define BENCHMARK_DISABLE_DEPRECATED_WARNING \
250  _Pragma("GCC diagnostic push") \
251  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
252 #define BENCHMARK_RESTORE_DEPRECATED_WARNING _Pragma("GCC diagnostic pop")
253 #elif defined(__NVCOMPILER)
254 #define BENCHMARK_BUILTIN_EXPECT(x, y) __builtin_expect(x, y)
255 #define BENCHMARK_DEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
256 #define BENCHMARK_DISABLE_DEPRECATED_WARNING \
257  _Pragma("diagnostic push") \
258  _Pragma("diag_suppress deprecated_entity_with_custom_message")
259 #define BENCHMARK_RESTORE_DEPRECATED_WARNING _Pragma("diagnostic pop")
260 #else
261 #define BENCHMARK_BUILTIN_EXPECT(x, y) x
262 #define BENCHMARK_DEPRECATED_MSG(msg)
263 #define BENCHMARK_WARNING_MSG(msg) \
264  __pragma(message(__FILE__ "(" BENCHMARK_INTERNAL_TOSTRING( \
265  __LINE__) ") : warning note: " msg))
266 #define BENCHMARK_DISABLE_DEPRECATED_WARNING
267 #define BENCHMARK_RESTORE_DEPRECATED_WARNING
268 #endif
269 // clang-format on
270 
271 #if defined(__GNUC__) && !defined(__clang__)
272 #define BENCHMARK_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__)
273 #endif
274 
275 #ifndef __has_builtin
276 #define __has_builtin(x) 0
277 #endif
278 
279 #if defined(__GNUC__) || __has_builtin(__builtin_unreachable)
280 #define BENCHMARK_UNREACHABLE() __builtin_unreachable()
281 #elif defined(_MSC_VER)
282 #define BENCHMARK_UNREACHABLE() __assume(false)
283 #else
284 #define BENCHMARK_UNREACHABLE() ((void)0)
285 #endif
286 
287 #ifdef BENCHMARK_HAS_CXX11
288 #define BENCHMARK_OVERRIDE override
289 #else
290 #define BENCHMARK_OVERRIDE
291 #endif
292 
293 #if defined(_MSC_VER)
294 #pragma warning(push)
295 // C4251: <symbol> needs to have dll-interface to be used by clients of class
296 #pragma warning(disable : 4251)
297 #endif
298 
299 namespace benchmark {
300 class BenchmarkReporter;
301 
302 // Default number of minimum benchmark running time in seconds.
303 const char kDefaultMinTimeStr[] = "0.5s";
304 
305 // Returns the version of the library.
306 BENCHMARK_EXPORT std::string GetBenchmarkVersion();
307 
308 BENCHMARK_EXPORT void PrintDefaultHelp();
309 
310 BENCHMARK_EXPORT void Initialize(int* argc, char** argv,
311  void (*HelperPrinterf)() = PrintDefaultHelp);
312 BENCHMARK_EXPORT void Shutdown();
313 
314 // Report to stdout all arguments in 'argv' as unrecognized except the first.
315 // Returns true there is at least on unrecognized argument (i.e. 'argc' > 1).
316 BENCHMARK_EXPORT bool ReportUnrecognizedArguments(int argc, char** argv);
317 
318 // Returns the current value of --benchmark_filter.
319 BENCHMARK_EXPORT std::string GetBenchmarkFilter();
320 
321 // Sets a new value to --benchmark_filter. (This will override this flag's
322 // current value).
323 // Should be called after `benchmark::Initialize()`, as
324 // `benchmark::Initialize()` will override the flag's value.
325 BENCHMARK_EXPORT void SetBenchmarkFilter(std::string value);
326 
327 // Returns the current value of --v (command line value for verbosity).
328 BENCHMARK_EXPORT int32_t GetBenchmarkVerbosity();
329 
330 // Creates a default display reporter. Used by the library when no display
331 // reporter is provided, but also made available for external use in case a
332 // custom reporter should respect the `--benchmark_format` flag as a fallback
333 BENCHMARK_EXPORT BenchmarkReporter* CreateDefaultDisplayReporter();
334 
335 // Generate a list of benchmarks matching the specified --benchmark_filter flag
336 // and if --benchmark_list_tests is specified return after printing the name
337 // of each matching benchmark. Otherwise run each matching benchmark and
338 // report the results.
339 //
340 // spec : Specify the benchmarks to run. If users do not specify this arg,
341 // then the value of FLAGS_benchmark_filter
342 // will be used.
343 //
344 // The second and third overload use the specified 'display_reporter' and
345 // 'file_reporter' respectively. 'file_reporter' will write to the file
346 // specified
347 // by '--benchmark_out'. If '--benchmark_out' is not given the
348 // 'file_reporter' is ignored.
349 //
350 // RETURNS: The number of matching benchmarks.
351 BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks();
352 BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks(std::string spec);
353 
354 BENCHMARK_EXPORT size_t
355 RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter);
356 BENCHMARK_EXPORT size_t
357 RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter, std::string spec);
358 
359 BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks(
360  BenchmarkReporter* display_reporter, BenchmarkReporter* file_reporter);
361 BENCHMARK_EXPORT size_t
362 RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter,
363  BenchmarkReporter* file_reporter, std::string spec);
364 
365 // TimeUnit is passed to a benchmark in order to specify the order of magnitude
366 // for the measured time.
367 enum TimeUnit { kNanosecond, kMicrosecond, kMillisecond, kSecond };
368 
369 BENCHMARK_EXPORT TimeUnit GetDefaultTimeUnit();
370 
371 // Sets the default time unit the benchmarks use
372 // Has to be called before the benchmark loop to take effect
373 BENCHMARK_EXPORT void SetDefaultTimeUnit(TimeUnit unit);
374 
375 // If a MemoryManager is registered (via RegisterMemoryManager()),
376 // it can be used to collect and report allocation metrics for a run of the
377 // benchmark.
379  public:
380  static const int64_t TombstoneValue;
381 
382  struct Result {
383  Result()
384  : num_allocs(0),
385  max_bytes_used(0),
386  total_allocated_bytes(TombstoneValue),
387  net_heap_growth(TombstoneValue) {}
388 
389  // The number of allocations made in total between Start and Stop.
390  int64_t num_allocs;
391 
392  // The peak memory use between Start and Stop.
393  int64_t max_bytes_used;
394 
395  // The total memory allocated, in bytes, between Start and Stop.
396  // Init'ed to TombstoneValue if metric not available.
397  int64_t total_allocated_bytes;
398 
399  // The net changes in memory, in bytes, between Start and Stop.
400  // ie., total_allocated_bytes - total_deallocated_bytes.
401  // Init'ed to TombstoneValue if metric not available.
402  int64_t net_heap_growth;
403  };
404 
405  virtual ~MemoryManager() {}
406 
407  // Implement this to start recording allocation information.
408  virtual void Start() = 0;
409 
410  // Implement this to stop recording and fill out the given Result structure.
411  virtual void Stop(Result& result) = 0;
412 };
413 
414 // Register a MemoryManager instance that will be used to collect and report
415 // allocation measurements for benchmark runs.
416 BENCHMARK_EXPORT
417 void RegisterMemoryManager(MemoryManager* memory_manager);
418 
419 // If a ProfilerManager is registered (via RegisterProfilerManager()), the
420 // benchmark will be run an additional time under the profiler to collect and
421 // report profile metrics for the run of the benchmark.
423  public:
424  virtual ~ProfilerManager() {}
425 
426  // This is called after `Setup()` code and right before the benchmark is run.
427  virtual void AfterSetupStart() = 0;
428 
429  // This is called before `Teardown()` code and right after the benchmark
430  // completes.
431  virtual void BeforeTeardownStop() = 0;
432 };
433 
434 // Register a ProfilerManager instance that will be used to collect and report
435 // profile measurements for benchmark runs.
436 BENCHMARK_EXPORT
437 void RegisterProfilerManager(ProfilerManager* profiler_manager);
438 
439 // Add a key-value pair to output as part of the context stanza in the report.
440 BENCHMARK_EXPORT
441 void AddCustomContext(const std::string& key, const std::string& value);
442 
443 namespace internal {
444 class Benchmark;
445 class BenchmarkImp;
446 class BenchmarkFamilies;
447 
448 BENCHMARK_EXPORT std::map<std::string, std::string>*& GetGlobalContext();
449 
450 BENCHMARK_EXPORT
451 void UseCharPointer(char const volatile*);
452 
453 // Take ownership of the pointer and register the benchmark. Return the
454 // registered benchmark.
455 BENCHMARK_EXPORT Benchmark* RegisterBenchmarkInternal(Benchmark*);
456 
457 // Ensure that the standard streams are properly initialized in every TU.
458 BENCHMARK_EXPORT int InitializeStreams();
459 BENCHMARK_UNUSED static int stream_init_anchor = InitializeStreams();
460 
461 } // namespace internal
462 
463 #if (!defined(__GNUC__) && !defined(__clang__)) || defined(__pnacl__) || \
464  defined(__EMSCRIPTEN__)
465 #define BENCHMARK_HAS_NO_INLINE_ASSEMBLY
466 #endif
467 
468 // Force the compiler to flush pending writes to global memory. Acts as an
469 // effective read/write barrier
470 #ifdef BENCHMARK_HAS_CXX11
471 inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() {
472  std::atomic_signal_fence(std::memory_order_acq_rel);
473 }
474 #endif
475 
476 // The DoNotOptimize(...) function can be used to prevent a value or
477 // expression from being optimized away by the compiler. This function is
478 // intended to add little to no overhead.
479 // See: https://youtu.be/nXaxk27zwlk?t=2441
480 #ifndef BENCHMARK_HAS_NO_INLINE_ASSEMBLY
481 #if !defined(__GNUC__) || defined(__llvm__) || defined(__INTEL_COMPILER)
482 template <class Tp>
483 BENCHMARK_DEPRECATED_MSG(
484  "The const-ref version of this method can permit "
485  "undesired compiler optimizations in benchmarks")
486 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
487  asm volatile("" : : "r,m"(value) : "memory");
488 }
489 
490 template <class Tp>
491 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp& value) {
492 #if defined(__clang__)
493  asm volatile("" : "+r,m"(value) : : "memory");
494 #else
495  asm volatile("" : "+m,r"(value) : : "memory");
496 #endif
497 }
498 
499 #ifdef BENCHMARK_HAS_CXX11
500 template <class Tp>
501 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp&& value) {
502 #if defined(__clang__)
503  asm volatile("" : "+r,m"(value) : : "memory");
504 #else
505  asm volatile("" : "+m,r"(value) : : "memory");
506 #endif
507 }
508 #endif
509 #elif defined(BENCHMARK_HAS_CXX11) && (__GNUC__ >= 5)
510 // Workaround for a bug with full argument copy overhead with GCC.
511 // See: #1340 and https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105519
512 template <class Tp>
513 BENCHMARK_DEPRECATED_MSG(
514  "The const-ref version of this method can permit "
515  "undesired compiler optimizations in benchmarks")
516 inline BENCHMARK_ALWAYS_INLINE
517  typename std::enable_if<std::is_trivially_copyable<Tp>::value &&
518  (sizeof(Tp) <= sizeof(Tp*))>::type
519  DoNotOptimize(Tp const& value) {
520  asm volatile("" : : "r,m"(value) : "memory");
521 }
522 
523 template <class Tp>
524 BENCHMARK_DEPRECATED_MSG(
525  "The const-ref version of this method can permit "
526  "undesired compiler optimizations in benchmarks")
527 inline BENCHMARK_ALWAYS_INLINE
528  typename std::enable_if<!std::is_trivially_copyable<Tp>::value ||
529  (sizeof(Tp) > sizeof(Tp*))>::type
530  DoNotOptimize(Tp const& value) {
531  asm volatile("" : : "m"(value) : "memory");
532 }
533 
534 template <class Tp>
535 inline BENCHMARK_ALWAYS_INLINE
536  typename std::enable_if<std::is_trivially_copyable<Tp>::value &&
537  (sizeof(Tp) <= sizeof(Tp*))>::type
538  DoNotOptimize(Tp& value) {
539  asm volatile("" : "+m,r"(value) : : "memory");
540 }
541 
542 template <class Tp>
543 inline BENCHMARK_ALWAYS_INLINE
544  typename std::enable_if<!std::is_trivially_copyable<Tp>::value ||
545  (sizeof(Tp) > sizeof(Tp*))>::type
546  DoNotOptimize(Tp& value) {
547  asm volatile("" : "+m"(value) : : "memory");
548 }
549 
550 template <class Tp>
551 inline BENCHMARK_ALWAYS_INLINE
552  typename std::enable_if<std::is_trivially_copyable<Tp>::value &&
553  (sizeof(Tp) <= sizeof(Tp*))>::type
554  DoNotOptimize(Tp&& value) {
555  asm volatile("" : "+m,r"(value) : : "memory");
556 }
557 
558 template <class Tp>
559 inline BENCHMARK_ALWAYS_INLINE
560  typename std::enable_if<!std::is_trivially_copyable<Tp>::value ||
561  (sizeof(Tp) > sizeof(Tp*))>::type
562  DoNotOptimize(Tp&& value) {
563  asm volatile("" : "+m"(value) : : "memory");
564 }
565 
566 #else
567 // Fallback for GCC < 5. Can add some overhead because the compiler is forced
568 // to use memory operations instead of operations with registers.
569 // TODO: Remove if GCC < 5 will be unsupported.
570 template <class Tp>
571 BENCHMARK_DEPRECATED_MSG(
572  "The const-ref version of this method can permit "
573  "undesired compiler optimizations in benchmarks")
574 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
575  asm volatile("" : : "m"(value) : "memory");
576 }
577 
578 template <class Tp>
579 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp& value) {
580  asm volatile("" : "+m"(value) : : "memory");
581 }
582 
583 #ifdef BENCHMARK_HAS_CXX11
584 template <class Tp>
585 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp&& value) {
586  asm volatile("" : "+m"(value) : : "memory");
587 }
588 #endif
589 #endif
590 
591 #ifndef BENCHMARK_HAS_CXX11
592 inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() {
593  asm volatile("" : : : "memory");
594 }
595 #endif
596 #elif defined(_MSC_VER)
597 template <class Tp>
598 BENCHMARK_DEPRECATED_MSG(
599  "The const-ref version of this method can permit "
600  "undesired compiler optimizations in benchmarks")
601 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
602  internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
603  _ReadWriteBarrier();
604 }
605 
606 #ifndef BENCHMARK_HAS_CXX11
607 inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() { _ReadWriteBarrier(); }
608 #endif
609 #else
610 #ifdef BENCHMARK_HAS_CXX11
611 template <class Tp>
612 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp&& value) {
613  internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
614 }
615 #else
616 template <class Tp>
617 BENCHMARK_DEPRECATED_MSG(
618  "The const-ref version of this method can permit "
619  "undesired compiler optimizations in benchmarks")
620 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
621  internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
622 }
623 
624 template <class Tp>
625 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp& value) {
626  internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
627 }
628 #endif
629 // FIXME Add ClobberMemory() for non-gnu and non-msvc compilers, before C++11.
630 #endif
631 
632 // This class is used for user-defined counters.
633 class Counter {
634  public:
635  enum Flags {
636  kDefaults = 0,
637  // Mark the counter as a rate. It will be presented divided
638  // by the duration of the benchmark.
639  kIsRate = 1 << 0,
640  // Mark the counter as a thread-average quantity. It will be
641  // presented divided by the number of threads.
642  kAvgThreads = 1 << 1,
643  // Mark the counter as a thread-average rate. See above.
644  kAvgThreadsRate = kIsRate | kAvgThreads,
645  // Mark the counter as a constant value, valid/same for *every* iteration.
646  // When reporting, it will be *multiplied* by the iteration count.
647  kIsIterationInvariant = 1 << 2,
648  // Mark the counter as a constant rate.
649  // When reporting, it will be *multiplied* by the iteration count
650  // and then divided by the duration of the benchmark.
651  kIsIterationInvariantRate = kIsRate | kIsIterationInvariant,
652  // Mark the counter as a iteration-average quantity.
653  // It will be presented divided by the number of iterations.
654  kAvgIterations = 1 << 3,
655  // Mark the counter as a iteration-average rate. See above.
656  kAvgIterationsRate = kIsRate | kAvgIterations,
657 
658  // In the end, invert the result. This is always done last!
659  kInvert = 1 << 31
660  };
661 
662  enum OneK {
663  // 1'000 items per 1k
664  kIs1000 = 1000,
665  // 1'024 items per 1k
666  kIs1024 = 1024
667  };
668 
669  double value;
670  Flags flags;
671  OneK oneK;
672 
673  BENCHMARK_ALWAYS_INLINE
674  Counter(double v = 0., Flags f = kDefaults, OneK k = kIs1000)
675  : value(v), flags(f), oneK(k) {}
676 
677  BENCHMARK_ALWAYS_INLINE operator double const &() const { return value; }
678  BENCHMARK_ALWAYS_INLINE operator double&() { return value; }
679 };
680 
681 // A helper for user code to create unforeseen combinations of Flags, without
682 // having to do this cast manually each time, or providing this operator.
683 Counter::Flags inline operator|(const Counter::Flags& LHS,
684  const Counter::Flags& RHS) {
685  return static_cast<Counter::Flags>(static_cast<int>(LHS) |
686  static_cast<int>(RHS));
687 }
688 
689 // This is the container for the user-defined counters.
690 typedef std::map<std::string, Counter> UserCounters;
691 
692 // BigO is passed to a benchmark in order to specify the asymptotic
693 // computational
694 // complexity for the benchmark. In case oAuto is selected, complexity will be
695 // calculated automatically to the best fit.
696 enum BigO { oNone, o1, oN, oNSquared, oNCubed, oLogN, oNLogN, oAuto, oLambda };
697 
698 typedef int64_t ComplexityN;
699 
700 typedef int64_t IterationCount;
701 
702 enum StatisticUnit { kTime, kPercentage };
703 
704 // BigOFunc is passed to a benchmark in order to specify the asymptotic
705 // computational complexity for the benchmark.
706 typedef double(BigOFunc)(ComplexityN);
707 
708 // StatisticsFunc is passed to a benchmark in order to compute some descriptive
709 // statistics over all the measurements of some type
710 typedef double(StatisticsFunc)(const std::vector<double>&);
711 
712 namespace internal {
713 struct Statistics {
714  std::string name_;
715  StatisticsFunc* compute_;
716  StatisticUnit unit_;
717 
718  Statistics(const std::string& name, StatisticsFunc* compute,
719  StatisticUnit unit = kTime)
720  : name_(name), compute_(compute), unit_(unit) {}
721 };
722 
723 class BenchmarkInstance;
724 class ThreadTimer;
725 class ThreadManager;
727 
728 enum AggregationReportMode
729 #if defined(BENCHMARK_HAS_CXX11)
730  : unsigned
731 #else
732 #endif
733 {
734  // The mode has not been manually specified
735  ARM_Unspecified = 0,
736  // The mode is user-specified.
737  // This may or may not be set when the following bit-flags are set.
738  ARM_Default = 1U << 0U,
739  // File reporter should only output aggregates.
740  ARM_FileReportAggregatesOnly = 1U << 1U,
741  // Display reporter should only output aggregates
742  ARM_DisplayReportAggregatesOnly = 1U << 2U,
743  // Both reporters should only display aggregates.
744  ARM_ReportAggregatesOnly =
745  ARM_FileReportAggregatesOnly | ARM_DisplayReportAggregatesOnly
746 };
747 
748 enum Skipped
749 #if defined(BENCHMARK_HAS_CXX11)
750  : unsigned
751 #endif
752 {
753  NotSkipped = 0,
754  SkippedWithMessage,
755  SkippedWithError
756 };
757 
758 } // namespace internal
759 
760 // State is passed to a running Benchmark and contains state for the
761 // benchmark to use.
762 class BENCHMARK_EXPORT State {
763  public:
764  struct StateIterator;
765  friend struct StateIterator;
766 
767  // Returns iterators used to run each iteration of a benchmark using a
768  // C++11 ranged-based for loop. These functions should not be called directly.
769  //
770  // REQUIRES: The benchmark has not started running yet. Neither begin nor end
771  // have been called previously.
772  //
773  // NOTE: KeepRunning may not be used after calling either of these functions.
774  inline BENCHMARK_ALWAYS_INLINE StateIterator begin();
775  inline BENCHMARK_ALWAYS_INLINE StateIterator end();
776 
777  // Returns true if the benchmark should continue through another iteration.
778  // NOTE: A benchmark may not return from the test until KeepRunning() has
779  // returned false.
780  inline bool KeepRunning();
781 
782  // Returns true iff the benchmark should run n more iterations.
783  // REQUIRES: 'n' > 0.
784  // NOTE: A benchmark must not return from the test until KeepRunningBatch()
785  // has returned false.
786  // NOTE: KeepRunningBatch() may overshoot by up to 'n' iterations.
787  //
788  // Intended usage:
789  // while (state.KeepRunningBatch(1000)) {
790  // // process 1000 elements
791  // }
792  inline bool KeepRunningBatch(IterationCount n);
793 
794  // REQUIRES: timer is running and 'SkipWithMessage(...)' or
795  // 'SkipWithError(...)' has not been called by the current thread.
796  // Stop the benchmark timer. If not called, the timer will be
797  // automatically stopped after the last iteration of the benchmark loop.
798  //
799  // For threaded benchmarks the PauseTiming() function only pauses the timing
800  // for the current thread.
801  //
802  // NOTE: The "real time" measurement is per-thread. If different threads
803  // report different measurements the largest one is reported.
804  //
805  // NOTE: PauseTiming()/ResumeTiming() are relatively
806  // heavyweight, and so their use should generally be avoided
807  // within each benchmark iteration, if possible.
808  void PauseTiming();
809 
810  // REQUIRES: timer is not running and 'SkipWithMessage(...)' or
811  // 'SkipWithError(...)' has not been called by the current thread.
812  // Start the benchmark timer. The timer is NOT running on entrance to the
813  // benchmark function. It begins running after control flow enters the
814  // benchmark loop.
815  //
816  // NOTE: PauseTiming()/ResumeTiming() are relatively
817  // heavyweight, and so their use should generally be avoided
818  // within each benchmark iteration, if possible.
819  void ResumeTiming();
820 
821  // REQUIRES: 'SkipWithMessage(...)' or 'SkipWithError(...)' has not been
822  // called previously by the current thread.
823  // Report the benchmark as resulting in being skipped with the specified
824  // 'msg'.
825  // After this call the user may explicitly 'return' from the benchmark.
826  //
827  // If the ranged-for style of benchmark loop is used, the user must explicitly
828  // break from the loop, otherwise all future iterations will be run.
829  // If the 'KeepRunning()' loop is used the current thread will automatically
830  // exit the loop at the end of the current iteration.
831  //
832  // For threaded benchmarks only the current thread stops executing and future
833  // calls to `KeepRunning()` will block until all threads have completed
834  // the `KeepRunning()` loop. If multiple threads report being skipped only the
835  // first skip message is used.
836  //
837  // NOTE: Calling 'SkipWithMessage(...)' does not cause the benchmark to exit
838  // the current scope immediately. If the function is called from within
839  // the 'KeepRunning()' loop the current iteration will finish. It is the users
840  // responsibility to exit the scope as needed.
841  void SkipWithMessage(const std::string& msg);
842 
843  // REQUIRES: 'SkipWithMessage(...)' or 'SkipWithError(...)' has not been
844  // called previously by the current thread.
845  // Report the benchmark as resulting in an error with the specified 'msg'.
846  // After this call the user may explicitly 'return' from the benchmark.
847  //
848  // If the ranged-for style of benchmark loop is used, the user must explicitly
849  // break from the loop, otherwise all future iterations will be run.
850  // If the 'KeepRunning()' loop is used the current thread will automatically
851  // exit the loop at the end of the current iteration.
852  //
853  // For threaded benchmarks only the current thread stops executing and future
854  // calls to `KeepRunning()` will block until all threads have completed
855  // the `KeepRunning()` loop. If multiple threads report an error only the
856  // first error message is used.
857  //
858  // NOTE: Calling 'SkipWithError(...)' does not cause the benchmark to exit
859  // the current scope immediately. If the function is called from within
860  // the 'KeepRunning()' loop the current iteration will finish. It is the users
861  // responsibility to exit the scope as needed.
862  void SkipWithError(const std::string& msg);
863 
864  // Returns true if 'SkipWithMessage(...)' or 'SkipWithError(...)' was called.
865  bool skipped() const { return internal::NotSkipped != skipped_; }
866 
867  // Returns true if an error has been reported with 'SkipWithError(...)'.
868  bool error_occurred() const { return internal::SkippedWithError == skipped_; }
869 
870  // REQUIRES: called exactly once per iteration of the benchmarking loop.
871  // Set the manually measured time for this benchmark iteration, which
872  // is used instead of automatically measured time if UseManualTime() was
873  // specified.
874  //
875  // For threaded benchmarks the final value will be set to the largest
876  // reported values.
877  void SetIterationTime(double seconds);
878 
879  // Set the number of bytes processed by the current benchmark
880  // execution. This routine is typically called once at the end of a
881  // throughput oriented benchmark.
882  //
883  // REQUIRES: a benchmark has exited its benchmarking loop.
884  BENCHMARK_ALWAYS_INLINE
885  void SetBytesProcessed(int64_t bytes) {
886  counters["bytes_per_second"] =
887  Counter(static_cast<double>(bytes), Counter::kIsRate, Counter::kIs1024);
888  }
889 
890  BENCHMARK_ALWAYS_INLINE
891  int64_t bytes_processed() const {
892  if (counters.find("bytes_per_second") != counters.end())
893  return static_cast<int64_t>(counters.at("bytes_per_second"));
894  return 0;
895  }
896 
897  // If this routine is called with complexity_n > 0 and complexity report is
898  // requested for the
899  // family benchmark, then current benchmark will be part of the computation
900  // and complexity_n will
901  // represent the length of N.
902  BENCHMARK_ALWAYS_INLINE
903  void SetComplexityN(ComplexityN complexity_n) {
904  complexity_n_ = complexity_n;
905  }
906 
907  BENCHMARK_ALWAYS_INLINE
908  ComplexityN complexity_length_n() const { return complexity_n_; }
909 
910  // If this routine is called with items > 0, then an items/s
911  // label is printed on the benchmark report line for the currently
912  // executing benchmark. It is typically called at the end of a processing
913  // benchmark where a processing items/second output is desired.
914  //
915  // REQUIRES: a benchmark has exited its benchmarking loop.
916  BENCHMARK_ALWAYS_INLINE
917  void SetItemsProcessed(int64_t items) {
918  counters["items_per_second"] =
919  Counter(static_cast<double>(items), benchmark::Counter::kIsRate);
920  }
921 
922  BENCHMARK_ALWAYS_INLINE
923  int64_t items_processed() const {
924  if (counters.find("items_per_second") != counters.end())
925  return static_cast<int64_t>(counters.at("items_per_second"));
926  return 0;
927  }
928 
929  // If this routine is called, the specified label is printed at the
930  // end of the benchmark report line for the currently executing
931  // benchmark. Example:
932  // static void BM_Compress(benchmark::State& state) {
933  // ...
934  // double compress = input_size / output_size;
935  // state.SetLabel(StrFormat("compress:%.1f%%", 100.0*compression));
936  // }
937  // Produces output that looks like:
938  // BM_Compress 50 50 14115038 compress:27.3%
939  //
940  // REQUIRES: a benchmark has exited its benchmarking loop.
941  void SetLabel(const std::string& label);
942 
943  // Range arguments for this run. CHECKs if the argument has been set.
944  BENCHMARK_ALWAYS_INLINE
945  int64_t range(std::size_t pos = 0) const {
946  assert(range_.size() > pos);
947  return range_[pos];
948  }
949 
950  BENCHMARK_DEPRECATED_MSG("use 'range(0)' instead")
951  int64_t range_x() const { return range(0); }
952 
953  BENCHMARK_DEPRECATED_MSG("use 'range(1)' instead")
954  int64_t range_y() const { return range(1); }
955 
956  // Number of threads concurrently executing the benchmark.
957  BENCHMARK_ALWAYS_INLINE
958  int threads() const { return threads_; }
959 
960  // Index of the executing thread. Values from [0, threads).
961  BENCHMARK_ALWAYS_INLINE
962  int thread_index() const { return thread_index_; }
963 
964  BENCHMARK_ALWAYS_INLINE
965  IterationCount iterations() const {
966  if (BENCHMARK_BUILTIN_EXPECT(!started_, false)) {
967  return 0;
968  }
969  return max_iterations - total_iterations_ + batch_leftover_;
970  }
971 
972  BENCHMARK_ALWAYS_INLINE
973  std::string name() const { return name_; }
974 
975  private:
976  // items we expect on the first cache line (ie 64 bytes of the struct)
977  // When total_iterations_ is 0, KeepRunning() and friends will return false.
978  // May be larger than max_iterations.
979  IterationCount total_iterations_;
980 
981  // When using KeepRunningBatch(), batch_leftover_ holds the number of
982  // iterations beyond max_iters that were run. Used to track
983  // completed_iterations_ accurately.
984  IterationCount batch_leftover_;
985 
986  public:
987  const IterationCount max_iterations;
988 
989  private:
990  bool started_;
991  bool finished_;
992  internal::Skipped skipped_;
993 
994  // items we don't need on the first cache line
995  std::vector<int64_t> range_;
996 
997  ComplexityN complexity_n_;
998 
999  public:
1000  // Container for user-defined counters.
1001  UserCounters counters;
1002 
1003  private:
1004  State(std::string name, IterationCount max_iters,
1005  const std::vector<int64_t>& ranges, int thread_i, int n_threads,
1007  internal::PerfCountersMeasurement* perf_counters_measurement,
1008  ProfilerManager* profiler_manager);
1009 
1010  void StartKeepRunning();
1011  // Implementation of KeepRunning() and KeepRunningBatch().
1012  // is_batch must be true unless n is 1.
1013  inline bool KeepRunningInternal(IterationCount n, bool is_batch);
1014  void FinishKeepRunning();
1015 
1016  const std::string name_;
1017  const int thread_index_;
1018  const int threads_;
1019 
1020  internal::ThreadTimer* const timer_;
1021  internal::ThreadManager* const manager_;
1022  internal::PerfCountersMeasurement* const perf_counters_measurement_;
1023  ProfilerManager* const profiler_manager_;
1024 
1025  friend class internal::BenchmarkInstance;
1026 };
1027 
1028 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunning() {
1029  return KeepRunningInternal(1, /*is_batch=*/false);
1030 }
1031 
1032 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningBatch(IterationCount n) {
1033  return KeepRunningInternal(n, /*is_batch=*/true);
1034 }
1035 
1036 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningInternal(IterationCount n,
1037  bool is_batch) {
1038  // total_iterations_ is set to 0 by the constructor, and always set to a
1039  // nonzero value by StartKepRunning().
1040  assert(n > 0);
1041  // n must be 1 unless is_batch is true.
1042  assert(is_batch || n == 1);
1043  if (BENCHMARK_BUILTIN_EXPECT(total_iterations_ >= n, true)) {
1044  total_iterations_ -= n;
1045  return true;
1046  }
1047  if (!started_) {
1048  StartKeepRunning();
1049  if (!skipped() && total_iterations_ >= n) {
1050  total_iterations_ -= n;
1051  return true;
1052  }
1053  }
1054  // For non-batch runs, total_iterations_ must be 0 by now.
1055  if (is_batch && total_iterations_ != 0) {
1056  batch_leftover_ = n - total_iterations_;
1057  total_iterations_ = 0;
1058  return true;
1059  }
1060  FinishKeepRunning();
1061  return false;
1062 }
1063 
1065  struct BENCHMARK_UNUSED Value {};
1066  typedef std::forward_iterator_tag iterator_category;
1067  typedef Value value_type;
1068  typedef Value reference;
1069  typedef Value pointer;
1070  typedef std::ptrdiff_t difference_type;
1071 
1072  private:
1073  friend class State;
1074  BENCHMARK_ALWAYS_INLINE
1075  StateIterator() : cached_(0), parent_() {}
1076 
1077  BENCHMARK_ALWAYS_INLINE
1078  explicit StateIterator(State* st)
1079  : cached_(st->skipped() ? 0 : st->max_iterations), parent_(st) {}
1080 
1081  public:
1082  BENCHMARK_ALWAYS_INLINE
1083  Value operator*() const { return Value(); }
1084 
1085  BENCHMARK_ALWAYS_INLINE
1086  StateIterator& operator++() {
1087  assert(cached_ > 0);
1088  --cached_;
1089  return *this;
1090  }
1091 
1092  BENCHMARK_ALWAYS_INLINE
1093  bool operator!=(StateIterator const&) const {
1094  if (BENCHMARK_BUILTIN_EXPECT(cached_ != 0, true)) return true;
1095  parent_->FinishKeepRunning();
1096  return false;
1097  }
1098 
1099  private:
1100  IterationCount cached_;
1101  State* const parent_;
1102 };
1103 
1104 inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::begin() {
1105  return StateIterator(this);
1106 }
1107 inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::end() {
1108  StartKeepRunning();
1109  return StateIterator();
1110 }
1111 
1112 namespace internal {
1113 
1114 typedef void(Function)(State&);
1115 
1116 // ------------------------------------------------------
1117 // Benchmark registration object. The BENCHMARK() macro expands
1118 // into an internal::Benchmark* object. Various methods can
1119 // be called on this object to change the properties of the benchmark.
1120 // Each method returns "this" so that multiple method calls can
1121 // chained into one expression.
1122 class BENCHMARK_EXPORT Benchmark {
1123  public:
1124  virtual ~Benchmark();
1125 
1126  // Note: the following methods all return "this" so that multiple
1127  // method calls can be chained together in one expression.
1128 
1129  // Specify the name of the benchmark
1130  Benchmark* Name(const std::string& name);
1131 
1132  // Run this benchmark once with "x" as the extra argument passed
1133  // to the function.
1134  // REQUIRES: The function passed to the constructor must accept an arg1.
1135  Benchmark* Arg(int64_t x);
1136 
1137  // Run this benchmark with the given time unit for the generated output report
1138  Benchmark* Unit(TimeUnit unit);
1139 
1140  // Run this benchmark once for a number of values picked from the
1141  // range [start..limit]. (start and limit are always picked.)
1142  // REQUIRES: The function passed to the constructor must accept an arg1.
1143  Benchmark* Range(int64_t start, int64_t limit);
1144 
1145  // Run this benchmark once for all values in the range [start..limit] with
1146  // specific step
1147  // REQUIRES: The function passed to the constructor must accept an arg1.
1148  Benchmark* DenseRange(int64_t start, int64_t limit, int step = 1);
1149 
1150  // Run this benchmark once with "args" as the extra arguments passed
1151  // to the function.
1152  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1153  Benchmark* Args(const std::vector<int64_t>& args);
1154 
1155  // Equivalent to Args({x, y})
1156  // NOTE: This is a legacy C++03 interface provided for compatibility only.
1157  // New code should use 'Args'.
1158  Benchmark* ArgPair(int64_t x, int64_t y) {
1159  std::vector<int64_t> args;
1160  args.push_back(x);
1161  args.push_back(y);
1162  return Args(args);
1163  }
1164 
1165  // Run this benchmark once for a number of values picked from the
1166  // ranges [start..limit]. (starts and limits are always picked.)
1167  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1168  Benchmark* Ranges(const std::vector<std::pair<int64_t, int64_t> >& ranges);
1169 
1170  // Run this benchmark once for each combination of values in the (cartesian)
1171  // product of the supplied argument lists.
1172  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1173  Benchmark* ArgsProduct(const std::vector<std::vector<int64_t> >& arglists);
1174 
1175  // Equivalent to ArgNames({name})
1176  Benchmark* ArgName(const std::string& name);
1177 
1178  // Set the argument names to display in the benchmark name. If not called,
1179  // only argument values will be shown.
1180  Benchmark* ArgNames(const std::vector<std::string>& names);
1181 
1182  // Equivalent to Ranges({{lo1, hi1}, {lo2, hi2}}).
1183  // NOTE: This is a legacy C++03 interface provided for compatibility only.
1184  // New code should use 'Ranges'.
1185  Benchmark* RangePair(int64_t lo1, int64_t hi1, int64_t lo2, int64_t hi2) {
1186  std::vector<std::pair<int64_t, int64_t> > ranges;
1187  ranges.push_back(std::make_pair(lo1, hi1));
1188  ranges.push_back(std::make_pair(lo2, hi2));
1189  return Ranges(ranges);
1190  }
1191 
1192  // Have "setup" and/or "teardown" invoked once for every benchmark run.
1193  // If the benchmark is multi-threaded (will run in k threads concurrently),
1194  // the setup callback will be be invoked exactly once (not k times) before
1195  // each run with k threads. Time allowing (e.g. for a short benchmark), there
1196  // may be multiple such runs per benchmark, each run with its own
1197  // "setup"/"teardown".
1198  //
1199  // If the benchmark uses different size groups of threads (e.g. via
1200  // ThreadRange), the above will be true for each size group.
1201  //
1202  // The callback will be passed a State object, which includes the number
1203  // of threads, thread-index, benchmark arguments, etc.
1204  //
1205  // The callback must not be NULL or self-deleting.
1206  Benchmark* Setup(void (*setup)(const benchmark::State&));
1207  Benchmark* Teardown(void (*teardown)(const benchmark::State&));
1208 
1209  // Pass this benchmark object to *func, which can customize
1210  // the benchmark by calling various methods like Arg, Args,
1211  // Threads, etc.
1212  Benchmark* Apply(void (*func)(Benchmark* benchmark));
1213 
1214  // Set the range multiplier for non-dense range. If not called, the range
1215  // multiplier kRangeMultiplier will be used.
1216  Benchmark* RangeMultiplier(int multiplier);
1217 
1218  // Set the minimum amount of time to use when running this benchmark. This
1219  // option overrides the `benchmark_min_time` flag.
1220  // REQUIRES: `t > 0` and `Iterations` has not been called on this benchmark.
1221  Benchmark* MinTime(double t);
1222 
1223  // Set the minimum amount of time to run the benchmark before taking runtimes
1224  // of this benchmark into account. This
1225  // option overrides the `benchmark_min_warmup_time` flag.
1226  // REQUIRES: `t >= 0` and `Iterations` has not been called on this benchmark.
1227  Benchmark* MinWarmUpTime(double t);
1228 
1229  // Specify the amount of iterations that should be run by this benchmark.
1230  // This option overrides the `benchmark_min_time` flag.
1231  // REQUIRES: 'n > 0' and `MinTime` has not been called on this benchmark.
1232  //
1233  // NOTE: This function should only be used when *exact* iteration control is
1234  // needed and never to control or limit how long a benchmark runs, where
1235  // `--benchmark_min_time=<N>s` or `MinTime(...)` should be used instead.
1236  Benchmark* Iterations(IterationCount n);
1237 
1238  // Specify the amount of times to repeat this benchmark. This option overrides
1239  // the `benchmark_repetitions` flag.
1240  // REQUIRES: `n > 0`
1241  Benchmark* Repetitions(int n);
1242 
1243  // Specify if each repetition of the benchmark should be reported separately
1244  // or if only the final statistics should be reported. If the benchmark
1245  // is not repeated then the single result is always reported.
1246  // Applies to *ALL* reporters (display and file).
1247  Benchmark* ReportAggregatesOnly(bool value = true);
1248 
1249  // Same as ReportAggregatesOnly(), but applies to display reporter only.
1250  Benchmark* DisplayAggregatesOnly(bool value = true);
1251 
1252  // By default, the CPU time is measured only for the main thread, which may
1253  // be unrepresentative if the benchmark uses threads internally. If called,
1254  // the total CPU time spent by all the threads will be measured instead.
1255  // By default, only the main thread CPU time will be measured.
1256  Benchmark* MeasureProcessCPUTime();
1257 
1258  // If a particular benchmark should use the Wall clock instead of the CPU time
1259  // (be it either the CPU time of the main thread only (default), or the
1260  // total CPU usage of the benchmark), call this method. If called, the elapsed
1261  // (wall) time will be used to control how many iterations are run, and in the
1262  // printing of items/second or MB/seconds values.
1263  // If not called, the CPU time used by the benchmark will be used.
1264  Benchmark* UseRealTime();
1265 
1266  // If a benchmark must measure time manually (e.g. if GPU execution time is
1267  // being
1268  // measured), call this method. If called, each benchmark iteration should
1269  // call
1270  // SetIterationTime(seconds) to report the measured time, which will be used
1271  // to control how many iterations are run, and in the printing of items/second
1272  // or MB/second values.
1273  Benchmark* UseManualTime();
1274 
1275  // Set the asymptotic computational complexity for the benchmark. If called
1276  // the asymptotic computational complexity will be shown on the output.
1277  Benchmark* Complexity(BigO complexity = benchmark::oAuto);
1278 
1279  // Set the asymptotic computational complexity for the benchmark. If called
1280  // the asymptotic computational complexity will be shown on the output.
1281  Benchmark* Complexity(BigOFunc* complexity);
1282 
1283  // Add this statistics to be computed over all the values of benchmark run
1284  Benchmark* ComputeStatistics(const std::string& name,
1285  StatisticsFunc* statistics,
1286  StatisticUnit unit = kTime);
1287 
1288  // Support for running multiple copies of the same benchmark concurrently
1289  // in multiple threads. This may be useful when measuring the scaling
1290  // of some piece of code.
1291 
1292  // Run one instance of this benchmark concurrently in t threads.
1293  Benchmark* Threads(int t);
1294 
1295  // Pick a set of values T from [min_threads,max_threads].
1296  // min_threads and max_threads are always included in T. Run this
1297  // benchmark once for each value in T. The benchmark run for a
1298  // particular value t consists of t threads running the benchmark
1299  // function concurrently. For example, consider:
1300  // BENCHMARK(Foo)->ThreadRange(1,16);
1301  // This will run the following benchmarks:
1302  // Foo in 1 thread
1303  // Foo in 2 threads
1304  // Foo in 4 threads
1305  // Foo in 8 threads
1306  // Foo in 16 threads
1307  Benchmark* ThreadRange(int min_threads, int max_threads);
1308 
1309  // For each value n in the range, run this benchmark once using n threads.
1310  // min_threads and max_threads are always included in the range.
1311  // stride specifies the increment. E.g. DenseThreadRange(1, 8, 3) starts
1312  // a benchmark with 1, 4, 7 and 8 threads.
1313  Benchmark* DenseThreadRange(int min_threads, int max_threads, int stride = 1);
1314 
1315  // Equivalent to ThreadRange(NumCPUs(), NumCPUs())
1316  Benchmark* ThreadPerCpu();
1317 
1318  virtual void Run(State& state) = 0;
1319 
1320  TimeUnit GetTimeUnit() const;
1321 
1322  protected:
1323  explicit Benchmark(const std::string& name);
1324  void SetName(const std::string& name);
1325 
1326  public:
1327  const char* GetName() const;
1328  int ArgsCnt() const;
1329  const char* GetArgName(int arg) const;
1330 
1331  private:
1332  friend class BenchmarkFamilies;
1333  friend class BenchmarkInstance;
1334 
1335  std::string name_;
1336  AggregationReportMode aggregation_report_mode_;
1337  std::vector<std::string> arg_names_; // Args for all benchmark runs
1338  std::vector<std::vector<int64_t> > args_; // Args for all benchmark runs
1339 
1340  TimeUnit time_unit_;
1341  bool use_default_time_unit_;
1342 
1343  int range_multiplier_;
1344  double min_time_;
1345  double min_warmup_time_;
1346  IterationCount iterations_;
1347  int repetitions_;
1348  bool measure_process_cpu_time_;
1349  bool use_real_time_;
1350  bool use_manual_time_;
1351  BigO complexity_;
1352  BigOFunc* complexity_lambda_;
1353  std::vector<Statistics> statistics_;
1354  std::vector<int> thread_counts_;
1355 
1356  typedef void (*callback_function)(const benchmark::State&);
1357  callback_function setup_;
1358  callback_function teardown_;
1359 
1360  Benchmark(Benchmark const&)
1361 #if defined(BENCHMARK_HAS_CXX11)
1362  = delete
1363 #endif
1364  ;
1365 
1366  Benchmark& operator=(Benchmark const&)
1367 #if defined(BENCHMARK_HAS_CXX11)
1368  = delete
1369 #endif
1370  ;
1371 };
1372 
1373 } // namespace internal
1374 
1375 // Create and register a benchmark with the specified 'name' that invokes
1376 // the specified functor 'fn'.
1377 //
1378 // RETURNS: A pointer to the registered benchmark.
1379 internal::Benchmark* RegisterBenchmark(const std::string& name,
1380  internal::Function* fn);
1381 
1382 #if defined(BENCHMARK_HAS_CXX11)
1383 template <class Lambda>
1384 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn);
1385 #endif
1386 
1387 // Remove all registered benchmarks. All pointers to previously registered
1388 // benchmarks are invalidated.
1389 BENCHMARK_EXPORT void ClearRegisteredBenchmarks();
1390 
1391 namespace internal {
1392 // The class used to hold all Benchmarks created from static function.
1393 // (ie those created using the BENCHMARK(...) macros.
1394 class BENCHMARK_EXPORT FunctionBenchmark : public Benchmark {
1395  public:
1396  FunctionBenchmark(const std::string& name, Function* func)
1397  : Benchmark(name), func_(func) {}
1398 
1399  void Run(State& st) BENCHMARK_OVERRIDE;
1400 
1401  private:
1402  Function* func_;
1403 };
1404 
1405 #ifdef BENCHMARK_HAS_CXX11
1406 template <class Lambda>
1407 class LambdaBenchmark : public Benchmark {
1408  public:
1409  void Run(State& st) BENCHMARK_OVERRIDE { lambda_(st); }
1410 
1411  private:
1412  template <class OLambda>
1413  LambdaBenchmark(const std::string& name, OLambda&& lam)
1414  : Benchmark(name), lambda_(std::forward<OLambda>(lam)) {}
1415 
1416  LambdaBenchmark(LambdaBenchmark const&) = delete;
1417 
1418  template <class Lam> // NOLINTNEXTLINE(readability-redundant-declaration)
1419  friend Benchmark* ::benchmark::RegisterBenchmark(const std::string&, Lam&&);
1420 
1421  Lambda lambda_;
1422 };
1423 #endif
1424 } // namespace internal
1425 
1426 inline internal::Benchmark* RegisterBenchmark(const std::string& name,
1427  internal::Function* fn) {
1428  // FIXME: this should be a `std::make_unique<>()` but we don't have C++14.
1429  // codechecker_intentional [cplusplus.NewDeleteLeaks]
1430  return internal::RegisterBenchmarkInternal(
1431  ::new internal::FunctionBenchmark(name, fn));
1432 }
1433 
1434 #ifdef BENCHMARK_HAS_CXX11
1435 template <class Lambda>
1436 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn) {
1437  using BenchType =
1438  internal::LambdaBenchmark<typename std::decay<Lambda>::type>;
1439  // FIXME: this should be a `std::make_unique<>()` but we don't have C++14.
1440  // codechecker_intentional [cplusplus.NewDeleteLeaks]
1441  return internal::RegisterBenchmarkInternal(
1442  ::new BenchType(name, std::forward<Lambda>(fn)));
1443 }
1444 #endif
1445 
1446 #if defined(BENCHMARK_HAS_CXX11) && \
1447  (!defined(BENCHMARK_GCC_VERSION) || BENCHMARK_GCC_VERSION >= 409)
1448 template <class Lambda, class... Args>
1449 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn,
1450  Args&&... args) {
1451  return benchmark::RegisterBenchmark(
1452  name, [=](benchmark::State& st) { fn(st, args...); });
1453 }
1454 #else
1455 #define BENCHMARK_HAS_NO_VARIADIC_REGISTER_BENCHMARK
1456 #endif
1457 
1458 // The base class for all fixture tests.
1460  public:
1461  Fixture() : internal::Benchmark("") {}
1462 
1463  void Run(State& st) BENCHMARK_OVERRIDE {
1464  this->SetUp(st);
1465  this->BenchmarkCase(st);
1466  this->TearDown(st);
1467  }
1468 
1469  // These will be deprecated ...
1470  virtual void SetUp(const State&) {}
1471  virtual void TearDown(const State&) {}
1472  // ... In favor of these.
1473  virtual void SetUp(State& st) { SetUp(const_cast<const State&>(st)); }
1474  virtual void TearDown(State& st) { TearDown(const_cast<const State&>(st)); }
1475 
1476  protected:
1477  virtual void BenchmarkCase(State&) = 0;
1478 };
1479 } // namespace benchmark
1480 
1481 // ------------------------------------------------------
1482 // Macro to register benchmarks
1483 
1484 // Check that __COUNTER__ is defined and that __COUNTER__ increases by 1
1485 // every time it is expanded. X + 1 == X + 0 is used in case X is defined to be
1486 // empty. If X is empty the expression becomes (+1 == +0).
1487 #if defined(__COUNTER__) && (__COUNTER__ + 1 == __COUNTER__ + 0)
1488 #define BENCHMARK_PRIVATE_UNIQUE_ID __COUNTER__
1489 #else
1490 #define BENCHMARK_PRIVATE_UNIQUE_ID __LINE__
1491 #endif
1492 
1493 // Helpers for generating unique variable names
1494 #ifdef BENCHMARK_HAS_CXX11
1495 #define BENCHMARK_PRIVATE_NAME(...) \
1496  BENCHMARK_PRIVATE_CONCAT(benchmark_uniq_, BENCHMARK_PRIVATE_UNIQUE_ID, \
1497  __VA_ARGS__)
1498 #else
1499 #define BENCHMARK_PRIVATE_NAME(n) \
1500  BENCHMARK_PRIVATE_CONCAT(benchmark_uniq_, BENCHMARK_PRIVATE_UNIQUE_ID, n)
1501 #endif // BENCHMARK_HAS_CXX11
1502 
1503 #define BENCHMARK_PRIVATE_CONCAT(a, b, c) BENCHMARK_PRIVATE_CONCAT2(a, b, c)
1504 #define BENCHMARK_PRIVATE_CONCAT2(a, b, c) a##b##c
1505 // Helper for concatenation with macro name expansion
1506 #define BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method) \
1507  BaseClass##_##Method##_Benchmark
1508 
1509 #define BENCHMARK_PRIVATE_DECLARE(n) \
1510  static ::benchmark::internal::Benchmark* BENCHMARK_PRIVATE_NAME(n) \
1511  BENCHMARK_UNUSED
1512 
1513 #ifdef BENCHMARK_HAS_CXX11
1514 #define BENCHMARK(...) \
1515  BENCHMARK_PRIVATE_DECLARE(_benchmark_) = \
1516  (::benchmark::internal::RegisterBenchmarkInternal( \
1517  new ::benchmark::internal::FunctionBenchmark(#__VA_ARGS__, \
1518  __VA_ARGS__)))
1519 #else
1520 #define BENCHMARK(n) \
1521  BENCHMARK_PRIVATE_DECLARE(n) = \
1522  (::benchmark::internal::RegisterBenchmarkInternal( \
1523  new ::benchmark::internal::FunctionBenchmark(#n, n)))
1524 #endif // BENCHMARK_HAS_CXX11
1525 
1526 // Old-style macros
1527 #define BENCHMARK_WITH_ARG(n, a) BENCHMARK(n)->Arg((a))
1528 #define BENCHMARK_WITH_ARG2(n, a1, a2) BENCHMARK(n)->Args({(a1), (a2)})
1529 #define BENCHMARK_WITH_UNIT(n, t) BENCHMARK(n)->Unit((t))
1530 #define BENCHMARK_RANGE(n, lo, hi) BENCHMARK(n)->Range((lo), (hi))
1531 #define BENCHMARK_RANGE2(n, l1, h1, l2, h2) \
1532  BENCHMARK(n)->RangePair({{(l1), (h1)}, {(l2), (h2)}})
1533 
1534 #ifdef BENCHMARK_HAS_CXX11
1535 
1536 // Register a benchmark which invokes the function specified by `func`
1537 // with the additional arguments specified by `...`.
1538 //
1539 // For example:
1540 //
1541 // template <class ...ExtraArgs>`
1542 // void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
1543 // [...]
1544 //}
1545 // /* Registers a benchmark named "BM_takes_args/int_string_test` */
1546 // BENCHMARK_CAPTURE(BM_takes_args, int_string_test, 42, std::string("abc"));
1547 #define BENCHMARK_CAPTURE(func, test_case_name, ...) \
1548  BENCHMARK_PRIVATE_DECLARE(_benchmark_) = \
1549  (::benchmark::internal::RegisterBenchmarkInternal( \
1550  new ::benchmark::internal::FunctionBenchmark( \
1551  #func "/" #test_case_name, \
1552  [](::benchmark::State& st) { func(st, __VA_ARGS__); })))
1553 
1554 #endif // BENCHMARK_HAS_CXX11
1555 
1556 // This will register a benchmark for a templatized function. For example:
1557 //
1558 // template<int arg>
1559 // void BM_Foo(int iters);
1560 //
1561 // BENCHMARK_TEMPLATE(BM_Foo, 1);
1562 //
1563 // will register BM_Foo<1> as a benchmark.
1564 #define BENCHMARK_TEMPLATE1(n, a) \
1565  BENCHMARK_PRIVATE_DECLARE(n) = \
1566  (::benchmark::internal::RegisterBenchmarkInternal( \
1567  new ::benchmark::internal::FunctionBenchmark(#n "<" #a ">", n<a>)))
1568 
1569 #define BENCHMARK_TEMPLATE2(n, a, b) \
1570  BENCHMARK_PRIVATE_DECLARE(n) = \
1571  (::benchmark::internal::RegisterBenchmarkInternal( \
1572  new ::benchmark::internal::FunctionBenchmark(#n "<" #a "," #b ">", \
1573  n<a, b>)))
1574 
1575 #ifdef BENCHMARK_HAS_CXX11
1576 #define BENCHMARK_TEMPLATE(n, ...) \
1577  BENCHMARK_PRIVATE_DECLARE(n) = \
1578  (::benchmark::internal::RegisterBenchmarkInternal( \
1579  new ::benchmark::internal::FunctionBenchmark( \
1580  #n "<" #__VA_ARGS__ ">", n<__VA_ARGS__>)))
1581 #else
1582 #define BENCHMARK_TEMPLATE(n, a) BENCHMARK_TEMPLATE1(n, a)
1583 #endif
1584 
1585 #ifdef BENCHMARK_HAS_CXX11
1586 // This will register a benchmark for a templatized function,
1587 // with the additional arguments specified by `...`.
1588 //
1589 // For example:
1590 //
1591 // template <typename T, class ...ExtraArgs>`
1592 // void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
1593 // [...]
1594 //}
1595 // /* Registers a benchmark named "BM_takes_args<void>/int_string_test` */
1596 // BENCHMARK_TEMPLATE1_CAPTURE(BM_takes_args, void, int_string_test, 42,
1597 // std::string("abc"));
1598 #define BENCHMARK_TEMPLATE1_CAPTURE(func, a, test_case_name, ...) \
1599  BENCHMARK_CAPTURE(func<a>, test_case_name, __VA_ARGS__)
1600 
1601 #define BENCHMARK_TEMPLATE2_CAPTURE(func, a, b, test_case_name, ...) \
1602  BENCHMARK_PRIVATE_DECLARE(func) = \
1603  (::benchmark::internal::RegisterBenchmarkInternal( \
1604  new ::benchmark::internal::FunctionBenchmark( \
1605  #func "<" #a "," #b ">" \
1606  "/" #test_case_name, \
1607  [](::benchmark::State& st) { func<a, b>(st, __VA_ARGS__); })))
1608 #endif // BENCHMARK_HAS_CXX11
1609 
1610 #define BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1611  class BaseClass##_##Method##_Benchmark : public BaseClass { \
1612  public: \
1613  BaseClass##_##Method##_Benchmark() { \
1614  this->SetName(#BaseClass "/" #Method); \
1615  } \
1616  \
1617  protected: \
1618  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1619  };
1620 
1621 #define BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1622  class BaseClass##_##Method##_Benchmark : public BaseClass<a> { \
1623  public: \
1624  BaseClass##_##Method##_Benchmark() { \
1625  this->SetName(#BaseClass "<" #a ">/" #Method); \
1626  } \
1627  \
1628  protected: \
1629  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1630  };
1631 
1632 #define BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1633  class BaseClass##_##Method##_Benchmark : public BaseClass<a, b> { \
1634  public: \
1635  BaseClass##_##Method##_Benchmark() { \
1636  this->SetName(#BaseClass "<" #a "," #b ">/" #Method); \
1637  } \
1638  \
1639  protected: \
1640  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1641  };
1642 
1643 #ifdef BENCHMARK_HAS_CXX11
1644 #define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, ...) \
1645  class BaseClass##_##Method##_Benchmark : public BaseClass<__VA_ARGS__> { \
1646  public: \
1647  BaseClass##_##Method##_Benchmark() { \
1648  this->SetName(#BaseClass "<" #__VA_ARGS__ ">/" #Method); \
1649  } \
1650  \
1651  protected: \
1652  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1653  };
1654 #else
1655 #define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(n, a) \
1656  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(n, a)
1657 #endif
1658 
1659 #define BENCHMARK_DEFINE_F(BaseClass, Method) \
1660  BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1661  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1662 
1663 #define BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a) \
1664  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1665  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1666 
1667 #define BENCHMARK_TEMPLATE2_DEFINE_F(BaseClass, Method, a, b) \
1668  BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1669  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1670 
1671 #ifdef BENCHMARK_HAS_CXX11
1672 #define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, ...) \
1673  BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1674  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1675 #else
1676 #define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, a) \
1677  BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a)
1678 #endif
1679 
1680 #define BENCHMARK_REGISTER_F(BaseClass, Method) \
1681  BENCHMARK_PRIVATE_REGISTER_F(BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method))
1682 
1683 #define BENCHMARK_PRIVATE_REGISTER_F(TestName) \
1684  BENCHMARK_PRIVATE_DECLARE(TestName) = \
1685  (::benchmark::internal::RegisterBenchmarkInternal(new TestName()))
1686 
1687 // This macro will define and register a benchmark within a fixture class.
1688 #define BENCHMARK_F(BaseClass, Method) \
1689  BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1690  BENCHMARK_REGISTER_F(BaseClass, Method); \
1691  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1692 
1693 #define BENCHMARK_TEMPLATE1_F(BaseClass, Method, a) \
1694  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1695  BENCHMARK_REGISTER_F(BaseClass, Method); \
1696  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1697 
1698 #define BENCHMARK_TEMPLATE2_F(BaseClass, Method, a, b) \
1699  BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1700  BENCHMARK_REGISTER_F(BaseClass, Method); \
1701  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1702 
1703 #ifdef BENCHMARK_HAS_CXX11
1704 #define BENCHMARK_TEMPLATE_F(BaseClass, Method, ...) \
1705  BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1706  BENCHMARK_REGISTER_F(BaseClass, Method); \
1707  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1708 #else
1709 #define BENCHMARK_TEMPLATE_F(BaseClass, Method, a) \
1710  BENCHMARK_TEMPLATE1_F(BaseClass, Method, a)
1711 #endif
1712 
1713 // Helper macro to create a main routine in a test that runs the benchmarks
1714 // Note the workaround for Hexagon simulator passing argc != 0, argv = NULL.
1715 #define BENCHMARK_MAIN() \
1716  int main(int argc, char** argv) { \
1717  char arg0_default[] = "benchmark"; \
1718  char* args_default = arg0_default; \
1719  if (!argv) { \
1720  argc = 1; \
1721  argv = &args_default; \
1722  } \
1723  ::benchmark::Initialize(&argc, argv); \
1724  if (::benchmark::ReportUnrecognizedArguments(argc, argv)) return 1; \
1725  ::benchmark::RunSpecifiedBenchmarks(); \
1726  ::benchmark::Shutdown(); \
1727  return 0; \
1728  } \
1729  int main(int, char**)
1730 
1731 // ------------------------------------------------------
1732 // Benchmark Reporters
1733 
1734 namespace benchmark {
1735 
1736 struct BENCHMARK_EXPORT CPUInfo {
1737  struct CacheInfo {
1738  std::string type;
1739  int level;
1740  int size;
1741  int num_sharing;
1742  };
1743 
1744  enum Scaling { UNKNOWN, ENABLED, DISABLED };
1745 
1746  int num_cpus;
1747  Scaling scaling;
1748  double cycles_per_second;
1749  std::vector<CacheInfo> caches;
1750  std::vector<double> load_avg;
1751 
1752  static const CPUInfo& Get();
1753 
1754  private:
1755  CPUInfo();
1756  BENCHMARK_DISALLOW_COPY_AND_ASSIGN(CPUInfo);
1757 };
1758 
1759 // Adding Struct for System Information
1760 struct BENCHMARK_EXPORT SystemInfo {
1761  std::string name;
1762  static const SystemInfo& Get();
1763 
1764  private:
1765  SystemInfo();
1766  BENCHMARK_DISALLOW_COPY_AND_ASSIGN(SystemInfo);
1767 };
1768 
1769 // BenchmarkName contains the components of the Benchmark's name
1770 // which allows individual fields to be modified or cleared before
1771 // building the final name using 'str()'.
1772 struct BENCHMARK_EXPORT BenchmarkName {
1773  std::string function_name;
1774  std::string args;
1775  std::string min_time;
1776  std::string min_warmup_time;
1777  std::string iterations;
1778  std::string repetitions;
1779  std::string time_type;
1780  std::string threads;
1781 
1782  // Return the full name of the benchmark with each non-empty
1783  // field separated by a '/'
1784  std::string str() const;
1785 };
1786 
1787 // Interface for custom benchmark result printers.
1788 // By default, benchmark reports are printed to stdout. However an application
1789 // can control the destination of the reports by calling
1790 // RunSpecifiedBenchmarks and passing it a custom reporter object.
1791 // The reporter object must implement the following interface.
1792 class BENCHMARK_EXPORT BenchmarkReporter {
1793  public:
1794  struct Context {
1795  CPUInfo const& cpu_info;
1796  SystemInfo const& sys_info;
1797  // The number of chars in the longest benchmark name.
1798  size_t name_field_width;
1799  static const char* executable_name;
1800  Context();
1801  };
1802 
1803  struct BENCHMARK_EXPORT Run {
1804  static const int64_t no_repetition_index = -1;
1805  enum RunType { RT_Iteration, RT_Aggregate };
1806 
1807  Run()
1808  : run_type(RT_Iteration),
1809  aggregate_unit(kTime),
1810  skipped(internal::NotSkipped),
1811  iterations(1),
1812  threads(1),
1813  time_unit(GetDefaultTimeUnit()),
1814  real_accumulated_time(0),
1815  cpu_accumulated_time(0),
1816  max_heapbytes_used(0),
1817  use_real_time_for_initial_big_o(false),
1818  complexity(oNone),
1819  complexity_lambda(),
1820  complexity_n(0),
1821  report_big_o(false),
1822  report_rms(false),
1823  memory_result(NULL),
1824  allocs_per_iter(0.0) {}
1825 
1826  std::string benchmark_name() const;
1827  BenchmarkName run_name;
1828  int64_t family_index;
1829  int64_t per_family_instance_index;
1830  RunType run_type;
1831  std::string aggregate_name;
1832  StatisticUnit aggregate_unit;
1833  std::string report_label; // Empty if not set by benchmark.
1834  internal::Skipped skipped;
1835  std::string skip_message;
1836 
1837  IterationCount iterations;
1838  int64_t threads;
1839  int64_t repetition_index;
1840  int64_t repetitions;
1841  TimeUnit time_unit;
1842  double real_accumulated_time;
1843  double cpu_accumulated_time;
1844 
1845  // Return a value representing the real time per iteration in the unit
1846  // specified by 'time_unit'.
1847  // NOTE: If 'iterations' is zero the returned value represents the
1848  // accumulated time.
1849  double GetAdjustedRealTime() const;
1850 
1851  // Return a value representing the cpu time per iteration in the unit
1852  // specified by 'time_unit'.
1853  // NOTE: If 'iterations' is zero the returned value represents the
1854  // accumulated time.
1855  double GetAdjustedCPUTime() const;
1856 
1857  // This is set to 0.0 if memory tracing is not enabled.
1858  double max_heapbytes_used;
1859 
1860  // By default Big-O is computed for CPU time, but that is not what you want
1861  // to happen when manual time was requested, which is stored as real time.
1862  bool use_real_time_for_initial_big_o;
1863 
1864  // Keep track of arguments to compute asymptotic complexity
1865  BigO complexity;
1866  BigOFunc* complexity_lambda;
1867  ComplexityN complexity_n;
1868 
1869  // what statistics to compute from the measurements
1870  const std::vector<internal::Statistics>* statistics;
1871 
1872  // Inform print function whether the current run is a complexity report
1873  bool report_big_o;
1874  bool report_rms;
1875 
1876  UserCounters counters;
1877 
1878  // Memory metrics.
1879  const MemoryManager::Result* memory_result;
1880  double allocs_per_iter;
1881  };
1882 
1884  PerFamilyRunReports() : num_runs_total(0), num_runs_done(0) {}
1885 
1886  // How many runs will all instances of this benchmark perform?
1887  int num_runs_total;
1888 
1889  // How many runs have happened already?
1890  int num_runs_done;
1891 
1892  // The reports about (non-errneous!) runs of this family.
1893  std::vector<BenchmarkReporter::Run> Runs;
1894  };
1895 
1896  // Construct a BenchmarkReporter with the output stream set to 'std::cout'
1897  // and the error stream set to 'std::cerr'
1899 
1900  // Called once for every suite of benchmarks run.
1901  // The parameter "context" contains information that the
1902  // reporter may wish to use when generating its report, for example the
1903  // platform under which the benchmarks are running. The benchmark run is
1904  // never started if this function returns false, allowing the reporter
1905  // to skip runs based on the context information.
1906  virtual bool ReportContext(const Context& context) = 0;
1907 
1908  // Called once for each group of benchmark runs, gives information about
1909  // the configurations of the runs.
1910  virtual void ReportRunsConfig(double /*min_time*/,
1911  bool /*has_explicit_iters*/,
1912  IterationCount /*iters*/) {}
1913 
1914  // Called once for each group of benchmark runs, gives information about
1915  // cpu-time and heap memory usage during the benchmark run. If the group
1916  // of runs contained more than two entries then 'report' contains additional
1917  // elements representing the mean and standard deviation of those runs.
1918  // Additionally if this group of runs was the last in a family of benchmarks
1919  // 'reports' contains additional entries representing the asymptotic
1920  // complexity and RMS of that benchmark family.
1921  virtual void ReportRuns(const std::vector<Run>& report) = 0;
1922 
1923  // Called once and only once after ever group of benchmarks is run and
1924  // reported.
1925  virtual void Finalize() {}
1926 
1927  // REQUIRES: The object referenced by 'out' is valid for the lifetime
1928  // of the reporter.
1929  void SetOutputStream(std::ostream* out) {
1930  assert(out);
1931  output_stream_ = out;
1932  }
1933 
1934  // REQUIRES: The object referenced by 'err' is valid for the lifetime
1935  // of the reporter.
1936  void SetErrorStream(std::ostream* err) {
1937  assert(err);
1938  error_stream_ = err;
1939  }
1940 
1941  std::ostream& GetOutputStream() const { return *output_stream_; }
1942 
1943  std::ostream& GetErrorStream() const { return *error_stream_; }
1944 
1945  virtual ~BenchmarkReporter();
1946 
1947  // Write a human readable string to 'out' representing the specified
1948  // 'context'.
1949  // REQUIRES: 'out' is non-null.
1950  static void PrintBasicContext(std::ostream* out, Context const& context);
1951 
1952  private:
1953  std::ostream* output_stream_;
1954  std::ostream* error_stream_;
1955 };
1956 
1957 // Simple reporter that outputs benchmark data to the console. This is the
1958 // default reporter used by RunSpecifiedBenchmarks().
1959 class BENCHMARK_EXPORT ConsoleReporter : public BenchmarkReporter {
1960  public:
1961  enum OutputOptions {
1962  OO_None = 0,
1963  OO_Color = 1,
1964  OO_Tabular = 2,
1965  OO_ColorTabular = OO_Color | OO_Tabular,
1966  OO_Defaults = OO_ColorTabular
1967  };
1968  explicit ConsoleReporter(OutputOptions opts_ = OO_Defaults)
1969  : output_options_(opts_), name_field_width_(0), printed_header_(false) {}
1970 
1971  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
1972  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
1973 
1974  protected:
1975  virtual void PrintRunData(const Run& report);
1976  virtual void PrintHeader(const Run& report);
1977 
1978  OutputOptions output_options_;
1979  size_t name_field_width_;
1980  UserCounters prev_counters_;
1981  bool printed_header_;
1982 };
1983 
1984 class BENCHMARK_EXPORT JSONReporter : public BenchmarkReporter {
1985  public:
1986  JSONReporter() : first_report_(true) {}
1987  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
1988  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
1989  void Finalize() BENCHMARK_OVERRIDE;
1990 
1991  private:
1992  void PrintRunData(const Run& report);
1993 
1994  bool first_report_;
1995 };
1996 
1997 class BENCHMARK_EXPORT BENCHMARK_DEPRECATED_MSG(
1998  "The CSV Reporter will be removed in a future release") CSVReporter
1999  : public BenchmarkReporter {
2000  public:
2001  CSVReporter() : printed_header_(false) {}
2002  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
2003  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
2004 
2005  private:
2006  void PrintRunData(const Run& report);
2007 
2008  bool printed_header_;
2009  std::set<std::string> user_counter_names_;
2010 };
2011 
2012 inline const char* GetTimeUnitString(TimeUnit unit) {
2013  switch (unit) {
2014  case kSecond:
2015  return "s";
2016  case kMillisecond:
2017  return "ms";
2018  case kMicrosecond:
2019  return "us";
2020  case kNanosecond:
2021  return "ns";
2022  }
2023  BENCHMARK_UNREACHABLE();
2024 }
2025 
2026 inline double GetTimeUnitMultiplier(TimeUnit unit) {
2027  switch (unit) {
2028  case kSecond:
2029  return 1;
2030  case kMillisecond:
2031  return 1e3;
2032  case kMicrosecond:
2033  return 1e6;
2034  case kNanosecond:
2035  return 1e9;
2036  }
2037  BENCHMARK_UNREACHABLE();
2038 }
2039 
2040 // Creates a list of integer values for the given range and multiplier.
2041 // This can be used together with ArgsProduct() to allow multiple ranges
2042 // with different multipliers.
2043 // Example:
2044 // ArgsProduct({
2045 // CreateRange(0, 1024, /*multi=*/32),
2046 // CreateRange(0, 100, /*multi=*/4),
2047 // CreateDenseRange(0, 4, /*step=*/1),
2048 // });
2049 BENCHMARK_EXPORT
2050 std::vector<int64_t> CreateRange(int64_t lo, int64_t hi, int multi);
2051 
2052 // Creates a list of integer values for the given range and step.
2053 BENCHMARK_EXPORT
2054 std::vector<int64_t> CreateDenseRange(int64_t start, int64_t limit, int step);
2055 
2056 } // namespace benchmark
2057 
2058 #if defined(_MSC_VER)
2059 #pragma warning(pop)
2060 #endif
2061 
2062 #endif // BENCHMARK_BENCHMARK_H_
Definition: benchmark.h:1792
Definition: benchmark.h:1959
Definition: benchmark.h:633
Definition: benchmark.h:1459
Definition: benchmark.h:1984
Definition: benchmark.h:378
Definition: benchmark.h:422
Definition: benchmark.h:762
Definition: benchmark_register.cc:73
Definition: benchmark_api_internal.h:18
Definition: benchmark.h:1122
Definition: benchmark.h:1394
Definition: perf_counters.h:149
Definition: thread_manager.h:12
Definition: thread_timer.h:10
Definition: benchmark.h:1772
Definition: benchmark.h:1794
Definition: benchmark.h:1803
Definition: benchmark.h:1737
Definition: benchmark.h:1736
Definition: benchmark.h:382
Definition: benchmark.h:1065
Definition: benchmark.h:1064
Definition: benchmark.h:1760
Definition: benchmark.h:713