2 * Copyright 2014 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef FOLLY_BENCHMARK_H_
18 #define FOLLY_BENCHMARK_H_
20 #include "folly/Portability.h"
21 #include "folly/Preprocessor.h" // for FB_ANONYMOUS_VARIABLE
24 #include <boost/function_types/function_arity.hpp>
26 #include <glog/logging.h>
27 #include <gflags/gflags.h>
30 DECLARE_bool(benchmark);
35 * Runs all benchmarks defined. Usually put in main().
40 * Runs all benchmarks defined if and only if the --benchmark flag has
41 * been passed to the program. Usually put in main().
43 inline bool runBenchmarksOnFlag() {
44 if (FLAGS_benchmark) {
47 return FLAGS_benchmark;
53 * This is the clock ID used for measuring time. On older kernels, the
54 * resolution of this clock will be very coarse, which will cause the
57 enum Clock { DEFAULT_CLOCK_ID = CLOCK_REALTIME };
60 * Adds a benchmark wrapped in a std::function. Only used
61 * internally. Pass by value is intentional.
63 void addBenchmarkImpl(const char* file,
65 std::function<uint64_t(unsigned int)>);
68 * Takes the difference between two timespec values. end is assumed to
71 inline uint64_t timespecDiff(timespec end, timespec start) {
72 if (end.tv_sec == start.tv_sec) {
73 assert(end.tv_nsec >= start.tv_nsec);
74 return end.tv_nsec - start.tv_nsec;
76 assert(end.tv_sec > start.tv_sec &&
77 end.tv_sec - start.tv_sec <
78 std::numeric_limits<uint64_t>::max() / 1000000000UL);
79 return (end.tv_sec - start.tv_sec) * 1000000000UL
80 + end.tv_nsec - start.tv_nsec;
84 * Takes the difference between two sets of timespec values. The first
85 * two come from a high-resolution clock whereas the other two come
86 * from a low-resolution clock. The crux of the matter is that
87 * high-res values may be bogus as documented in
88 * http://linux.die.net/man/3/clock_gettime. The trouble is when the
89 * running process migrates from one CPU to another, which is more
90 * likely for long-running processes. Therefore we watch for high
91 * differences between the two timings.
93 * This function is subject to further improvements.
95 inline uint64_t timespecDiff(timespec end, timespec start,
96 timespec endCoarse, timespec startCoarse) {
97 auto fine = timespecDiff(end, start);
98 auto coarse = timespecDiff(endCoarse, startCoarse);
99 if (coarse - fine >= 1000000) {
100 // The fine time is in all likelihood bogus
106 } // namespace detail
109 * Supporting type for BENCHMARK_SUSPEND defined below.
111 struct BenchmarkSuspender {
112 BenchmarkSuspender() {
113 CHECK_EQ(0, clock_gettime(detail::DEFAULT_CLOCK_ID, &start));
116 BenchmarkSuspender(const BenchmarkSuspender &) = delete;
117 BenchmarkSuspender(BenchmarkSuspender && rhs) {
119 rhs.start.tv_nsec = rhs.start.tv_sec = 0;
122 BenchmarkSuspender& operator=(const BenchmarkSuspender &) = delete;
123 BenchmarkSuspender& operator=(BenchmarkSuspender && rhs) {
124 if (start.tv_nsec > 0 || start.tv_sec > 0) {
128 rhs.start.tv_nsec = rhs.start.tv_sec = 0;
132 ~BenchmarkSuspender() {
133 if (start.tv_nsec > 0 || start.tv_sec > 0) {
139 assert(start.tv_nsec > 0 || start.tv_sec > 0);
141 start.tv_nsec = start.tv_sec = 0;
145 assert(start.tv_nsec == 0 || start.tv_sec == 0);
146 CHECK_EQ(0, clock_gettime(detail::DEFAULT_CLOCK_ID, &start));
150 * This helps the macro definition. To get around the dangers of
151 * operator bool, returns a pointer to member (which allows no
154 operator int BenchmarkSuspender::*() const {
159 * Accumulates nanoseconds spent outside benchmark.
161 typedef uint64_t NanosecondsSpent;
162 static NanosecondsSpent nsSpent;
167 CHECK_EQ(0, clock_gettime(detail::DEFAULT_CLOCK_ID, &end));
168 nsSpent += detail::timespecDiff(end, start);
176 * Adds a benchmark. Usually not called directly but instead through
177 * the macro BENCHMARK defined below. The lambda function involved
178 * must take exactly one parameter of type unsigned, and the benchmark
179 * uses it with counter semantics (iteration occurs inside the
182 template <typename Lambda>
183 typename std::enable_if<
184 boost::function_types::function_arity<decltype(&Lambda::operator())>::value
187 addBenchmark(const char* file, const char* name, Lambda&& lambda) {
188 auto execute = [=](unsigned int times) -> uint64_t {
189 BenchmarkSuspender::nsSpent = 0;
192 // CORE MEASUREMENT STARTS
193 auto const r1 = clock_gettime(detail::DEFAULT_CLOCK_ID, &start);
195 auto const r2 = clock_gettime(detail::DEFAULT_CLOCK_ID, &end);
196 // CORE MEASUREMENT ENDS
201 return detail::timespecDiff(end, start) - BenchmarkSuspender::nsSpent;
204 detail::addBenchmarkImpl(file, name,
205 std::function<uint64_t(unsigned int)>(execute));
209 * Adds a benchmark. Usually not called directly but instead through
210 * the macro BENCHMARK defined below. The lambda function involved
211 * must take zero parameters, and the benchmark calls it repeatedly
212 * (iteration occurs outside the function).
214 template <typename Lambda>
215 typename std::enable_if<
216 boost::function_types::function_arity<decltype(&Lambda::operator())>::value
219 addBenchmark(const char* file, const char* name, Lambda&& lambda) {
220 addBenchmark(file, name, [=](unsigned int times) {
221 while (times-- > 0) {
228 * Call doNotOptimizeAway(var) against variables that you use for
229 * benchmarking but otherwise are useless. The compiler tends to do a
230 * good job at eliminating unused variables, and this function fools
231 * it into thinking var is in fact needed.
235 #pragma optimize("", off)
238 void doNotOptimizeAway(T&& datum) {
242 #pragma optimize("", on)
246 void doNotOptimizeAway(T&& datum) {
247 asm volatile("" : "+r" (datum));
254 * Introduces a benchmark function. Used internally, see BENCHMARK and
257 #define BENCHMARK_IMPL(funName, stringName, paramType, paramName) \
258 static void funName(paramType); \
259 static bool FB_ANONYMOUS_VARIABLE(follyBenchmarkUnused) = ( \
260 ::folly::addBenchmark(__FILE__, stringName, \
261 [](paramType paramName) { funName(paramName); }), \
263 static void funName(paramType paramName)
266 * Introduces a benchmark function. Use with either one one or two
267 * arguments. The first is the name of the benchmark. Use something
268 * descriptive, such as insertVectorBegin. The second argument may be
269 * missing, or could be a symbolic counter. The counter dictates how
270 * many internal iteration the benchmark does. Example:
272 * BENCHMARK(vectorPushBack) {
277 * BENCHMARK(insertVectorBegin, n) {
279 * FOR_EACH_RANGE (i, 0, n) {
280 * v.insert(v.begin(), 42);
284 #define BENCHMARK(name, ...) \
287 FB_STRINGIZE(name), \
288 FB_ONE_OR_NONE(unsigned, ## __VA_ARGS__), \
292 * Defines a benchmark that passes a parameter to another one. This is
293 * common for benchmarks that need a "problem size" in addition to
294 * "number of iterations". Consider:
296 * void pushBack(uint n, size_t initialSize) {
298 * BENCHMARK_SUSPEND {
299 * v.resize(initialSize);
301 * FOR_EACH_RANGE (i, 0, n) {
305 * BENCHMARK_PARAM(pushBack, 0)
306 * BENCHMARK_PARAM(pushBack, 1000)
307 * BENCHMARK_PARAM(pushBack, 1000000)
309 * The benchmark above estimates the speed of push_back at different
310 * initial sizes of the vector. The framework will pass 0, 1000, and
311 * 1000000 for initialSize, and the iteration count for n.
313 #define BENCHMARK_PARAM(name, param) \
314 BENCHMARK_NAMED_PARAM(name, param, param)
317 * Like BENCHMARK_PARAM(), but allows a custom name to be specified for each
318 * parameter, rather than using the parameter value.
320 * Useful when the parameter value is not a valid token for string pasting,
321 * of when you want to specify multiple parameter arguments.
325 * void addValue(uint n, int64_t bucketSize, int64_t min, int64_t max) {
326 * Histogram<int64_t> hist(bucketSize, min, max);
328 * FOR_EACH_RANGE (i, 0, n) {
329 * hist.addValue(num);
331 * if (num > max) { num = min; }
335 * BENCHMARK_NAMED_PARAM(addValue, 0_to_100, 1, 0, 100)
336 * BENCHMARK_NAMED_PARAM(addValue, 0_to_1000, 10, 0, 1000)
337 * BENCHMARK_NAMED_PARAM(addValue, 5k_to_20k, 250, 5000, 20000)
339 #define BENCHMARK_NAMED_PARAM(name, param_name, ...) \
341 FB_CONCATENATE(name, FB_CONCATENATE(_, param_name)), \
342 FB_STRINGIZE(name) "(" FB_STRINGIZE(param_name) ")", \
345 name(iters, ## __VA_ARGS__); \
349 * Just like BENCHMARK, but prints the time relative to a
350 * baseline. The baseline is the most recent BENCHMARK() seen in
351 * lexical order. Example:
353 * // This is the baseline
354 * BENCHMARK(insertVectorBegin, n) {
356 * FOR_EACH_RANGE (i, 0, n) {
357 * v.insert(v.begin(), 42);
361 * BENCHMARK_RELATIVE(insertListBegin, n) {
363 * FOR_EACH_RANGE (i, 0, n) {
364 * s.insert(s.begin(), 42);
368 * Any number of relative benchmark can be associated with a
369 * baseline. Another BENCHMARK() occurrence effectively establishes a
372 #define BENCHMARK_RELATIVE(name, ...) \
375 "%" FB_STRINGIZE(name), \
376 FB_ONE_OR_NONE(unsigned, ## __VA_ARGS__), \
380 * A combination of BENCHMARK_RELATIVE and BENCHMARK_PARAM.
382 #define BENCHMARK_RELATIVE_PARAM(name, param) \
383 BENCHMARK_RELATIVE_NAMED_PARAM(name, param, param)
386 * A combination of BENCHMARK_RELATIVE and BENCHMARK_NAMED_PARAM.
388 #define BENCHMARK_RELATIVE_NAMED_PARAM(name, param_name, ...) \
390 FB_CONCATENATE(name, FB_CONCATENATE(_, param_name)), \
391 "%" FB_STRINGIZE(name) "(" FB_STRINGIZE(param_name) ")", \
394 name(iters, ## __VA_ARGS__); \
398 * Draws a line of dashes.
400 #define BENCHMARK_DRAW_LINE() \
401 static bool FB_ANONYMOUS_VARIABLE(follyBenchmarkUnused) = ( \
402 ::folly::addBenchmark(__FILE__, "-", []() { }), \
406 * Allows execution of code that doesn't count torward the benchmark's
407 * time budget. Example:
409 * BENCHMARK_START_GROUP(insertVectorBegin, n) {
411 * BENCHMARK_SUSPEND {
414 * FOR_EACH_RANGE (i, 0, n) {
415 * v.insert(v.begin(), 42);
419 #define BENCHMARK_SUSPEND \
420 if (auto FB_ANONYMOUS_VARIABLE(BENCHMARK_SUSPEND) = \
421 ::folly::BenchmarkSuspender()) {} \
424 #endif // FOLLY_BENCHMARK_H_