benchmark 1.8.5
Loading...
Searching...
No Matches
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:
20static void BM_StringCreation(benchmark::State& state) {
21 for (auto _ : state)
22 std::string empty_string;
23}
24
25// Register the function as a benchmark
26BENCHMARK(BM_StringCreation);
27
28// Define another benchmark
29static void BM_StringCopy(benchmark::State& state) {
30 std::string x = "hello";
31 for (auto _ : state)
32 std::string copy(x);
33}
34BENCHMARK(BM_StringCopy);
35
36// Augment the main() program to invoke benchmarks if specified
37// via the --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'
42int 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
55static 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}
63BENCHMARK(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.
69BENCHMARK(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.
74static 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}
84BENCHMARK(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.
98BENCHMARK(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.
105static 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}
110BENCHMARK(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.
115template <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}
127BENCHMARK_TEMPLATE(BM_Sequential, WaitQueue<int>)->Range(1<<0, 1<<10);
128
129Use `Benchmark::MinTime(double t)` to set the minimum time used to run the
130benchmark. This option overrides the `benchmark_min_time` flag.
131
132void BM_test(benchmark::State& state) {
133 ... body ...
134}
135BENCHMARK(BM_test)->MinTime(2.0); // Run for at least 2 seconds.
136
137In a multithreaded test, it is guaranteed that none of the threads will start
138until all have reached the loop start, and all will have finished before any
139thread exits the loop body. As such, any global setup or teardown you want to
140do can be wrapped in a check against the thread index:
141
142static 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}
153BENCHMARK(BM_MultiThreaded)->Threads(4);
154
155
156If a benchmark runs a few milliseconds it may be hard to visually compare the
157measured times, since the output data is given in nanoseconds per default. In
158order to manually set the time unit, you can specify it manually:
159
160BENCHMARK(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
299namespace benchmark {
300class BenchmarkReporter;
301
302// Default number of minimum benchmark running time in seconds.
303const char kDefaultMinTimeStr[] = "0.5s";
304
305// Returns the version of the library.
306BENCHMARK_EXPORT std::string GetBenchmarkVersion();
307
308BENCHMARK_EXPORT void PrintDefaultHelp();
309
310BENCHMARK_EXPORT void Initialize(int* argc, char** argv,
311 void (*HelperPrinterf)() = PrintDefaultHelp);
312BENCHMARK_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).
316BENCHMARK_EXPORT bool ReportUnrecognizedArguments(int argc, char** argv);
317
318// Returns the current value of --benchmark_filter.
319BENCHMARK_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.
325BENCHMARK_EXPORT void SetBenchmarkFilter(std::string value);
326
327// Returns the current value of --v (command line value for verbosity).
328BENCHMARK_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
333BENCHMARK_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.
351BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks();
352BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks(std::string spec);
353
354BENCHMARK_EXPORT size_t
355RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter);
356BENCHMARK_EXPORT size_t
357RunSpecifiedBenchmarks(BenchmarkReporter* display_reporter, std::string spec);
358
359BENCHMARK_EXPORT size_t RunSpecifiedBenchmarks(
360 BenchmarkReporter* display_reporter, BenchmarkReporter* file_reporter);
361BENCHMARK_EXPORT size_t
362RunSpecifiedBenchmarks(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.
367enum TimeUnit { kNanosecond, kMicrosecond, kMillisecond, kSecond };
368
369BENCHMARK_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
373BENCHMARK_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.
416BENCHMARK_EXPORT
417void 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.
436BENCHMARK_EXPORT
437void RegisterProfilerManager(ProfilerManager* profiler_manager);
438
439// Add a key-value pair to output as part of the context stanza in the report.
440BENCHMARK_EXPORT
441void AddCustomContext(const std::string& key, const std::string& value);
442
443namespace internal {
444class Benchmark;
445class BenchmarkImp;
446class BenchmarkFamilies;
447
448BENCHMARK_EXPORT std::map<std::string, std::string>*& GetGlobalContext();
449
450BENCHMARK_EXPORT
451void UseCharPointer(char const volatile*);
452
453// Take ownership of the pointer and register the benchmark. Return the
454// registered benchmark.
455BENCHMARK_EXPORT Benchmark* RegisterBenchmarkInternal(Benchmark*);
456
457// Ensure that the standard streams are properly initialized in every TU.
458BENCHMARK_EXPORT int InitializeStreams();
459BENCHMARK_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
471inline 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)
482template <class Tp>
483BENCHMARK_DEPRECATED_MSG(
484 "The const-ref version of this method can permit "
485 "undesired compiler optimizations in benchmarks")
486inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
487 asm volatile("" : : "r,m"(value) : "memory");
488}
489
490template <class Tp>
491inline 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
500template <class Tp>
501inline 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
512template <class Tp>
513BENCHMARK_DEPRECATED_MSG(
514 "The const-ref version of this method can permit "
515 "undesired compiler optimizations in benchmarks")
516inline 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
523template <class Tp>
524BENCHMARK_DEPRECATED_MSG(
525 "The const-ref version of this method can permit "
526 "undesired compiler optimizations in benchmarks")
527inline 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
534template <class Tp>
535inline 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
542template <class Tp>
543inline 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
550template <class Tp>
551inline 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
558template <class Tp>
559inline 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.
570template <class Tp>
571BENCHMARK_DEPRECATED_MSG(
572 "The const-ref version of this method can permit "
573 "undesired compiler optimizations in benchmarks")
574inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
575 asm volatile("" : : "m"(value) : "memory");
576}
577
578template <class Tp>
579inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp& value) {
580 asm volatile("" : "+m"(value) : : "memory");
581}
582
583#ifdef BENCHMARK_HAS_CXX11
584template <class Tp>
585inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp&& value) {
586 asm volatile("" : "+m"(value) : : "memory");
587}
588#endif
589#endif
590
591#ifndef BENCHMARK_HAS_CXX11
592inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() {
593 asm volatile("" : : : "memory");
594}
595#endif
596#elif defined(_MSC_VER)
597template <class Tp>
598BENCHMARK_DEPRECATED_MSG(
599 "The const-ref version of this method can permit "
600 "undesired compiler optimizations in benchmarks")
601inline 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
607inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() { _ReadWriteBarrier(); }
608#endif
609#else
610#ifdef BENCHMARK_HAS_CXX11
611template <class Tp>
612inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp&& value) {
613 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
614}
615#else
616template <class Tp>
617BENCHMARK_DEPRECATED_MSG(
618 "The const-ref version of this method can permit "
619 "undesired compiler optimizations in benchmarks")
620inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) {
621 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value));
622}
623
624template <class Tp>
625inline 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.
633class 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.
683Counter::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.
690typedef 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.
696enum BigO { oNone, o1, oN, oNSquared, oNCubed, oLogN, oNLogN, oAuto, oLambda };
697
698typedef int64_t ComplexityN;
699
700typedef int64_t IterationCount;
701
702enum StatisticUnit { kTime, kPercentage };
703
704// BigOFunc is passed to a benchmark in order to specify the asymptotic
705// computational complexity for the benchmark.
706typedef 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
710typedef double(StatisticsFunc)(const std::vector<double>&);
711
712namespace internal {
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
724class ThreadTimer;
725class ThreadManager;
727
728enum 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
748enum 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.
762class 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
1026inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunning() {
1027 return KeepRunningInternal(1, /*is_batch=*/false);
1028}
1029
1030inline BENCHMARK_ALWAYS_INLINE bool State::KeepRunningBatch(IterationCount n) {
1031 return KeepRunningInternal(n, /*is_batch=*/true);
1032}
1033
1034inline 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
1102inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::begin() {
1103 return StateIterator(this);
1104}
1105inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::end() {
1106 StartKeepRunning();
1107 return StateIterator();
1108}
1109
1110namespace internal {
1111
1112typedef 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.
1120class 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.
1377internal::Benchmark* RegisterBenchmark(const std::string& name,
1378 internal::Function* fn);
1379
1380#if defined(BENCHMARK_HAS_CXX11)
1381template <class Lambda>
1382internal::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.
1387BENCHMARK_EXPORT void ClearRegisteredBenchmarks();
1388
1389namespace internal {
1390// The class used to hold all Benchmarks created from static function.
1391// (ie those created using the BENCHMARK(...) macros.
1392class 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
1404template <class Lambda>
1405class 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
1424inline 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
1433template <class Lambda>
1434internal::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)
1446template <class Lambda, class... Args>
1447internal::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
1732namespace benchmark {
1733
1734struct 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
1758struct 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()'.
1770struct 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.
1790class 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().
1957class 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
1982class 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
1995class 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
2010inline 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
2024inline 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// });
2047BENCHMARK_EXPORT
2048std::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.
2051BENCHMARK_EXPORT
2052std::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