"Fossies" - the Fresh Open Source Software Archive

Member "xxHash-0.8.0/tests/bench/benchfn.h" (27 Jul 2020, 8724 Bytes) of package /linux/misc/xxHash-0.8.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "benchfn.h": 0.7.3_vs_0.7.4.

    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