benchmark  1.8.5
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 
1009  void StartKeepRunning();
1010  // Implementation of KeepRunning() and KeepRunningBatch().
1011  // is_batch must be true unless n is 1.
1012  inline bool KeepRunningInternal(IterationCount n, bool is_batch);
1013  void FinishKeepRunning();
1014 
1015  const std::string name_;
1016  const int thread_index_;
1017  const int threads_;
1018 
1019  internal::ThreadTimer* const timer_;
1020  internal::ThreadManager* const manager_;
1021  internal::PerfCountersMeasurement* const perf_counters_measurement_;
1022 
1023  friend class internal::BenchmarkInstance;
1024 };
1025 
1026 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunning() {
1027  return KeepRunningInternal(1, /*is_batch=*/false);
1028 }
1029 
1030 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningBatch(IterationCount n) {
1031  return KeepRunningInternal(n, /*is_batch=*/true);
1032 }
1033 
1034 inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningInternal(IterationCount n,
1035  bool is_batch) {
1036  // total_iterations_ is set to 0 by the constructor, and always set to a
1037  // nonzero value by StartKepRunning().
1038  assert(n > 0);
1039  // n must be 1 unless is_batch is true.
1040  assert(is_batch || n == 1);
1041  if (BENCHMARK_BUILTIN_EXPECT(total_iterations_ >= n, true)) {
1042  total_iterations_ -= n;
1043  return true;
1044  }
1045  if (!started_) {
1046  StartKeepRunning();
1047  if (!skipped() && total_iterations_ >= n) {
1048  total_iterations_ -= n;
1049  return true;
1050  }
1051  }
1052  // For non-batch runs, total_iterations_ must be 0 by now.
1053  if (is_batch && total_iterations_ != 0) {
1054  batch_leftover_ = n - total_iterations_;
1055  total_iterations_ = 0;
1056  return true;
1057  }
1058  FinishKeepRunning();
1059  return false;
1060 }
1061 
1063  struct BENCHMARK_UNUSED Value {};
1064  typedef std::forward_iterator_tag iterator_category;
1065  typedef Value value_type;
1066  typedef Value reference;
1067  typedef Value pointer;
1068  typedef std::ptrdiff_t difference_type;
1069 
1070  private:
1071  friend class State;
1072  BENCHMARK_ALWAYS_INLINE
1073  StateIterator() : cached_(0), parent_() {}
1074 
1075  BENCHMARK_ALWAYS_INLINE
1076  explicit StateIterator(State* st)
1077  : cached_(st->skipped() ? 0 : st->max_iterations), parent_(st) {}
1078 
1079  public:
1080  BENCHMARK_ALWAYS_INLINE
1081  Value operator*() const { return Value(); }
1082 
1083  BENCHMARK_ALWAYS_INLINE
1084  StateIterator& operator++() {
1085  assert(cached_ > 0);
1086  --cached_;
1087  return *this;
1088  }
1089 
1090  BENCHMARK_ALWAYS_INLINE
1091  bool operator!=(StateIterator const&) const {
1092  if (BENCHMARK_BUILTIN_EXPECT(cached_ != 0, true)) return true;
1093  parent_->FinishKeepRunning();
1094  return false;
1095  }
1096 
1097  private:
1098  IterationCount cached_;
1099  State* const parent_;
1100 };
1101 
1102 inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::begin() {
1103  return StateIterator(this);
1104 }
1105 inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::end() {
1106  StartKeepRunning();
1107  return StateIterator();
1108 }
1109 
1110 namespace internal {
1111 
1112 typedef void(Function)(State&);
1113 
1114 // ------------------------------------------------------
1115 // Benchmark registration object. The BENCHMARK() macro expands
1116 // into an internal::Benchmark* object. Various methods can
1117 // be called on this object to change the properties of the benchmark.
1118 // Each method returns "this" so that multiple method calls can
1119 // chained into one expression.
1120 class BENCHMARK_EXPORT Benchmark {
1121  public:
1122  virtual ~Benchmark();
1123 
1124  // Note: the following methods all return "this" so that multiple
1125  // method calls can be chained together in one expression.
1126 
1127  // Specify the name of the benchmark
1128  Benchmark* Name(const std::string& name);
1129 
1130  // Run this benchmark once with "x" as the extra argument passed
1131  // to the function.
1132  // REQUIRES: The function passed to the constructor must accept an arg1.
1133  Benchmark* Arg(int64_t x);
1134 
1135  // Run this benchmark with the given time unit for the generated output report
1136  Benchmark* Unit(TimeUnit unit);
1137 
1138  // Run this benchmark once for a number of values picked from the
1139  // range [start..limit]. (start and limit are always picked.)
1140  // REQUIRES: The function passed to the constructor must accept an arg1.
1141  Benchmark* Range(int64_t start, int64_t limit);
1142 
1143  // Run this benchmark once for all values in the range [start..limit] with
1144  // specific step
1145  // REQUIRES: The function passed to the constructor must accept an arg1.
1146  Benchmark* DenseRange(int64_t start, int64_t limit, int step = 1);
1147 
1148  // Run this benchmark once with "args" as the extra arguments passed
1149  // to the function.
1150  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1151  Benchmark* Args(const std::vector<int64_t>& args);
1152 
1153  // Equivalent to Args({x, y})
1154  // NOTE: This is a legacy C++03 interface provided for compatibility only.
1155  // New code should use 'Args'.
1156  Benchmark* ArgPair(int64_t x, int64_t y) {
1157  std::vector<int64_t> args;
1158  args.push_back(x);
1159  args.push_back(y);
1160  return Args(args);
1161  }
1162 
1163  // Run this benchmark once for a number of values picked from the
1164  // ranges [start..limit]. (starts and limits are always picked.)
1165  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1166  Benchmark* Ranges(const std::vector<std::pair<int64_t, int64_t> >& ranges);
1167 
1168  // Run this benchmark once for each combination of values in the (cartesian)
1169  // product of the supplied argument lists.
1170  // REQUIRES: The function passed to the constructor must accept arg1, arg2 ...
1171  Benchmark* ArgsProduct(const std::vector<std::vector<int64_t> >& arglists);
1172 
1173  // Equivalent to ArgNames({name})
1174  Benchmark* ArgName(const std::string& name);
1175 
1176  // Set the argument names to display in the benchmark name. If not called,
1177  // only argument values will be shown.
1178  Benchmark* ArgNames(const std::vector<std::string>& names);
1179 
1180  // Equivalent to Ranges({{lo1, hi1}, {lo2, hi2}}).
1181  // NOTE: This is a legacy C++03 interface provided for compatibility only.
1182  // New code should use 'Ranges'.
1183  Benchmark* RangePair(int64_t lo1, int64_t hi1, int64_t lo2, int64_t hi2) {
1184  std::vector<std::pair<int64_t, int64_t> > ranges;
1185  ranges.push_back(std::make_pair(lo1, hi1));
1186  ranges.push_back(std::make_pair(lo2, hi2));
1187  return Ranges(ranges);
1188  }
1189 
1190  // Have "setup" and/or "teardown" invoked once for every benchmark run.
1191  // If the benchmark is multi-threaded (will run in k threads concurrently),
1192  // the setup callback will be be invoked exactly once (not k times) before
1193  // each run with k threads. Time allowing (e.g. for a short benchmark), there
1194  // may be multiple such runs per benchmark, each run with its own
1195  // "setup"/"teardown".
1196  //
1197  // If the benchmark uses different size groups of threads (e.g. via
1198  // ThreadRange), the above will be true for each size group.
1199  //
1200  // The callback will be passed a State object, which includes the number
1201  // of threads, thread-index, benchmark arguments, etc.
1202  //
1203  // The callback must not be NULL or self-deleting.
1204  Benchmark* Setup(void (*setup)(const benchmark::State&));
1205  Benchmark* Teardown(void (*teardown)(const benchmark::State&));
1206 
1207  // Pass this benchmark object to *func, which can customize
1208  // the benchmark by calling various methods like Arg, Args,
1209  // Threads, etc.
1210  Benchmark* Apply(void (*func)(Benchmark* benchmark));
1211 
1212  // Set the range multiplier for non-dense range. If not called, the range
1213  // multiplier kRangeMultiplier will be used.
1214  Benchmark* RangeMultiplier(int multiplier);
1215 
1216  // Set the minimum amount of time to use when running this benchmark. This
1217  // option overrides the `benchmark_min_time` flag.
1218  // REQUIRES: `t > 0` and `Iterations` has not been called on this benchmark.
1219  Benchmark* MinTime(double t);
1220 
1221  // Set the minimum amount of time to run the benchmark before taking runtimes
1222  // of this benchmark into account. This
1223  // option overrides the `benchmark_min_warmup_time` flag.
1224  // REQUIRES: `t >= 0` and `Iterations` has not been called on this benchmark.
1225  Benchmark* MinWarmUpTime(double t);
1226 
1227  // Specify the amount of iterations that should be run by this benchmark.
1228  // This option overrides the `benchmark_min_time` flag.
1229  // REQUIRES: 'n > 0' and `MinTime` has not been called on this benchmark.
1230  //
1231  // NOTE: This function should only be used when *exact* iteration control is
1232  // needed and never to control or limit how long a benchmark runs, where
1233  // `--benchmark_min_time=<N>s` or `MinTime(...)` should be used instead.
1234  Benchmark* Iterations(IterationCount n);
1235 
1236  // Specify the amount of times to repeat this benchmark. This option overrides
1237  // the `benchmark_repetitions` flag.
1238  // REQUIRES: `n > 0`
1239  Benchmark* Repetitions(int n);
1240 
1241  // Specify if each repetition of the benchmark should be reported separately
1242  // or if only the final statistics should be reported. If the benchmark
1243  // is not repeated then the single result is always reported.
1244  // Applies to *ALL* reporters (display and file).
1245  Benchmark* ReportAggregatesOnly(bool value = true);
1246 
1247  // Same as ReportAggregatesOnly(), but applies to display reporter only.
1248  Benchmark* DisplayAggregatesOnly(bool value = true);
1249 
1250  // By default, the CPU time is measured only for the main thread, which may
1251  // be unrepresentative if the benchmark uses threads internally. If called,
1252  // the total CPU time spent by all the threads will be measured instead.
1253  // By default, only the main thread CPU time will be measured.
1254  Benchmark* MeasureProcessCPUTime();
1255 
1256  // If a particular benchmark should use the Wall clock instead of the CPU time
1257  // (be it either the CPU time of the main thread only (default), or the
1258  // total CPU usage of the benchmark), call this method. If called, the elapsed
1259  // (wall) time will be used to control how many iterations are run, and in the
1260  // printing of items/second or MB/seconds values.
1261  // If not called, the CPU time used by the benchmark will be used.
1262  Benchmark* UseRealTime();
1263 
1264  // If a benchmark must measure time manually (e.g. if GPU execution time is
1265  // being
1266  // measured), call this method. If called, each benchmark iteration should
1267  // call
1268  // SetIterationTime(seconds) to report the measured time, which will be used
1269  // to control how many iterations are run, and in the printing of items/second
1270  // or MB/second values.
1271  Benchmark* UseManualTime();
1272 
1273  // Set the asymptotic computational complexity for the benchmark. If called
1274  // the asymptotic computational complexity will be shown on the output.
1275  Benchmark* Complexity(BigO complexity = benchmark::oAuto);
1276 
1277  // Set the asymptotic computational complexity for the benchmark. If called
1278  // the asymptotic computational complexity will be shown on the output.
1279  Benchmark* Complexity(BigOFunc* complexity);
1280 
1281  // Add this statistics to be computed over all the values of benchmark run
1282  Benchmark* ComputeStatistics(const std::string& name,
1283  StatisticsFunc* statistics,
1284  StatisticUnit unit = kTime);
1285 
1286  // Support for running multiple copies of the same benchmark concurrently
1287  // in multiple threads. This may be useful when measuring the scaling
1288  // of some piece of code.
1289 
1290  // Run one instance of this benchmark concurrently in t threads.
1291  Benchmark* Threads(int t);
1292 
1293  // Pick a set of values T from [min_threads,max_threads].
1294  // min_threads and max_threads are always included in T. Run this
1295  // benchmark once for each value in T. The benchmark run for a
1296  // particular value t consists of t threads running the benchmark
1297  // function concurrently. For example, consider:
1298  // BENCHMARK(Foo)->ThreadRange(1,16);
1299  // This will run the following benchmarks:
1300  // Foo in 1 thread
1301  // Foo in 2 threads
1302  // Foo in 4 threads
1303  // Foo in 8 threads
1304  // Foo in 16 threads
1305  Benchmark* ThreadRange(int min_threads, int max_threads);
1306 
1307  // For each value n in the range, run this benchmark once using n threads.
1308  // min_threads and max_threads are always included in the range.
1309  // stride specifies the increment. E.g. DenseThreadRange(1, 8, 3) starts
1310  // a benchmark with 1, 4, 7 and 8 threads.
1311  Benchmark* DenseThreadRange(int min_threads, int max_threads, int stride = 1);
1312 
1313  // Equivalent to ThreadRange(NumCPUs(), NumCPUs())
1314  Benchmark* ThreadPerCpu();
1315 
1316  virtual void Run(State& state) = 0;
1317 
1318  TimeUnit GetTimeUnit() const;
1319 
1320  protected:
1321  explicit Benchmark(const std::string& name);
1322  void SetName(const std::string& name);
1323 
1324  public:
1325  const char* GetName() const;
1326  int ArgsCnt() const;
1327  const char* GetArgName(int arg) const;
1328 
1329  private:
1330  friend class BenchmarkFamilies;
1331  friend class BenchmarkInstance;
1332 
1333  std::string name_;
1334  AggregationReportMode aggregation_report_mode_;
1335  std::vector<std::string> arg_names_; // Args for all benchmark runs
1336  std::vector<std::vector<int64_t> > args_; // Args for all benchmark runs
1337 
1338  TimeUnit time_unit_;
1339  bool use_default_time_unit_;
1340 
1341  int range_multiplier_;
1342  double min_time_;
1343  double min_warmup_time_;
1344  IterationCount iterations_;
1345  int repetitions_;
1346  bool measure_process_cpu_time_;
1347  bool use_real_time_;
1348  bool use_manual_time_;
1349  BigO complexity_;
1350  BigOFunc* complexity_lambda_;
1351  std::vector<Statistics> statistics_;
1352  std::vector<int> thread_counts_;
1353 
1354  typedef void (*callback_function)(const benchmark::State&);
1355  callback_function setup_;
1356  callback_function teardown_;
1357 
1358  Benchmark(Benchmark const&)
1359 #if defined(BENCHMARK_HAS_CXX11)
1360  = delete
1361 #endif
1362  ;
1363 
1364  Benchmark& operator=(Benchmark const&)
1365 #if defined(BENCHMARK_HAS_CXX11)
1366  = delete
1367 #endif
1368  ;
1369 };
1370 
1371 } // namespace internal
1372 
1373 // Create and register a benchmark with the specified 'name' that invokes
1374 // the specified functor 'fn'.
1375 //
1376 // RETURNS: A pointer to the registered benchmark.
1377 internal::Benchmark* RegisterBenchmark(const std::string& name,
1378  internal::Function* fn);
1379 
1380 #if defined(BENCHMARK_HAS_CXX11)
1381 template <class Lambda>
1382 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn);
1383 #endif
1384 
1385 // Remove all registered benchmarks. All pointers to previously registered
1386 // benchmarks are invalidated.
1387 BENCHMARK_EXPORT void ClearRegisteredBenchmarks();
1388 
1389 namespace internal {
1390 // The class used to hold all Benchmarks created from static function.
1391 // (ie those created using the BENCHMARK(...) macros.
1392 class BENCHMARK_EXPORT FunctionBenchmark : public Benchmark {
1393  public:
1394  FunctionBenchmark(const std::string& name, Function* func)
1395  : Benchmark(name), func_(func) {}
1396 
1397  void Run(State& st) BENCHMARK_OVERRIDE;
1398 
1399  private:
1400  Function* func_;
1401 };
1402 
1403 #ifdef BENCHMARK_HAS_CXX11
1404 template <class Lambda>
1405 class LambdaBenchmark : public Benchmark {
1406  public:
1407  void Run(State& st) BENCHMARK_OVERRIDE { lambda_(st); }
1408 
1409  private:
1410  template <class OLambda>
1411  LambdaBenchmark(const std::string& name, OLambda&& lam)
1412  : Benchmark(name), lambda_(std::forward<OLambda>(lam)) {}
1413 
1414  LambdaBenchmark(LambdaBenchmark const&) = delete;
1415 
1416  template <class Lam> // NOLINTNEXTLINE(readability-redundant-declaration)
1417  friend Benchmark* ::benchmark::RegisterBenchmark(const std::string&, Lam&&);
1418 
1419  Lambda lambda_;
1420 };
1421 #endif
1422 } // namespace internal
1423 
1424 inline internal::Benchmark* RegisterBenchmark(const std::string& name,
1425  internal::Function* fn) {
1426  // FIXME: this should be a `std::make_unique<>()` but we don't have C++14.
1427  // codechecker_intentional [cplusplus.NewDeleteLeaks]
1428  return internal::RegisterBenchmarkInternal(
1429  ::new internal::FunctionBenchmark(name, fn));
1430 }
1431 
1432 #ifdef BENCHMARK_HAS_CXX11
1433 template <class Lambda>
1434 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn) {
1435  using BenchType =
1436  internal::LambdaBenchmark<typename std::decay<Lambda>::type>;
1437  // FIXME: this should be a `std::make_unique<>()` but we don't have C++14.
1438  // codechecker_intentional [cplusplus.NewDeleteLeaks]
1439  return internal::RegisterBenchmarkInternal(
1440  ::new BenchType(name, std::forward<Lambda>(fn)));
1441 }
1442 #endif
1443 
1444 #if defined(BENCHMARK_HAS_CXX11) && \
1445  (!defined(BENCHMARK_GCC_VERSION) || BENCHMARK_GCC_VERSION >= 409)
1446 template <class Lambda, class... Args>
1447 internal::Benchmark* RegisterBenchmark(const std::string& name, Lambda&& fn,
1448  Args&&... args) {
1449  return benchmark::RegisterBenchmark(
1450  name, [=](benchmark::State& st) { fn(st, args...); });
1451 }
1452 #else
1453 #define BENCHMARK_HAS_NO_VARIADIC_REGISTER_BENCHMARK
1454 #endif
1455 
1456 // The base class for all fixture tests.
1458  public:
1459  Fixture() : internal::Benchmark("") {}
1460 
1461  void Run(State& st) BENCHMARK_OVERRIDE {
1462  this->SetUp(st);
1463  this->BenchmarkCase(st);
1464  this->TearDown(st);
1465  }
1466 
1467  // These will be deprecated ...
1468  virtual void SetUp(const State&) {}
1469  virtual void TearDown(const State&) {}
1470  // ... In favor of these.
1471  virtual void SetUp(State& st) { SetUp(const_cast<const State&>(st)); }
1472  virtual void TearDown(State& st) { TearDown(const_cast<const State&>(st)); }
1473 
1474  protected:
1475  virtual void BenchmarkCase(State&) = 0;
1476 };
1477 } // namespace benchmark
1478 
1479 // ------------------------------------------------------
1480 // Macro to register benchmarks
1481 
1482 // Check that __COUNTER__ is defined and that __COUNTER__ increases by 1
1483 // every time it is expanded. X + 1 == X + 0 is used in case X is defined to be
1484 // empty. If X is empty the expression becomes (+1 == +0).
1485 #if defined(__COUNTER__) && (__COUNTER__ + 1 == __COUNTER__ + 0)
1486 #define BENCHMARK_PRIVATE_UNIQUE_ID __COUNTER__
1487 #else
1488 #define BENCHMARK_PRIVATE_UNIQUE_ID __LINE__
1489 #endif
1490 
1491 // Helpers for generating unique variable names
1492 #ifdef BENCHMARK_HAS_CXX11
1493 #define BENCHMARK_PRIVATE_NAME(...) \
1494  BENCHMARK_PRIVATE_CONCAT(benchmark_uniq_, BENCHMARK_PRIVATE_UNIQUE_ID, \
1495  __VA_ARGS__)
1496 #else
1497 #define BENCHMARK_PRIVATE_NAME(n) \
1498  BENCHMARK_PRIVATE_CONCAT(benchmark_uniq_, BENCHMARK_PRIVATE_UNIQUE_ID, n)
1499 #endif // BENCHMARK_HAS_CXX11
1500 
1501 #define BENCHMARK_PRIVATE_CONCAT(a, b, c) BENCHMARK_PRIVATE_CONCAT2(a, b, c)
1502 #define BENCHMARK_PRIVATE_CONCAT2(a, b, c) a##b##c
1503 // Helper for concatenation with macro name expansion
1504 #define BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method) \
1505  BaseClass##_##Method##_Benchmark
1506 
1507 #define BENCHMARK_PRIVATE_DECLARE(n) \
1508  static ::benchmark::internal::Benchmark* BENCHMARK_PRIVATE_NAME(n) \
1509  BENCHMARK_UNUSED
1510 
1511 #ifdef BENCHMARK_HAS_CXX11
1512 #define BENCHMARK(...) \
1513  BENCHMARK_PRIVATE_DECLARE(_benchmark_) = \
1514  (::benchmark::internal::RegisterBenchmarkInternal( \
1515  new ::benchmark::internal::FunctionBenchmark(#__VA_ARGS__, \
1516  __VA_ARGS__)))
1517 #else
1518 #define BENCHMARK(n) \
1519  BENCHMARK_PRIVATE_DECLARE(n) = \
1520  (::benchmark::internal::RegisterBenchmarkInternal( \
1521  new ::benchmark::internal::FunctionBenchmark(#n, n)))
1522 #endif // BENCHMARK_HAS_CXX11
1523 
1524 // Old-style macros
1525 #define BENCHMARK_WITH_ARG(n, a) BENCHMARK(n)->Arg((a))
1526 #define BENCHMARK_WITH_ARG2(n, a1, a2) BENCHMARK(n)->Args({(a1), (a2)})
1527 #define BENCHMARK_WITH_UNIT(n, t) BENCHMARK(n)->Unit((t))
1528 #define BENCHMARK_RANGE(n, lo, hi) BENCHMARK(n)->Range((lo), (hi))
1529 #define BENCHMARK_RANGE2(n, l1, h1, l2, h2) \
1530  BENCHMARK(n)->RangePair({{(l1), (h1)}, {(l2), (h2)}})
1531 
1532 #ifdef BENCHMARK_HAS_CXX11
1533 
1534 // Register a benchmark which invokes the function specified by `func`
1535 // with the additional arguments specified by `...`.
1536 //
1537 // For example:
1538 //
1539 // template <class ...ExtraArgs>`
1540 // void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
1541 // [...]
1542 //}
1543 // /* Registers a benchmark named "BM_takes_args/int_string_test` */
1544 // BENCHMARK_CAPTURE(BM_takes_args, int_string_test, 42, std::string("abc"));
1545 #define BENCHMARK_CAPTURE(func, test_case_name, ...) \
1546  BENCHMARK_PRIVATE_DECLARE(_benchmark_) = \
1547  (::benchmark::internal::RegisterBenchmarkInternal( \
1548  new ::benchmark::internal::FunctionBenchmark( \
1549  #func "/" #test_case_name, \
1550  [](::benchmark::State& st) { func(st, __VA_ARGS__); })))
1551 
1552 #endif // BENCHMARK_HAS_CXX11
1553 
1554 // This will register a benchmark for a templatized function. For example:
1555 //
1556 // template<int arg>
1557 // void BM_Foo(int iters);
1558 //
1559 // BENCHMARK_TEMPLATE(BM_Foo, 1);
1560 //
1561 // will register BM_Foo<1> as a benchmark.
1562 #define BENCHMARK_TEMPLATE1(n, a) \
1563  BENCHMARK_PRIVATE_DECLARE(n) = \
1564  (::benchmark::internal::RegisterBenchmarkInternal( \
1565  new ::benchmark::internal::FunctionBenchmark(#n "<" #a ">", n<a>)))
1566 
1567 #define BENCHMARK_TEMPLATE2(n, a, b) \
1568  BENCHMARK_PRIVATE_DECLARE(n) = \
1569  (::benchmark::internal::RegisterBenchmarkInternal( \
1570  new ::benchmark::internal::FunctionBenchmark(#n "<" #a "," #b ">", \
1571  n<a, b>)))
1572 
1573 #ifdef BENCHMARK_HAS_CXX11
1574 #define BENCHMARK_TEMPLATE(n, ...) \
1575  BENCHMARK_PRIVATE_DECLARE(n) = \
1576  (::benchmark::internal::RegisterBenchmarkInternal( \
1577  new ::benchmark::internal::FunctionBenchmark( \
1578  #n "<" #__VA_ARGS__ ">", n<__VA_ARGS__>)))
1579 #else
1580 #define BENCHMARK_TEMPLATE(n, a) BENCHMARK_TEMPLATE1(n, a)
1581 #endif
1582 
1583 #ifdef BENCHMARK_HAS_CXX11
1584 // This will register a benchmark for a templatized function,
1585 // with the additional arguments specified by `...`.
1586 //
1587 // For example:
1588 //
1589 // template <typename T, class ...ExtraArgs>`
1590 // void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) {
1591 // [...]
1592 //}
1593 // /* Registers a benchmark named "BM_takes_args<void>/int_string_test` */
1594 // BENCHMARK_TEMPLATE1_CAPTURE(BM_takes_args, void, int_string_test, 42,
1595 // std::string("abc"));
1596 #define BENCHMARK_TEMPLATE1_CAPTURE(func, a, test_case_name, ...) \
1597  BENCHMARK_CAPTURE(func<a>, test_case_name, __VA_ARGS__)
1598 
1599 #define BENCHMARK_TEMPLATE2_CAPTURE(func, a, b, test_case_name, ...) \
1600  BENCHMARK_PRIVATE_DECLARE(func) = \
1601  (::benchmark::internal::RegisterBenchmarkInternal( \
1602  new ::benchmark::internal::FunctionBenchmark( \
1603  #func "<" #a "," #b ">" \
1604  "/" #test_case_name, \
1605  [](::benchmark::State& st) { func<a, b>(st, __VA_ARGS__); })))
1606 #endif // BENCHMARK_HAS_CXX11
1607 
1608 #define BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1609  class BaseClass##_##Method##_Benchmark : public BaseClass { \
1610  public: \
1611  BaseClass##_##Method##_Benchmark() { \
1612  this->SetName(#BaseClass "/" #Method); \
1613  } \
1614  \
1615  protected: \
1616  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1617  };
1618 
1619 #define BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1620  class BaseClass##_##Method##_Benchmark : public BaseClass<a> { \
1621  public: \
1622  BaseClass##_##Method##_Benchmark() { \
1623  this->SetName(#BaseClass "<" #a ">/" #Method); \
1624  } \
1625  \
1626  protected: \
1627  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1628  };
1629 
1630 #define BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1631  class BaseClass##_##Method##_Benchmark : public BaseClass<a, b> { \
1632  public: \
1633  BaseClass##_##Method##_Benchmark() { \
1634  this->SetName(#BaseClass "<" #a "," #b ">/" #Method); \
1635  } \
1636  \
1637  protected: \
1638  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1639  };
1640 
1641 #ifdef BENCHMARK_HAS_CXX11
1642 #define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, ...) \
1643  class BaseClass##_##Method##_Benchmark : public BaseClass<__VA_ARGS__> { \
1644  public: \
1645  BaseClass##_##Method##_Benchmark() { \
1646  this->SetName(#BaseClass "<" #__VA_ARGS__ ">/" #Method); \
1647  } \
1648  \
1649  protected: \
1650  void BenchmarkCase(::benchmark::State&) BENCHMARK_OVERRIDE; \
1651  };
1652 #else
1653 #define BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(n, a) \
1654  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(n, a)
1655 #endif
1656 
1657 #define BENCHMARK_DEFINE_F(BaseClass, Method) \
1658  BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1659  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1660 
1661 #define BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a) \
1662  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1663  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1664 
1665 #define BENCHMARK_TEMPLATE2_DEFINE_F(BaseClass, Method, a, b) \
1666  BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1667  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1668 
1669 #ifdef BENCHMARK_HAS_CXX11
1670 #define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, ...) \
1671  BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1672  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1673 #else
1674 #define BENCHMARK_TEMPLATE_DEFINE_F(BaseClass, Method, a) \
1675  BENCHMARK_TEMPLATE1_DEFINE_F(BaseClass, Method, a)
1676 #endif
1677 
1678 #define BENCHMARK_REGISTER_F(BaseClass, Method) \
1679  BENCHMARK_PRIVATE_REGISTER_F(BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method))
1680 
1681 #define BENCHMARK_PRIVATE_REGISTER_F(TestName) \
1682  BENCHMARK_PRIVATE_DECLARE(TestName) = \
1683  (::benchmark::internal::RegisterBenchmarkInternal(new TestName()))
1684 
1685 // This macro will define and register a benchmark within a fixture class.
1686 #define BENCHMARK_F(BaseClass, Method) \
1687  BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \
1688  BENCHMARK_REGISTER_F(BaseClass, Method); \
1689  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1690 
1691 #define BENCHMARK_TEMPLATE1_F(BaseClass, Method, a) \
1692  BENCHMARK_TEMPLATE1_PRIVATE_DECLARE_F(BaseClass, Method, a) \
1693  BENCHMARK_REGISTER_F(BaseClass, Method); \
1694  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1695 
1696 #define BENCHMARK_TEMPLATE2_F(BaseClass, Method, a, b) \
1697  BENCHMARK_TEMPLATE2_PRIVATE_DECLARE_F(BaseClass, Method, a, b) \
1698  BENCHMARK_REGISTER_F(BaseClass, Method); \
1699  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1700 
1701 #ifdef BENCHMARK_HAS_CXX11
1702 #define BENCHMARK_TEMPLATE_F(BaseClass, Method, ...) \
1703  BENCHMARK_TEMPLATE_PRIVATE_DECLARE_F(BaseClass, Method, __VA_ARGS__) \
1704  BENCHMARK_REGISTER_F(BaseClass, Method); \
1705  void BENCHMARK_PRIVATE_CONCAT_NAME(BaseClass, Method)::BenchmarkCase
1706 #else
1707 #define BENCHMARK_TEMPLATE_F(BaseClass, Method, a) \
1708  BENCHMARK_TEMPLATE1_F(BaseClass, Method, a)
1709 #endif
1710 
1711 // Helper macro to create a main routine in a test that runs the benchmarks
1712 // Note the workaround for Hexagon simulator passing argc != 0, argv = NULL.
1713 #define BENCHMARK_MAIN() \
1714  int main(int argc, char** argv) { \
1715  char arg0_default[] = "benchmark"; \
1716  char* args_default = arg0_default; \
1717  if (!argv) { \
1718  argc = 1; \
1719  argv = &args_default; \
1720  } \
1721  ::benchmark::Initialize(&argc, argv); \
1722  if (::benchmark::ReportUnrecognizedArguments(argc, argv)) return 1; \
1723  ::benchmark::RunSpecifiedBenchmarks(); \
1724  ::benchmark::Shutdown(); \
1725  return 0; \
1726  } \
1727  int main(int, char**)
1728 
1729 // ------------------------------------------------------
1730 // Benchmark Reporters
1731 
1732 namespace benchmark {
1733 
1734 struct BENCHMARK_EXPORT CPUInfo {
1735  struct CacheInfo {
1736  std::string type;
1737  int level;
1738  int size;
1739  int num_sharing;
1740  };
1741 
1742  enum Scaling { UNKNOWN, ENABLED, DISABLED };
1743 
1744  int num_cpus;
1745  Scaling scaling;
1746  double cycles_per_second;
1747  std::vector<CacheInfo> caches;
1748  std::vector<double> load_avg;
1749 
1750  static const CPUInfo& Get();
1751 
1752  private:
1753  CPUInfo();
1754  BENCHMARK_DISALLOW_COPY_AND_ASSIGN(CPUInfo);
1755 };
1756 
1757 // Adding Struct for System Information
1758 struct BENCHMARK_EXPORT SystemInfo {
1759  std::string name;
1760  static const SystemInfo& Get();
1761 
1762  private:
1763  SystemInfo();
1764  BENCHMARK_DISALLOW_COPY_AND_ASSIGN(SystemInfo);
1765 };
1766 
1767 // BenchmarkName contains the components of the Benchmark's name
1768 // which allows individual fields to be modified or cleared before
1769 // building the final name using 'str()'.
1770 struct BENCHMARK_EXPORT BenchmarkName {
1771  std::string function_name;
1772  std::string args;
1773  std::string min_time;
1774  std::string min_warmup_time;
1775  std::string iterations;
1776  std::string repetitions;
1777  std::string time_type;
1778  std::string threads;
1779 
1780  // Return the full name of the benchmark with each non-empty
1781  // field separated by a '/'
1782  std::string str() const;
1783 };
1784 
1785 // Interface for custom benchmark result printers.
1786 // By default, benchmark reports are printed to stdout. However an application
1787 // can control the destination of the reports by calling
1788 // RunSpecifiedBenchmarks and passing it a custom reporter object.
1789 // The reporter object must implement the following interface.
1790 class BENCHMARK_EXPORT BenchmarkReporter {
1791  public:
1792  struct Context {
1793  CPUInfo const& cpu_info;
1794  SystemInfo const& sys_info;
1795  // The number of chars in the longest benchmark name.
1796  size_t name_field_width;
1797  static const char* executable_name;
1798  Context();
1799  };
1800 
1801  struct BENCHMARK_EXPORT Run {
1802  static const int64_t no_repetition_index = -1;
1803  enum RunType { RT_Iteration, RT_Aggregate };
1804 
1805  Run()
1806  : run_type(RT_Iteration),
1807  aggregate_unit(kTime),
1808  skipped(internal::NotSkipped),
1809  iterations(1),
1810  threads(1),
1811  time_unit(GetDefaultTimeUnit()),
1812  real_accumulated_time(0),
1813  cpu_accumulated_time(0),
1814  max_heapbytes_used(0),
1815  use_real_time_for_initial_big_o(false),
1816  complexity(oNone),
1817  complexity_lambda(),
1818  complexity_n(0),
1819  report_big_o(false),
1820  report_rms(false),
1821  memory_result(NULL),
1822  allocs_per_iter(0.0) {}
1823 
1824  std::string benchmark_name() const;
1825  BenchmarkName run_name;
1826  int64_t family_index;
1827  int64_t per_family_instance_index;
1828  RunType run_type;
1829  std::string aggregate_name;
1830  StatisticUnit aggregate_unit;
1831  std::string report_label; // Empty if not set by benchmark.
1832  internal::Skipped skipped;
1833  std::string skip_message;
1834 
1835  IterationCount iterations;
1836  int64_t threads;
1837  int64_t repetition_index;
1838  int64_t repetitions;
1839  TimeUnit time_unit;
1840  double real_accumulated_time;
1841  double cpu_accumulated_time;
1842 
1843  // Return a value representing the real time per iteration in the unit
1844  // specified by 'time_unit'.
1845  // NOTE: If 'iterations' is zero the returned value represents the
1846  // accumulated time.
1847  double GetAdjustedRealTime() const;
1848 
1849  // Return a value representing the cpu time per iteration in the unit
1850  // specified by 'time_unit'.
1851  // NOTE: If 'iterations' is zero the returned value represents the
1852  // accumulated time.
1853  double GetAdjustedCPUTime() const;
1854 
1855  // This is set to 0.0 if memory tracing is not enabled.
1856  double max_heapbytes_used;
1857 
1858  // By default Big-O is computed for CPU time, but that is not what you want
1859  // to happen when manual time was requested, which is stored as real time.
1860  bool use_real_time_for_initial_big_o;
1861 
1862  // Keep track of arguments to compute asymptotic complexity
1863  BigO complexity;
1864  BigOFunc* complexity_lambda;
1865  ComplexityN complexity_n;
1866 
1867  // what statistics to compute from the measurements
1868  const std::vector<internal::Statistics>* statistics;
1869 
1870  // Inform print function whether the current run is a complexity report
1871  bool report_big_o;
1872  bool report_rms;
1873 
1874  UserCounters counters;
1875 
1876  // Memory metrics.
1877  const MemoryManager::Result* memory_result;
1878  double allocs_per_iter;
1879  };
1880 
1882  PerFamilyRunReports() : num_runs_total(0), num_runs_done(0) {}
1883 
1884  // How many runs will all instances of this benchmark perform?
1885  int num_runs_total;
1886 
1887  // How many runs have happened already?
1888  int num_runs_done;
1889 
1890  // The reports about (non-errneous!) runs of this family.
1891  std::vector<BenchmarkReporter::Run> Runs;
1892  };
1893 
1894  // Construct a BenchmarkReporter with the output stream set to 'std::cout'
1895  // and the error stream set to 'std::cerr'
1897 
1898  // Called once for every suite of benchmarks run.
1899  // The parameter "context" contains information that the
1900  // reporter may wish to use when generating its report, for example the
1901  // platform under which the benchmarks are running. The benchmark run is
1902  // never started if this function returns false, allowing the reporter
1903  // to skip runs based on the context information.
1904  virtual bool ReportContext(const Context& context) = 0;
1905 
1906  // Called once for each group of benchmark runs, gives information about
1907  // the configurations of the runs.
1908  virtual void ReportRunsConfig(double /*min_time*/,
1909  bool /*has_explicit_iters*/,
1910  IterationCount /*iters*/) {}
1911 
1912  // Called once for each group of benchmark runs, gives information about
1913  // cpu-time and heap memory usage during the benchmark run. If the group
1914  // of runs contained more than two entries then 'report' contains additional
1915  // elements representing the mean and standard deviation of those runs.
1916  // Additionally if this group of runs was the last in a family of benchmarks
1917  // 'reports' contains additional entries representing the asymptotic
1918  // complexity and RMS of that benchmark family.
1919  virtual void ReportRuns(const std::vector<Run>& report) = 0;
1920 
1921  // Called once and only once after ever group of benchmarks is run and
1922  // reported.
1923  virtual void Finalize() {}
1924 
1925  // REQUIRES: The object referenced by 'out' is valid for the lifetime
1926  // of the reporter.
1927  void SetOutputStream(std::ostream* out) {
1928  assert(out);
1929  output_stream_ = out;
1930  }
1931 
1932  // REQUIRES: The object referenced by 'err' is valid for the lifetime
1933  // of the reporter.
1934  void SetErrorStream(std::ostream* err) {
1935  assert(err);
1936  error_stream_ = err;
1937  }
1938 
1939  std::ostream& GetOutputStream() const { return *output_stream_; }
1940 
1941  std::ostream& GetErrorStream() const { return *error_stream_; }
1942 
1943  virtual ~BenchmarkReporter();
1944 
1945  // Write a human readable string to 'out' representing the specified
1946  // 'context'.
1947  // REQUIRES: 'out' is non-null.
1948  static void PrintBasicContext(std::ostream* out, Context const& context);
1949 
1950  private:
1951  std::ostream* output_stream_;
1952  std::ostream* error_stream_;
1953 };
1954 
1955 // Simple reporter that outputs benchmark data to the console. This is the
1956 // default reporter used by RunSpecifiedBenchmarks().
1957 class BENCHMARK_EXPORT ConsoleReporter : public BenchmarkReporter {
1958  public:
1959  enum OutputOptions {
1960  OO_None = 0,
1961  OO_Color = 1,
1962  OO_Tabular = 2,
1963  OO_ColorTabular = OO_Color | OO_Tabular,
1964  OO_Defaults = OO_ColorTabular
1965  };
1966  explicit ConsoleReporter(OutputOptions opts_ = OO_Defaults)
1967  : output_options_(opts_), name_field_width_(0), printed_header_(false) {}
1968 
1969  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
1970  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
1971 
1972  protected:
1973  virtual void PrintRunData(const Run& report);
1974  virtual void PrintHeader(const Run& report);
1975 
1976  OutputOptions output_options_;
1977  size_t name_field_width_;
1978  UserCounters prev_counters_;
1979  bool printed_header_;
1980 };
1981 
1982 class BENCHMARK_EXPORT JSONReporter : public BenchmarkReporter {
1983  public:
1984  JSONReporter() : first_report_(true) {}
1985  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
1986  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
1987  void Finalize() BENCHMARK_OVERRIDE;
1988 
1989  private:
1990  void PrintRunData(const Run& report);
1991 
1992  bool first_report_;
1993 };
1994 
1995 class BENCHMARK_EXPORT BENCHMARK_DEPRECATED_MSG(
1996  "The CSV Reporter will be removed in a future release") CSVReporter
1997  : public BenchmarkReporter {
1998  public:
1999  CSVReporter() : printed_header_(false) {}
2000  bool ReportContext(const Context& context) BENCHMARK_OVERRIDE;
2001  void ReportRuns(const std::vector<Run>& reports) BENCHMARK_OVERRIDE;
2002 
2003  private:
2004  void PrintRunData(const Run& report);
2005 
2006  bool printed_header_;
2007  std::set<std::string> user_counter_names_;
2008 };
2009 
2010 inline const char* GetTimeUnitString(TimeUnit unit) {
2011  switch (unit) {
2012  case kSecond:
2013  return "s";
2014  case kMillisecond:
2015  return "ms";
2016  case kMicrosecond:
2017  return "us";
2018  case kNanosecond:
2019  return "ns";
2020  }
2021  BENCHMARK_UNREACHABLE();
2022 }
2023 
2024 inline double GetTimeUnitMultiplier(TimeUnit unit) {
2025  switch (unit) {
2026  case kSecond:
2027  return 1;
2028  case kMillisecond:
2029  return 1e3;
2030  case kMicrosecond:
2031  return 1e6;
2032  case kNanosecond:
2033  return 1e9;
2034  }
2035  BENCHMARK_UNREACHABLE();
2036 }
2037 
2038 // Creates a list of integer values for the given range and multiplier.
2039 // This can be used together with ArgsProduct() to allow multiple ranges
2040 // with different multipliers.
2041 // Example:
2042 // ArgsProduct({
2043 // CreateRange(0, 1024, /*multi=*/32),
2044 // CreateRange(0, 100, /*multi=*/4),
2045 // CreateDenseRange(0, 4, /*step=*/1),
2046 // });
2047 BENCHMARK_EXPORT
2048 std::vector<int64_t> CreateRange(int64_t lo, int64_t hi, int multi);
2049 
2050 // Creates a list of integer values for the given range and step.
2051 BENCHMARK_EXPORT
2052 std::vector<int64_t> CreateDenseRange(int64_t start, int64_t limit, int step);
2053 
2054 } // namespace benchmark
2055 
2056 #if defined(_MSC_VER)
2057 #pragma warning(pop)
2058 #endif
2059 
2060 #endif // BENCHMARK_BENCHMARK_H_
Definition: benchmark.h:1790
Definition: benchmark.h:1957
Definition: benchmark.h:633
Definition: benchmark.h:1457
Definition: benchmark.h:1982
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:1120
Definition: benchmark.h:1392
Definition: perf_counters.h:149
Definition: thread_manager.h:12
Definition: thread_timer.h:10
Definition: benchmark.h:1770
Definition: benchmark.h:1792
Definition: benchmark.h:1801
Definition: benchmark.h:1735
Definition: benchmark.h:1734
Definition: benchmark.h:382
Definition: benchmark.h:1063
Definition: benchmark.h:1062
Definition: benchmark.h:1758
Definition: benchmark.h:713