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