2 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
5 * This source code is licensed under both the BSD-style license (found in the
6 * LICENSE file in the root directory of this source tree) and the GPLv2 (found
7 * in the COPYING file in the root directory of this source tree).
8 * You may select, at your option, one of the above-listed licenses.
13 * benchmark any function on a set of input
14 * providing result in nanoSecPerRun
15 * or detecting and returning an error
18 #if defined (__cplusplus)
22 #ifndef BENCH_FN_H_23876
23 #define BENCH_FN_H_23876
25 /* === Dependencies === */
26 #include <stddef.h> /* size_t */
29 /* ==== Benchmark any function, iterated on a set of blocks ==== */
31 /* BMK_runTime_t: valid result return type */
34 unsigned long long nanoSecPerRun; /* time per iteration (over all blocks) */
35 size_t sumOfReturn; /* sum of return values */
40 * type expressing the outcome of a benchmark run by BMK_benchFunction(),
41 * which can be either valid or invalid.
42 * benchmark outcome can be invalid if errorFn is provided.
43 * BMK_runOutcome_t must be considered "opaque" : never access its members directly.
44 * Instead, use its assigned methods :
45 * BMK_isSuccessful_runOutcome, BMK_extract_runTime, BMK_extract_errorResult.
46 * The structure is only described here to allow its allocation on stack. */
49 BMK_runTime_t internal_never_ever_use_directly;
50 size_t error_result_never_ever_use_directly;
51 int error_tag_never_ever_use_directly;
55 /* prototypes for benchmarked functions */
56 typedef size_t (*BMK_benchFn_t)(const void* src, size_t srcSize, void* dst, size_t dstCapacity, void* customPayload);
57 typedef size_t (*BMK_initFn_t)(void* initPayload);
58 typedef unsigned (*BMK_errorFn_t)(size_t);
61 /* BMK_benchFunction() parameters are provided through following structure.
62 * This is preferable for readability,
63 * as the number of parameters required is pretty large.
64 * No initializer is provided, because it doesn't make sense to provide some "default" :
65 * all parameters should be specified by the caller */
67 BMK_benchFn_t benchFn; /* the function to benchmark, over the set of blocks */
68 void* benchPayload; /* pass custom parameters to benchFn :
69 * (*benchFn)(srcBuffers[i], srcSizes[i], dstBuffers[i], dstCapacities[i], benchPayload) */
70 BMK_initFn_t initFn; /* (*initFn)(initPayload) is run once per run, at the beginning. */
71 void* initPayload; /* Both arguments can be NULL, in which case nothing is run. */
72 BMK_errorFn_t errorFn; /* errorFn will check each return value of benchFn over each block, to determine if it failed or not.
73 * errorFn can be NULL, in which case no check is performed.
74 * errorFn must return 0 when benchFn was successful, and >= 1 if it detects an error.
75 * Execution is stopped as soon as an error is detected.
76 * the triggering return value can be retrieved using BMK_extract_errorResult(). */
77 size_t blockCount; /* number of blocks to operate benchFn on.
78 * It's also the size of all array parameters :
79 * srcBuffers, srcSizes, dstBuffers, dstCapacities, blockResults */
80 const void *const * srcBuffers; /* array of buffers to be operated on by benchFn */
81 const size_t* srcSizes; /* array of the sizes of srcBuffers buffers */
82 void *const * dstBuffers;/* array of buffers to be written into by benchFn */
83 const size_t* dstCapacities; /* array of the capacities of dstBuffers buffers */
84 size_t* blockResults; /* Optional: store the return value of benchFn for each block. Use NULL if this result is not requested. */
88 /* BMK_benchFunction() :
89 * This function benchmarks benchFn and initFn, providing a result.
91 * params : see description of BMK_benchParams_t above.
92 * nbLoops: defines number of times benchFn is run over the full set of blocks.
93 * Minimum value is 1. A 0 is interpreted as a 1.
95 * @return: can express either an error or a successful result.
96 * Use BMK_isSuccessful_runOutcome() to check if benchmark was successful.
97 * If yes, extract the result with BMK_extract_runTime(),
99 * .sumOfReturn : the sum of all return values of benchFn through all of blocks
100 * .nanoSecPerRun : time per run of benchFn + (time for initFn / nbLoops)
101 * .sumOfReturn is generally intended for functions which return a # of bytes written into dstBuffer,
102 * in which case, this value will be the total amount of bytes written into dstBuffer.
104 * blockResults : when provided (!= NULL), and when benchmark is successful,
105 * params.blockResults contains all return values of `benchFn` over all blocks.
106 * when provided (!= NULL), and when benchmark failed,
107 * params.blockResults contains return values of `benchFn` over all blocks preceding and including the failed block.
109 BMK_runOutcome_t BMK_benchFunction(BMK_benchParams_t params, unsigned nbLoops);
113 /* check first if the benchmark was successful or not */
114 int BMK_isSuccessful_runOutcome(BMK_runOutcome_t outcome);
116 /* If the benchmark was successful, extract the result.
117 * note : this function will abort() program execution if benchmark failed !
118 * always check if benchmark was successful first !
120 BMK_runTime_t BMK_extract_runTime(BMK_runOutcome_t outcome);
122 /* when benchmark failed, it means one invocation of `benchFn` failed.
123 * The failure was detected by `errorFn`, operating on return values of `benchFn`.
124 * Returns the faulty return value.
125 * note : this function will abort() program execution if benchmark did not failed.
126 * always check if benchmark failed first !
128 size_t BMK_extract_errorResult(BMK_runOutcome_t outcome);
132 /* ==== Benchmark any function, returning intermediate results ==== */
134 /* state information tracking benchmark session */
135 typedef struct BMK_timedFnState_s BMK_timedFnState_t;
137 /* BMK_benchTimedFn() :
138 * Similar to BMK_benchFunction(), most arguments being identical.
139 * Automatically determines `nbLoops` so that each result is regularly produced at interval of about run_ms.
140 * Note : minimum `nbLoops` is 1, therefore a run may last more than run_ms, and possibly even more than total_ms.
141 * Usage - initialize timedFnState, select benchmark duration (total_ms) and each measurement duration (run_ms)
142 * call BMK_benchTimedFn() repetitively, each measurement is supposed to last about run_ms
143 * Check if total time budget is spent or exceeded, using BMK_isCompleted_TimedFn()
145 BMK_runOutcome_t BMK_benchTimedFn(BMK_timedFnState_t* timedFnState,
146 BMK_benchParams_t params);
148 /* Tells if duration of all benchmark runs has exceeded total_ms
150 int BMK_isCompleted_TimedFn(const BMK_timedFnState_t* timedFnState);
152 /* BMK_createTimedFnState() and BMK_resetTimedFnState() :
153 * Create/Set BMK_timedFnState_t for next benchmark session,
154 * which shall last a minimum of total_ms milliseconds,
155 * producing intermediate results, paced at interval of (approximately) run_ms.
157 BMK_timedFnState_t* BMK_createTimedFnState(unsigned total_ms, unsigned run_ms);
158 void BMK_resetTimedFnState(BMK_timedFnState_t* timedFnState, unsigned total_ms, unsigned run_ms);
159 void BMK_freeTimedFnState(BMK_timedFnState_t* state);
163 #endif /* BENCH_FN_H_23876 */
165 #if defined (__cplusplus)