1 // Support for registering benchmarks for functions. 2 3 /* Example usage: 4 // Define a function that executes the code to be measured a 5 // specified number of times: 6 static void BM_StringCreation(benchmark::State& state) { 7 while (state.KeepRunning()) 8 std::string empty_string; 9 } 10 11 // Register the function as a benchmark 12 BENCHMARK(BM_StringCreation); 13 14 // Define another benchmark 15 static void BM_StringCopy(benchmark::State& state) { 16 std::string x = "hello"; 17 while (state.KeepRunning()) 18 std::string copy(x); 19 } 20 BENCHMARK(BM_StringCopy); 21 22 // Augment the main() program to invoke benchmarks if specified 23 // via the --benchmarks command line flag. E.g., 24 // my_unittest --benchmark_filter=all 25 // my_unittest --benchmark_filter=BM_StringCreation 26 // my_unittest --benchmark_filter=String 27 // my_unittest --benchmark_filter='Copy|Creation' 28 int main(int argc, char** argv) { 29 benchmark::Initialize(&argc, argv); 30 benchmark::RunSpecifiedBenchmarks(); 31 return 0; 32 } 33 34 // Sometimes a family of microbenchmarks can be implemented with 35 // just one routine that takes an extra argument to specify which 36 // one of the family of benchmarks to run. For example, the following 37 // code defines a family of microbenchmarks for measuring the speed 38 // of memcpy() calls of different lengths: 39 40 static void BM_memcpy(benchmark::State& state) { 41 char* src = new char[state.range(0)]; char* dst = new char[state.range(0)]; 42 memset(src, 'x', state.range(0)); 43 while (state.KeepRunning()) 44 memcpy(dst, src, state.range(0)); 45 state.SetBytesProcessed(int64_t(state.iterations()) * 46 int64_t(state.range(0))); 47 delete[] src; delete[] dst; 48 } 49 BENCHMARK(BM_memcpy)->Arg(8)->Arg(64)->Arg(512)->Arg(1<<10)->Arg(8<<10); 50 51 // The preceding code is quite repetitive, and can be replaced with the 52 // following short-hand. The following invocation will pick a few 53 // appropriate arguments in the specified range and will generate a 54 // microbenchmark for each such argument. 55 BENCHMARK(BM_memcpy)->Range(8, 8<<10); 56 57 // You might have a microbenchmark that depends on two inputs. For 58 // example, the following code defines a family of microbenchmarks for 59 // measuring the speed of set insertion. 60 static void BM_SetInsert(benchmark::State& state) { 61 while (state.KeepRunning()) { 62 state.PauseTiming(); 63 set<int> data = ConstructRandomSet(state.range(0)); 64 state.ResumeTiming(); 65 for (int j = 0; j < state.range(1); ++j) 66 data.insert(RandomNumber()); 67 } 68 } 69 BENCHMARK(BM_SetInsert) 70 ->Args({1<<10, 1}) 71 ->Args({1<<10, 8}) 72 ->Args({1<<10, 64}) 73 ->Args({1<<10, 512}) 74 ->Args({8<<10, 1}) 75 ->Args({8<<10, 8}) 76 ->Args({8<<10, 64}) 77 ->Args({8<<10, 512}); 78 79 // The preceding code is quite repetitive, and can be replaced with 80 // the following short-hand. The following macro will pick a few 81 // appropriate arguments in the product of the two specified ranges 82 // and will generate a microbenchmark for each such pair. 83 BENCHMARK(BM_SetInsert)->Ranges({{1<<10, 8<<10}, {1, 512}}); 84 85 // For more complex patterns of inputs, passing a custom function 86 // to Apply allows programmatic specification of an 87 // arbitrary set of arguments to run the microbenchmark on. 88 // The following example enumerates a dense range on 89 // one parameter, and a sparse range on the second. 90 static void CustomArguments(benchmark::internal::Benchmark* b) { 91 for (int i = 0; i <= 10; ++i) 92 for (int j = 32; j <= 1024*1024; j *= 8) 93 b->Args({i, j}); 94 } 95 BENCHMARK(BM_SetInsert)->Apply(CustomArguments); 96 97 // Templated microbenchmarks work the same way: 98 // Produce then consume 'size' messages 'iters' times 99 // Measures throughput in the absence of multiprogramming. 100 template <class Q> int BM_Sequential(benchmark::State& state) { 101 Q q; 102 typename Q::value_type v; 103 while (state.KeepRunning()) { 104 for (int i = state.range(0); i--; ) 105 q.push(v); 106 for (int e = state.range(0); e--; ) 107 q.Wait(&v); 108 } 109 // actually messages, not bytes: 110 state.SetBytesProcessed( 111 static_cast<int64_t>(state.iterations())*state.range(0)); 112 } 113 BENCHMARK_TEMPLATE(BM_Sequential, WaitQueue<int>)->Range(1<<0, 1<<10); 114 115 Use `Benchmark::MinTime(double t)` to set the minimum time used to run the 116 benchmark. This option overrides the `benchmark_min_time` flag. 117 118 void BM_test(benchmark::State& state) { 119 ... body ... 120 } 121 BENCHMARK(BM_test)->MinTime(2.0); // Run for at least 2 seconds. 122 123 In a multithreaded test, it is guaranteed that none of the threads will start 124 until all have called KeepRunning, and all will have finished before KeepRunning 125 returns false. As such, any global setup or teardown you want to do can be 126 wrapped in a check against the thread index: 127 128 static void BM_MultiThreaded(benchmark::State& state) { 129 if (state.thread_index == 0) { 130 // Setup code here. 131 } 132 while (state.KeepRunning()) { 133 // Run the test as normal. 134 } 135 if (state.thread_index == 0) { 136 // Teardown code here. 137 } 138 } 139 BENCHMARK(BM_MultiThreaded)->Threads(4); 140 141 142 If a benchmark runs a few milliseconds it may be hard to visually compare the 143 measured times, since the output data is given in nanoseconds per default. In 144 order to manually set the time unit, you can specify it manually: 145 146 BENCHMARK(BM_test)->Unit(benchmark::kMillisecond); 147 */ 148 149 #ifndef BENCHMARK_BENCHMARK_API_H_ 150 #define BENCHMARK_BENCHMARK_API_H_ 151 152 #include <assert.h> 153 #include <stddef.h> 154 #include <stdint.h> 155 156 #include <string> 157 #include <vector> 158 #include <map> 159 160 #include "macros.h" 161 162 #if defined(BENCHMARK_HAS_CXX11) 163 #include <type_traits> 164 #include <initializer_list> 165 #include <utility> 166 #endif 167 168 #if defined(_MSC_VER) 169 #include <intrin.h> // for _ReadWriteBarrier 170 #endif 171 172 namespace benchmark { 173 class BenchmarkReporter; 174 175 void Initialize(int* argc, char** argv); 176 177 // Report to stdout all arguments in 'argv' as unrecognized except the first. 178 // Returns true there is at least on unrecognized argument (i.e. 'argc' > 1). 179 bool ReportUnrecognizedArguments(int argc, char** argv); 180 181 // Generate a list of benchmarks matching the specified --benchmark_filter flag 182 // and if --benchmark_list_tests is specified return after printing the name 183 // of each matching benchmark. Otherwise run each matching benchmark and 184 // report the results. 185 // 186 // The second and third overload use the specified 'console_reporter' and 187 // 'file_reporter' respectively. 'file_reporter' will write to the file 188 // specified 189 // by '--benchmark_output'. If '--benchmark_output' is not given the 190 // 'file_reporter' is ignored. 191 // 192 // RETURNS: The number of matching benchmarks. 193 size_t RunSpecifiedBenchmarks(); 194 size_t RunSpecifiedBenchmarks(BenchmarkReporter* console_reporter); 195 size_t RunSpecifiedBenchmarks(BenchmarkReporter* console_reporter, 196 BenchmarkReporter* file_reporter); 197 198 // If this routine is called, peak memory allocation past this point in the 199 // benchmark is reported at the end of the benchmark report line. (It is 200 // computed by running the benchmark once with a single iteration and a memory 201 // tracer.) 202 // TODO(dominic) 203 // void MemoryUsage(); 204 205 namespace internal { 206 class Benchmark; 207 class BenchmarkImp; 208 class BenchmarkFamilies; 209 210 void UseCharPointer(char const volatile*); 211 212 // Take ownership of the pointer and register the benchmark. Return the 213 // registered benchmark. 214 Benchmark* RegisterBenchmarkInternal(Benchmark*); 215 216 // Ensure that the standard streams are properly initialized in every TU. 217 int InitializeStreams(); 218 BENCHMARK_UNUSED static int stream_init_anchor = InitializeStreams(); 219 220 } // end namespace internal 221 222 223 #if !defined(__GNUC__) || defined(__pnacl__) || defined(EMSCRIPTN) 224 # define BENCHMARK_HAS_NO_INLINE_ASSEMBLY 225 #endif 226 227 // The DoNotOptimize(...) function can be used to prevent a value or 228 // expression from being optimized away by the compiler. This function is 229 // intended to add little to no overhead. 230 // See: https://youtu.be/nXaxk27zwlk?t=2441 231 #ifndef BENCHMARK_HAS_NO_INLINE_ASSEMBLY 232 template <class Tp> 233 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) { 234 // Clang doesn't like the 'X' constraint on `value` and certain GCC versions 235 // don't like the 'g' constraint. Attempt to placate them both. 236 #if defined(__clang__) 237 asm volatile("" : : "g"(value) : "memory"); 238 #else 239 asm volatile("" : : "i,r,m"(value) : "memory"); 240 #endif 241 } 242 // Force the compiler to flush pending writes to global memory. Acts as an 243 // effective read/write barrier 244 inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() { 245 asm volatile("" : : : "memory"); 246 } 247 #elif defined(_MSC_VER) 248 template <class Tp> 249 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) { 250 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value)); 251 _ReadWriteBarrier(); 252 } 253 254 inline BENCHMARK_ALWAYS_INLINE void ClobberMemory() { 255 _ReadWriteBarrier(); 256 } 257 #else 258 template <class Tp> 259 inline BENCHMARK_ALWAYS_INLINE void DoNotOptimize(Tp const& value) { 260 internal::UseCharPointer(&reinterpret_cast<char const volatile&>(value)); 261 } 262 // FIXME Add ClobberMemory() for non-gnu and non-msvc compilers 263 #endif 264 265 266 267 // This class is used for user-defined counters. 268 class Counter { 269 public: 270 271 enum Flags { 272 kDefaults = 0, 273 // Mark the counter as a rate. It will be presented divided 274 // by the duration of the benchmark. 275 kIsRate = 1, 276 // Mark the counter as a thread-average quantity. It will be 277 // presented divided by the number of threads. 278 kAvgThreads = 2, 279 // Mark the counter as a thread-average rate. See above. 280 kAvgThreadsRate = kIsRate|kAvgThreads 281 }; 282 283 double value; 284 Flags flags; 285 286 BENCHMARK_ALWAYS_INLINE 287 Counter(double v = 0., Flags f = kDefaults) : value(v), flags(f) {} 288 289 BENCHMARK_ALWAYS_INLINE operator double const& () const { return value; } 290 BENCHMARK_ALWAYS_INLINE operator double & () { return value; } 291 292 }; 293 294 // This is the container for the user-defined counters. 295 typedef std::map<std::string, Counter> UserCounters; 296 297 298 // TimeUnit is passed to a benchmark in order to specify the order of magnitude 299 // for the measured time. 300 enum TimeUnit { kNanosecond, kMicrosecond, kMillisecond }; 301 302 // BigO is passed to a benchmark in order to specify the asymptotic 303 // computational 304 // complexity for the benchmark. In case oAuto is selected, complexity will be 305 // calculated automatically to the best fit. 306 enum BigO { oNone, o1, oN, oNSquared, oNCubed, oLogN, oNLogN, oAuto, oLambda }; 307 308 // BigOFunc is passed to a benchmark in order to specify the asymptotic 309 // computational complexity for the benchmark. 310 typedef double(BigOFunc)(int); 311 312 namespace internal { 313 class ThreadTimer; 314 class ThreadManager; 315 316 #if defined(BENCHMARK_HAS_CXX11) 317 enum ReportMode : unsigned { 318 #else 319 enum ReportMode { 320 #endif 321 RM_Unspecified, // The mode has not been manually specified 322 RM_Default, // The mode is user-specified as default. 323 RM_ReportAggregatesOnly 324 }; 325 } 326 327 // State is passed to a running Benchmark and contains state for the 328 // benchmark to use. 329 class State { 330 public: 331 // Returns true if the benchmark should continue through another iteration. 332 // NOTE: A benchmark may not return from the test until KeepRunning() has 333 // returned false. 334 bool KeepRunning() { 335 if (BENCHMARK_BUILTIN_EXPECT(!started_, false)) { 336 StartKeepRunning(); 337 } 338 bool const res = total_iterations_++ < max_iterations; 339 if (BENCHMARK_BUILTIN_EXPECT(!res, false)) { 340 FinishKeepRunning(); 341 } 342 return res; 343 } 344 345 // REQUIRES: timer is running and 'SkipWithError(...)' has not been called 346 // by the current thread. 347 // Stop the benchmark timer. If not called, the timer will be 348 // automatically stopped after KeepRunning() returns false for the first time. 349 // 350 // For threaded benchmarks the PauseTiming() function only pauses the timing 351 // for the current thread. 352 // 353 // NOTE: The "real time" measurement is per-thread. If different threads 354 // report different measurements the largest one is reported. 355 // 356 // NOTE: PauseTiming()/ResumeTiming() are relatively 357 // heavyweight, and so their use should generally be avoided 358 // within each benchmark iteration, if possible. 359 void PauseTiming(); 360 361 // REQUIRES: timer is not running and 'SkipWithError(...)' has not been called 362 // by the current thread. 363 // Start the benchmark timer. The timer is NOT running on entrance to the 364 // benchmark function. It begins running after the first call to KeepRunning() 365 // 366 // NOTE: PauseTiming()/ResumeTiming() are relatively 367 // heavyweight, and so their use should generally be avoided 368 // within each benchmark iteration, if possible. 369 void ResumeTiming(); 370 371 // REQUIRES: 'SkipWithError(...)' has not been called previously by the 372 // current thread. 373 // Skip any future iterations of the 'KeepRunning()' loop in the current 374 // thread and report an error with the specified 'msg'. After this call 375 // the user may explicitly 'return' from the benchmark. 376 // 377 // For threaded benchmarks only the current thread stops executing and future 378 // calls to `KeepRunning()` will block until all threads have completed 379 // the `KeepRunning()` loop. If multiple threads report an error only the 380 // first error message is used. 381 // 382 // NOTE: Calling 'SkipWithError(...)' does not cause the benchmark to exit 383 // the current scope immediately. If the function is called from within 384 // the 'KeepRunning()' loop the current iteration will finish. It is the users 385 // responsibility to exit the scope as needed. 386 void SkipWithError(const char* msg); 387 388 // REQUIRES: called exactly once per iteration of the KeepRunning loop. 389 // Set the manually measured time for this benchmark iteration, which 390 // is used instead of automatically measured time if UseManualTime() was 391 // specified. 392 // 393 // For threaded benchmarks the final value will be set to the largest 394 // reported values. 395 void SetIterationTime(double seconds); 396 397 // Set the number of bytes processed by the current benchmark 398 // execution. This routine is typically called once at the end of a 399 // throughput oriented benchmark. If this routine is called with a 400 // value > 0, the report is printed in MB/sec instead of nanoseconds 401 // per iteration. 402 // 403 // REQUIRES: a benchmark has exited its KeepRunning loop. 404 BENCHMARK_ALWAYS_INLINE 405 void SetBytesProcessed(size_t bytes) { bytes_processed_ = bytes; } 406 407 BENCHMARK_ALWAYS_INLINE 408 size_t bytes_processed() const { return bytes_processed_; } 409 410 // If this routine is called with complexity_n > 0 and complexity report is 411 // requested for the 412 // family benchmark, then current benchmark will be part of the computation 413 // and complexity_n will 414 // represent the length of N. 415 BENCHMARK_ALWAYS_INLINE 416 void SetComplexityN(int complexity_n) { complexity_n_ = complexity_n; } 417 418 BENCHMARK_ALWAYS_INLINE 419 int complexity_length_n() { return complexity_n_; } 420 421 // If this routine is called with items > 0, then an items/s 422 // label is printed on the benchmark report line for the currently 423 // executing benchmark. It is typically called at the end of a processing 424 // benchmark where a processing items/second output is desired. 425 // 426 // REQUIRES: a benchmark has exited its KeepRunning loop. 427 BENCHMARK_ALWAYS_INLINE 428 void SetItemsProcessed(size_t items) { items_processed_ = items; } 429 430 BENCHMARK_ALWAYS_INLINE 431 size_t items_processed() const { return items_processed_; } 432 433 // If this routine is called, the specified label is printed at the 434 // end of the benchmark report line for the currently executing 435 // benchmark. Example: 436 // static void BM_Compress(benchmark::State& state) { 437 // ... 438 // double compress = input_size / output_size; 439 // state.SetLabel(StringPrintf("compress:%.1f%%", 100.0*compression)); 440 // } 441 // Produces output that looks like: 442 // BM_Compress 50 50 14115038 compress:27.3% 443 // 444 // REQUIRES: a benchmark has exited its KeepRunning loop. 445 void SetLabel(const char* label); 446 447 void BENCHMARK_ALWAYS_INLINE SetLabel(const std::string& str) { 448 this->SetLabel(str.c_str()); 449 } 450 451 // Range arguments for this run. CHECKs if the argument has been set. 452 BENCHMARK_ALWAYS_INLINE 453 int range(std::size_t pos = 0) const { 454 assert(range_.size() > pos); 455 return range_[pos]; 456 } 457 458 BENCHMARK_DEPRECATED_MSG("use 'range(0)' instead") 459 int range_x() const { return range(0); } 460 461 BENCHMARK_DEPRECATED_MSG("use 'range(1)' instead") 462 int range_y() const { return range(1); } 463 464 BENCHMARK_ALWAYS_INLINE 465 size_t iterations() const { return total_iterations_; } 466 467 private: 468 bool started_; 469 bool finished_; 470 size_t total_iterations_; 471 472 std::vector<int> range_; 473 474 size_t bytes_processed_; 475 size_t items_processed_; 476 477 int complexity_n_; 478 479 bool error_occurred_; 480 481 public: 482 // Container for user-defined counters. 483 UserCounters counters; 484 // Index of the executing thread. Values from [0, threads). 485 const int thread_index; 486 // Number of threads concurrently executing the benchmark. 487 const int threads; 488 const size_t max_iterations; 489 490 // TODO make me private 491 State(size_t max_iters, const std::vector<int>& ranges, int thread_i, 492 int n_threads, internal::ThreadTimer* timer, 493 internal::ThreadManager* manager); 494 495 private: 496 void StartKeepRunning(); 497 void FinishKeepRunning(); 498 internal::ThreadTimer* timer_; 499 internal::ThreadManager* manager_; 500 BENCHMARK_DISALLOW_COPY_AND_ASSIGN(State); 501 }; 502 503 namespace internal { 504 505 typedef void(Function)(State&); 506 507 // ------------------------------------------------------ 508 // Benchmark registration object. The BENCHMARK() macro expands 509 // into an internal::Benchmark* object. Various methods can 510 // be called on this object to change the properties of the benchmark. 511 // Each method returns "this" so that multiple method calls can 512 // chained into one expression. 513 class Benchmark { 514 public: 515 virtual ~Benchmark(); 516 517 // Note: the following methods all return "this" so that multiple 518 // method calls can be chained together in one expression. 519 520 // Run this benchmark once with "x" as the extra argument passed 521 // to the function. 522 // REQUIRES: The function passed to the constructor must accept an arg1. 523 Benchmark* Arg(int x); 524 525 // Run this benchmark with the given time unit for the generated output report 526 Benchmark* Unit(TimeUnit unit); 527 528 // Run this benchmark once for a number of values picked from the 529 // range [start..limit]. (start and limit are always picked.) 530 // REQUIRES: The function passed to the constructor must accept an arg1. 531 Benchmark* Range(int start, int limit); 532 533 // Run this benchmark once for all values in the range [start..limit] with 534 // specific step 535 // REQUIRES: The function passed to the constructor must accept an arg1. 536 Benchmark* DenseRange(int start, int limit, int step = 1); 537 538 // Run this benchmark once with "args" as the extra arguments passed 539 // to the function. 540 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ... 541 Benchmark* Args(const std::vector<int>& args); 542 543 // Equivalent to Args({x, y}) 544 // NOTE: This is a legacy C++03 interface provided for compatibility only. 545 // New code should use 'Args'. 546 Benchmark* ArgPair(int x, int y) { 547 std::vector<int> args; 548 args.push_back(x); 549 args.push_back(y); 550 return Args(args); 551 } 552 553 // Run this benchmark once for a number of values picked from the 554 // ranges [start..limit]. (starts and limits are always picked.) 555 // REQUIRES: The function passed to the constructor must accept arg1, arg2 ... 556 Benchmark* Ranges(const std::vector<std::pair<int, int> >& ranges); 557 558 // Equivalent to ArgNames({name}) 559 Benchmark* ArgName(const std::string& name); 560 561 // Set the argument names to display in the benchmark name. If not called, 562 // only argument values will be shown. 563 Benchmark* ArgNames(const std::vector<std::string>& names); 564 565 // Equivalent to Ranges({{lo1, hi1}, {lo2, hi2}}). 566 // NOTE: This is a legacy C++03 interface provided for compatibility only. 567 // New code should use 'Ranges'. 568 Benchmark* RangePair(int lo1, int hi1, int lo2, int hi2) { 569 std::vector<std::pair<int, int> > ranges; 570 ranges.push_back(std::make_pair(lo1, hi1)); 571 ranges.push_back(std::make_pair(lo2, hi2)); 572 return Ranges(ranges); 573 } 574 575 // Pass this benchmark object to *func, which can customize 576 // the benchmark by calling various methods like Arg, Args, 577 // Threads, etc. 578 Benchmark* Apply(void (*func)(Benchmark* benchmark)); 579 580 // Set the range multiplier for non-dense range. If not called, the range 581 // multiplier kRangeMultiplier will be used. 582 Benchmark* RangeMultiplier(int multiplier); 583 584 // Set the minimum amount of time to use when running this benchmark. This 585 // option overrides the `benchmark_min_time` flag. 586 // REQUIRES: `t > 0` and `Iterations` has not been called on this benchmark. 587 Benchmark* MinTime(double t); 588 589 // Specify the amount of iterations that should be run by this benchmark. 590 // REQUIRES: 'n > 0' and `MinTime` has not been called on this benchmark. 591 // 592 // NOTE: This function should only be used when *exact* iteration control is 593 // needed and never to control or limit how long a benchmark runs, where 594 // `--benchmark_min_time=N` or `MinTime(...)` should be used instead. 595 Benchmark* Iterations(size_t n); 596 597 // Specify the amount of times to repeat this benchmark. This option overrides 598 // the `benchmark_repetitions` flag. 599 // REQUIRES: `n > 0` 600 Benchmark* Repetitions(int n); 601 602 // Specify if each repetition of the benchmark should be reported separately 603 // or if only the final statistics should be reported. If the benchmark 604 // is not repeated then the single result is always reported. 605 Benchmark* ReportAggregatesOnly(bool v = true); 606 607 // If a particular benchmark is I/O bound, runs multiple threads internally or 608 // if for some reason CPU timings are not representative, call this method. If 609 // called, the elapsed time will be used to control how many iterations are 610 // run, and in the printing of items/second or MB/seconds values. If not 611 // called, the cpu time used by the benchmark will be used. 612 Benchmark* UseRealTime(); 613 614 // If a benchmark must measure time manually (e.g. if GPU execution time is 615 // being 616 // measured), call this method. If called, each benchmark iteration should 617 // call 618 // SetIterationTime(seconds) to report the measured time, which will be used 619 // to control how many iterations are run, and in the printing of items/second 620 // or MB/second values. 621 Benchmark* UseManualTime(); 622 623 // Set the asymptotic computational complexity for the benchmark. If called 624 // the asymptotic computational complexity will be shown on the output. 625 Benchmark* Complexity(BigO complexity = benchmark::oAuto); 626 627 // Set the asymptotic computational complexity for the benchmark. If called 628 // the asymptotic computational complexity will be shown on the output. 629 Benchmark* Complexity(BigOFunc* complexity); 630 631 // Support for running multiple copies of the same benchmark concurrently 632 // in multiple threads. This may be useful when measuring the scaling 633 // of some piece of code. 634 635 // Run one instance of this benchmark concurrently in t threads. 636 Benchmark* Threads(int t); 637 638 // Pick a set of values T from [min_threads,max_threads]. 639 // min_threads and max_threads are always included in T. Run this 640 // benchmark once for each value in T. The benchmark run for a 641 // particular value t consists of t threads running the benchmark 642 // function concurrently. For example, consider: 643 // BENCHMARK(Foo)->ThreadRange(1,16); 644 // This will run the following benchmarks: 645 // Foo in 1 thread 646 // Foo in 2 threads 647 // Foo in 4 threads 648 // Foo in 8 threads 649 // Foo in 16 threads 650 Benchmark* ThreadRange(int min_threads, int max_threads); 651 652 // For each value n in the range, run this benchmark once using n threads. 653 // min_threads and max_threads are always included in the range. 654 // stride specifies the increment. E.g. DenseThreadRange(1, 8, 3) starts 655 // a benchmark with 1, 4, 7 and 8 threads. 656 Benchmark* DenseThreadRange(int min_threads, int max_threads, int stride = 1); 657 658 // Equivalent to ThreadRange(NumCPUs(), NumCPUs()) 659 Benchmark* ThreadPerCpu(); 660 661 virtual void Run(State& state) = 0; 662 663 // Used inside the benchmark implementation 664 struct Instance; 665 666 protected: 667 explicit Benchmark(const char* name); 668 Benchmark(Benchmark const&); 669 void SetName(const char* name); 670 671 int ArgsCnt() const; 672 673 static void AddRange(std::vector<int>* dst, int lo, int hi, int mult); 674 675 private: 676 friend class BenchmarkFamilies; 677 678 std::string name_; 679 ReportMode report_mode_; 680 std::vector<std::string> arg_names_; // Args for all benchmark runs 681 std::vector<std::vector<int> > args_; // Args for all benchmark runs 682 TimeUnit time_unit_; 683 int range_multiplier_; 684 double min_time_; 685 size_t iterations_; 686 int repetitions_; 687 bool use_real_time_; 688 bool use_manual_time_; 689 BigO complexity_; 690 BigOFunc* complexity_lambda_; 691 std::vector<int> thread_counts_; 692 693 Benchmark& operator=(Benchmark const&); 694 }; 695 696 } // namespace internal 697 698 // Create and register a benchmark with the specified 'name' that invokes 699 // the specified functor 'fn'. 700 // 701 // RETURNS: A pointer to the registered benchmark. 702 internal::Benchmark* RegisterBenchmark(const char* name, 703 internal::Function* fn); 704 705 #if defined(BENCHMARK_HAS_CXX11) 706 template <class Lambda> 707 internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn); 708 #endif 709 710 // Remove all registered benchmarks. All pointers to previously registered 711 // benchmarks are invalidated. 712 void ClearRegisteredBenchmarks(); 713 714 namespace internal { 715 // The class used to hold all Benchmarks created from static function. 716 // (ie those created using the BENCHMARK(...) macros. 717 class FunctionBenchmark : public Benchmark { 718 public: 719 FunctionBenchmark(const char* name, Function* func) 720 : Benchmark(name), func_(func) {} 721 722 virtual void Run(State& st); 723 724 private: 725 Function* func_; 726 }; 727 728 #ifdef BENCHMARK_HAS_CXX11 729 template <class Lambda> 730 class LambdaBenchmark : public Benchmark { 731 public: 732 virtual void Run(State& st) { lambda_(st); } 733 734 private: 735 template <class OLambda> 736 LambdaBenchmark(const char* name, OLambda&& lam) 737 : Benchmark(name), lambda_(std::forward<OLambda>(lam)) {} 738 739 LambdaBenchmark(LambdaBenchmark const&) = delete; 740 741 private: 742 template <class Lam> 743 friend Benchmark* ::benchmark::RegisterBenchmark(const char*, Lam&&); 744 745 Lambda lambda_; 746 }; 747 #endif 748 749 } // end namespace internal 750 751 inline internal::Benchmark* RegisterBenchmark(const char* name, 752 internal::Function* fn) { 753 return internal::RegisterBenchmarkInternal( 754 ::new internal::FunctionBenchmark(name, fn)); 755 } 756 757 #ifdef BENCHMARK_HAS_CXX11 758 template <class Lambda> 759 internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn) { 760 using BenchType = 761 internal::LambdaBenchmark<typename std::decay<Lambda>::type>; 762 return internal::RegisterBenchmarkInternal( 763 ::new BenchType(name, std::forward<Lambda>(fn))); 764 } 765 #endif 766 767 #if defined(BENCHMARK_HAS_CXX11) && \ 768 (!defined(BENCHMARK_GCC_VERSION) || BENCHMARK_GCC_VERSION >= 409) 769 template <class Lambda, class... Args> 770 internal::Benchmark* RegisterBenchmark(const char* name, Lambda&& fn, 771 Args&&... args) { 772 return benchmark::RegisterBenchmark( 773 name, [=](benchmark::State& st) { fn(st, args...); }); 774 } 775 #else 776 #define BENCHMARK_HAS_NO_VARIADIC_REGISTER_BENCHMARK 777 #endif 778 779 // The base class for all fixture tests. 780 class Fixture : public internal::Benchmark { 781 public: 782 Fixture() : internal::Benchmark("") {} 783 784 virtual void Run(State& st) { 785 this->SetUp(st); 786 this->BenchmarkCase(st); 787 this->TearDown(st); 788 } 789 790 // These will be deprecated ... 791 virtual void SetUp(const State&) {} 792 virtual void TearDown(const State&) {} 793 // ... In favor of these. 794 virtual void SetUp(State& st) { SetUp(const_cast<const State&>(st)); } 795 virtual void TearDown(State& st) { TearDown(const_cast<const State&>(st)); } 796 797 protected: 798 virtual void BenchmarkCase(State&) = 0; 799 }; 800 801 } // end namespace benchmark 802 803 // ------------------------------------------------------ 804 // Macro to register benchmarks 805 806 // Check that __COUNTER__ is defined and that __COUNTER__ increases by 1 807 // every time it is expanded. X + 1 == X + 0 is used in case X is defined to be 808 // empty. If X is empty the expression becomes (+1 == +0). 809 #if defined(__COUNTER__) && (__COUNTER__ + 1 == __COUNTER__ + 0) 810 #define BENCHMARK_PRIVATE_UNIQUE_ID __COUNTER__ 811 #else 812 #define BENCHMARK_PRIVATE_UNIQUE_ID __LINE__ 813 #endif 814 815 // Helpers for generating unique variable names 816 #define BENCHMARK_PRIVATE_NAME(n) \ 817 BENCHMARK_PRIVATE_CONCAT(_benchmark_, BENCHMARK_PRIVATE_UNIQUE_ID, n) 818 #define BENCHMARK_PRIVATE_CONCAT(a, b, c) BENCHMARK_PRIVATE_CONCAT2(a, b, c) 819 #define BENCHMARK_PRIVATE_CONCAT2(a, b, c) a##b##c 820 821 #define BENCHMARK_PRIVATE_DECLARE(n) \ 822 static ::benchmark::internal::Benchmark* BENCHMARK_PRIVATE_NAME(n) \ 823 BENCHMARK_UNUSED 824 825 #define BENCHMARK(n) \ 826 BENCHMARK_PRIVATE_DECLARE(n) = \ 827 (::benchmark::internal::RegisterBenchmarkInternal( \ 828 new ::benchmark::internal::FunctionBenchmark(#n, n))) 829 830 // Old-style macros 831 #define BENCHMARK_WITH_ARG(n, a) BENCHMARK(n)->Arg((a)) 832 #define BENCHMARK_WITH_ARG2(n, a1, a2) BENCHMARK(n)->Args({(a1), (a2)}) 833 #define BENCHMARK_WITH_UNIT(n, t) BENCHMARK(n)->Unit((t)) 834 #define BENCHMARK_RANGE(n, lo, hi) BENCHMARK(n)->Range((lo), (hi)) 835 #define BENCHMARK_RANGE2(n, l1, h1, l2, h2) \ 836 BENCHMARK(n)->RangePair({{(l1), (h1)}, {(l2), (h2)}}) 837 838 #if __cplusplus >= 201103L 839 840 // Register a benchmark which invokes the function specified by `func` 841 // with the additional arguments specified by `...`. 842 // 843 // For example: 844 // 845 // template <class ...ExtraArgs>` 846 // void BM_takes_args(benchmark::State& state, ExtraArgs&&... extra_args) { 847 // [...] 848 //} 849 // /* Registers a benchmark named "BM_takes_args/int_string_test` */ 850 // BENCHMARK_CAPTURE(BM_takes_args, int_string_test, 42, std::string("abc")); 851 #define BENCHMARK_CAPTURE(func, test_case_name, ...) \ 852 BENCHMARK_PRIVATE_DECLARE(func) = \ 853 (::benchmark::internal::RegisterBenchmarkInternal( \ 854 new ::benchmark::internal::FunctionBenchmark( \ 855 #func "/" #test_case_name, \ 856 [](::benchmark::State& st) { func(st, __VA_ARGS__); }))) 857 858 #endif // __cplusplus >= 11 859 860 // This will register a benchmark for a templatized function. For example: 861 // 862 // template<int arg> 863 // void BM_Foo(int iters); 864 // 865 // BENCHMARK_TEMPLATE(BM_Foo, 1); 866 // 867 // will register BM_Foo<1> as a benchmark. 868 #define BENCHMARK_TEMPLATE1(n, a) \ 869 BENCHMARK_PRIVATE_DECLARE(n) = \ 870 (::benchmark::internal::RegisterBenchmarkInternal( \ 871 new ::benchmark::internal::FunctionBenchmark(#n "<" #a ">", n<a>))) 872 873 #define BENCHMARK_TEMPLATE2(n, a, b) \ 874 BENCHMARK_PRIVATE_DECLARE(n) = \ 875 (::benchmark::internal::RegisterBenchmarkInternal( \ 876 new ::benchmark::internal::FunctionBenchmark(#n "<" #a "," #b ">", \ 877 n<a, b>))) 878 879 #if __cplusplus >= 201103L 880 #define BENCHMARK_TEMPLATE(n, ...) \ 881 BENCHMARK_PRIVATE_DECLARE(n) = \ 882 (::benchmark::internal::RegisterBenchmarkInternal( \ 883 new ::benchmark::internal::FunctionBenchmark( \ 884 #n "<" #__VA_ARGS__ ">", n<__VA_ARGS__>))) 885 #else 886 #define BENCHMARK_TEMPLATE(n, a) BENCHMARK_TEMPLATE1(n, a) 887 #endif 888 889 #define BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \ 890 class BaseClass##_##Method##_Benchmark : public BaseClass { \ 891 public: \ 892 BaseClass##_##Method##_Benchmark() : BaseClass() { \ 893 this->SetName(#BaseClass "/" #Method); \ 894 } \ 895 \ 896 protected: \ 897 virtual void BenchmarkCase(::benchmark::State&); \ 898 }; 899 900 #define BENCHMARK_DEFINE_F(BaseClass, Method) \ 901 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \ 902 void BaseClass##_##Method##_Benchmark::BenchmarkCase 903 904 #define BENCHMARK_REGISTER_F(BaseClass, Method) \ 905 BENCHMARK_PRIVATE_REGISTER_F(BaseClass##_##Method##_Benchmark) 906 907 #define BENCHMARK_PRIVATE_REGISTER_F(TestName) \ 908 BENCHMARK_PRIVATE_DECLARE(TestName) = \ 909 (::benchmark::internal::RegisterBenchmarkInternal(new TestName())) 910 911 // This macro will define and register a benchmark within a fixture class. 912 #define BENCHMARK_F(BaseClass, Method) \ 913 BENCHMARK_PRIVATE_DECLARE_F(BaseClass, Method) \ 914 BENCHMARK_REGISTER_F(BaseClass, Method); \ 915 void BaseClass##_##Method##_Benchmark::BenchmarkCase 916 917 // Helper macro to create a main routine in a test that runs the benchmarks 918 #define BENCHMARK_MAIN() \ 919 int main(int argc, char** argv) { \ 920 ::benchmark::Initialize(&argc, argv); \ 921 if (::benchmark::ReportUnrecognizedArguments(argc, argv)) return 1; \ 922 ::benchmark::RunSpecifiedBenchmarks(); \ 923 } 924 925 #endif // BENCHMARK_BENCHMARK_API_H_ 926