1 /* 2 * Copyright (c) 2016-2020, Yann Collet, Facebook, Inc. 3 * All rights reserved. 4 * 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. 9 */ 10 11 12 /* benchfn : 13 * benchmark any function on a set of input 14 * providing result in nanoSecPerRun 15 * or detecting and returning an error 16 */ 17 18 #if defined (__cplusplus) 19 extern "C" { 20 #endif 21 22 #ifndef BENCH_FN_H_23876 23 #define BENCH_FN_H_23876 24 25 /* === Dependencies === */ 26 #include <stddef.h> /* size_t */ 27 28 29 /* ==== Benchmark any function, iterated on a set of blocks ==== */ 30 31 /* BMK_runTime_t: valid result return type */ 32 33 typedef struct { 34 double nanoSecPerRun; /* time per iteration (over all blocks) */ 35 size_t sumOfReturn; /* sum of return values */ 36 } BMK_runTime_t; 37 38 39 /* BMK_runOutcome_t: 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. */ 47 48 typedef struct { 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; 52 } BMK_runOutcome_t; 53 54 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); 59 60 61 /* BMK_benchFunction() parameters are provided via the following structure. 62 * A structure is preferable for readability, 63 * as the number of parameters required is fairly large. 64 * No initializer is provided, because it doesn't make sense to provide some "default" : 65 * all parameters must be specified by the caller. 66 * optional parameters are labelled explicitly, and accept value NULL when not used */ 67 typedef struct { 68 BMK_benchFn_t benchFn; /* the function to benchmark, over the set of blocks */ 69 void* benchPayload; /* pass custom parameters to benchFn : 70 * (*benchFn)(srcBuffers[i], srcSizes[i], dstBuffers[i], dstCapacities[i], benchPayload) */ 71 BMK_initFn_t initFn; /* (*initFn)(initPayload) is run once per run, at the beginning. */ 72 void* initPayload; /* Both arguments can be NULL, in which case nothing is run. */ 73 BMK_errorFn_t errorFn; /* errorFn will check each return value of benchFn over each block, to determine if it failed or not. 74 * errorFn can be NULL, in which case no check is performed. 75 * errorFn must return 0 when benchFn was successful, and >= 1 if it detects an error. 76 * Execution is stopped as soon as an error is detected. 77 * the triggering return value can be retrieved using BMK_extract_errorResult(). */ 78 size_t blockCount; /* number of blocks to operate benchFn on. 79 * It's also the size of all array parameters : 80 * srcBuffers, srcSizes, dstBuffers, dstCapacities, blockResults */ 81 const void *const * srcBuffers; /* read-only array of buffers to be operated on by benchFn */ 82 const size_t* srcSizes; /* read-only array containing sizes of srcBuffers */ 83 void *const * dstBuffers; /* array of buffers to be written into by benchFn. This array is not optional, it must be provided even if unused by benchfn. */ 84 const size_t* dstCapacities; /* read-only array containing capacities of dstBuffers. This array must be present. */ 85 size_t* blockResults; /* Optional: store the return value of benchFn for each block. Use NULL if this result is not requested. */ 86 } BMK_benchParams_t; 87 88 89 /* BMK_benchFunction() : 90 * This function benchmarks benchFn and initFn, providing a result. 91 * 92 * params : see description of BMK_benchParams_t above. 93 * nbLoops: defines number of times benchFn is run over the full set of blocks. 94 * Minimum value is 1. A 0 is interpreted as a 1. 95 * 96 * @return: can express either an error or a successful result. 97 * Use BMK_isSuccessful_runOutcome() to check if benchmark was successful. 98 * If yes, extract the result with BMK_extract_runTime(), 99 * it will contain : 100 * .sumOfReturn : the sum of all return values of benchFn through all of blocks 101 * .nanoSecPerRun : time per run of benchFn + (time for initFn / nbLoops) 102 * .sumOfReturn is generally intended for functions which return a # of bytes written into dstBuffer, 103 * in which case, this value will be the total amount of bytes written into dstBuffer. 104 * 105 * blockResults : when provided (!= NULL), and when benchmark is successful, 106 * params.blockResults contains all return values of `benchFn` over all blocks. 107 * when provided (!= NULL), and when benchmark failed, 108 * params.blockResults contains return values of `benchFn` over all blocks preceding and including the failed block. 109 */ 110 BMK_runOutcome_t BMK_benchFunction(BMK_benchParams_t params, unsigned nbLoops); 111 112 113 114 /* check first if the benchmark was successful or not */ 115 int BMK_isSuccessful_runOutcome(BMK_runOutcome_t outcome); 116 117 /* If the benchmark was successful, extract the result. 118 * note : this function will abort() program execution if benchmark failed ! 119 * always check if benchmark was successful first ! 120 */ 121 BMK_runTime_t BMK_extract_runTime(BMK_runOutcome_t outcome); 122 123 /* when benchmark failed, it means one invocation of `benchFn` failed. 124 * The failure was detected by `errorFn`, operating on return values of `benchFn`. 125 * Returns the faulty return value. 126 * note : this function will abort() program execution if benchmark did not failed. 127 * always check if benchmark failed first ! 128 */ 129 size_t BMK_extract_errorResult(BMK_runOutcome_t outcome); 130 131 132 133 /* ==== Benchmark any function, returning intermediate results ==== */ 134 135 /* state information tracking benchmark session */ 136 typedef struct BMK_timedFnState_s BMK_timedFnState_t; 137 138 /* BMK_benchTimedFn() : 139 * Similar to BMK_benchFunction(), most arguments being identical. 140 * Automatically determines `nbLoops` so that each result is regularly produced at interval of about run_ms. 141 * Note : minimum `nbLoops` is 1, therefore a run may last more than run_ms, and possibly even more than total_ms. 142 * Usage - initialize timedFnState, select benchmark duration (total_ms) and each measurement duration (run_ms) 143 * call BMK_benchTimedFn() repetitively, each measurement is supposed to last about run_ms 144 * Check if total time budget is spent or exceeded, using BMK_isCompleted_TimedFn() 145 */ 146 BMK_runOutcome_t BMK_benchTimedFn(BMK_timedFnState_t* timedFnState, 147 BMK_benchParams_t params); 148 149 /* Tells if duration of all benchmark runs has exceeded total_ms 150 */ 151 int BMK_isCompleted_TimedFn(const BMK_timedFnState_t* timedFnState); 152 153 /* BMK_createTimedFnState() and BMK_resetTimedFnState() : 154 * Create/Set BMK_timedFnState_t for next benchmark session, 155 * which shall last a minimum of total_ms milliseconds, 156 * producing intermediate results, paced at interval of (approximately) run_ms. 157 */ 158 BMK_timedFnState_t* BMK_createTimedFnState(unsigned total_ms, unsigned run_ms); 159 void BMK_resetTimedFnState(BMK_timedFnState_t* timedFnState, unsigned total_ms, unsigned run_ms); 160 void BMK_freeTimedFnState(BMK_timedFnState_t* state); 161 162 163 /* BMK_timedFnState_shell and BMK_initStatic_timedFnState() : 164 * Makes it possible to statically allocate a BMK_timedFnState_t on stack. 165 * BMK_timedFnState_shell is only there to allocate space, 166 * never ever access its members. 167 * BMK_timedFnState_t() actually accepts any buffer. 168 * It will check if provided buffer is large enough and is correctly aligned, 169 * and will return NULL if conditions are not respected. 170 */ 171 #define BMK_TIMEDFNSTATE_SIZE 64 172 typedef union { 173 char never_access_space[BMK_TIMEDFNSTATE_SIZE]; 174 long long alignment_enforcer; /* must be aligned on 8-bytes boundaries */ 175 } BMK_timedFnState_shell; 176 BMK_timedFnState_t* BMK_initStatic_timedFnState(void* buffer, size_t size, unsigned total_ms, unsigned run_ms); 177 178 179 #endif /* BENCH_FN_H_23876 */ 180 181 #if defined (__cplusplus) 182 } 183 #endif 184