/* * Copyright (c) 2016-present, Yann Collet, Facebook, Inc. * All rights reserved. * * This source code is licensed under both the BSD-style license (found in the * LICENSE file in the root directory of this source tree) and the GPLv2 (found * in the COPYING file in the root directory of this source tree). * You may select, at your option, one of the above-listed licenses. */ #if defined (__cplusplus) extern "C" { #endif #ifndef BENCH_H_121279284357 #define BENCH_H_121279284357 #include /* size_t */ #define ZSTD_STATIC_LINKING_ONLY /* ZSTD_compressionParameters */ #include "zstd.h" /* ZSTD_compressionParameters */ /* Creates a struct type typeName, featuring: * - an .error field of type int * - a .result field of some baseType. * Functions with return type typeName * will either be successful, with .error = 0, providing a valid .result, * or return an error, with .error != 0, in which case .result is invalid. */ #define SUMTYPE_ERROR_RESULT(baseType, variantName) \ \ typedef struct { \ baseType internal_never_use_directly; \ int tag; \ } variantName typedef struct { size_t cSize; unsigned long long cSpeed; /* bytes / sec */ unsigned long long dSpeed; size_t cMem; /* ? what is reported ? */ } BMK_benchResult_t; SUMTYPE_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t); /* check first if the return structure represents an error or a valid result */ int BMK_isSuccessful_benchOutcome(BMK_benchOutcome_t errorOrResult); /* extract result from variant type. * note : this function will abort() program execution if result is not valid * check result validity first, by using BMK_isValid_benchResult() */ BMK_benchResult_t BMK_extract_benchResult(BMK_benchOutcome_t errorOrResult); /*! BMK_benchFiles() -- called by zstdcli */ /* Loads files from fileNamesTable into memory, * loads dictionary from dictFileName, * then uses benchMem(). * fileNamesTable - name of files to benchmark * nbFiles - number of files (size of fileNamesTable), must be > 0 (what happens if not ?) * dictFileName - name of dictionary file to load * cLevel - compression level to benchmark, errors if invalid * compressionParams - advanced compression Parameters * displayLevel - what gets printed * 0 : no display; * 1 : errors; * 2 : + result + interaction + warnings; * 3 : + progression; * 4 : + information * @return * .error will give a nonzero error value if an error has occured * .result - only valid if .error = 0, * .result will return compression speed (.cSpeed), * decompression speed (.dSpeed), and compressed size (.cSize). */ BMK_benchOutcome_t BMK_benchFiles( const char* const * fileNamesTable, unsigned nbFiles, const char* dictFileName, int cLevel, const ZSTD_compressionParameters* compressionParams, int displayLevel); typedef enum { BMK_both = 0, BMK_decodeOnly = 1, BMK_compressOnly = 2 } BMK_mode_t; typedef struct { BMK_mode_t mode; /* 0: all, 1: compress only 2: decode only */ unsigned nbSeconds; /* default timing is in nbSeconds */ size_t blockSize; /* Maximum allowable size of a block*/ unsigned nbWorkers; /* multithreading */ unsigned realTime; /* real time priority */ int additionalParam; /* used by python speed benchmark */ unsigned ldmFlag; /* enables long distance matching */ unsigned ldmMinMatch; /* below: parameters for long distance matching, see zstd.1.md for meaning */ unsigned ldmHashLog; unsigned ldmBucketSizeLog; unsigned ldmHashEveryLog; } BMK_advancedParams_t; /* returns default parameters used by nonAdvanced functions */ BMK_advancedParams_t BMK_initAdvancedParams(void); /*! BMK_benchFilesAdvanced(): * Same as BMK_benchFiles(), * with more controls, provided through advancedParams_t structure */ BMK_benchOutcome_t BMK_benchFilesAdvanced( const char* const * fileNamesTable, unsigned nbFiles, const char* dictFileName, int cLevel, const ZSTD_compressionParameters* compressionParams, int displayLevel, const BMK_advancedParams_t* adv); /*! BMK_syntheticTest() -- called from zstdcli */ /* Generates a sample with datagen, using compressibility argument */ /* cLevel - compression level to benchmark, errors if invalid * compressibility - determines compressibility of sample * compressionParams - basic compression Parameters * displayLevel - see benchFiles * adv - see advanced_Params_t * @return: * .error will give a nonzero error value if an error has occured * .result - only valid if .error = 0, * .result will return the compression speed (.cSpeed), * decompression speed (.dSpeed), and compressed size (.cSize). */ BMK_benchOutcome_t BMK_syntheticTest( int cLevel, double compressibility, const ZSTD_compressionParameters* compressionParams, int displayLevel, const BMK_advancedParams_t * const adv); /* === Benchmark Zstandard in a memory-to-memory scenario === */ /** BMK_benchMem() -- core benchmarking function, called in paramgrill * applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer * with specific compression parameters provided by other arguments using benchFunction * (cLevel, comprParams + adv in advanced Mode) */ /* srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode * srcSize - size of data in srcBuffer * fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately. * note : sum(fileSizes) must be == srcSize. (<== ensure it's properly checked) * nbFiles - nb of segments * cLevel - compression level * comprParams - basic compression parameters * dictBuffer - a dictionary if used, null otherwise * dictBufferSize - size of dictBuffer, 0 otherwise * diplayLevel - see BMK_benchFiles * displayName - name used by display * @return * .error will give a nonzero value if an error has occured * .result - only valid if .error = 0, * provide the same results as benchFiles() * but for the data stored in srcBuffer */ BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize, const size_t* fileSizes, unsigned nbFiles, int cLevel, const ZSTD_compressionParameters* comprParams, const void* dictBuffer, size_t dictBufferSize, int displayLevel, const char* displayName); /* BMK_benchMemAdvanced() : same as BMK_benchMem() * with following additional options : * dstBuffer - destination buffer to write compressed output in, NULL if none provided. * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL * adv = see advancedParams_t */ BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize, void* dstBuffer, size_t dstCapacity, const size_t* fileSizes, unsigned nbFiles, int cLevel, const ZSTD_compressionParameters* comprParams, const void* dictBuffer, size_t dictBufferSize, int displayLevel, const char* displayName, const BMK_advancedParams_t* adv); /* ==== Benchmarking any function, iterated on a set of blocks ==== */ typedef struct { unsigned long long nanoSecPerRun; /* time per iteration */ size_t sumOfReturn; /* sum of return values */ } BMK_runTime_t; SUMTYPE_ERROR_RESULT(BMK_runTime_t, BMK_runOutcome_t); /* check first if the return structure represents an error or a valid result */ int BMK_isSuccessful_runOutcome(BMK_runOutcome_t outcome); /* extract result from variant type. * note : this function will abort() program execution if result is not valid * check result validity first, by using BMK_isSuccessful_runOutcome() */ BMK_runTime_t BMK_extract_runTime(BMK_runOutcome_t outcome); typedef size_t (*BMK_benchFn_t)(const void* src, size_t srcSize, void* dst, size_t dstCapacity, void* customPayload); typedef size_t (*BMK_initFn_t)(void* initPayload); /* BMK_benchFunction() : * This function times the execution of 2 argument functions, benchFn and initFn */ /* benchFn - (*benchFn)(srcBuffers[i], srcSizes[i], dstBuffers[i], dstCapacities[i], benchPayload) * is run nbLoops times * initFn - (*initFn)(initPayload) is run once per benchmark, at the beginning. * This argument can be NULL, in which case nothing is run. * blockCount - number of blocks. Size of all array parameters : srcBuffers, srcSizes, dstBuffers, dstCapacities, blockResults * srcBuffers - an array of buffers to be operated on by benchFn * srcSizes - an array of the sizes of above buffers * dstBuffers - an array of buffers to be written into by benchFn * dstCapacities - an array of the capacities of above buffers * blockResults - store the return value of benchFn for each block. Optional. Use NULL if this result is not requested. * nbLoops - defines number of times benchFn is run. * @return: a variant, which can be an error, or a BMK_runTime_t result. * Use BMK_isSuccessful_runOutcome() to check if function was successful. * If yes, extract the result with BMK_extract_runTime(), * it will contain : * .sumOfReturn : the sum of all return values of benchFn through all of blocks * .nanoSecPerRun : time per run of benchFn + (time for initFn / nbLoops) * .sumOfReturn is generally intended for functions which return a # of bytes written into dstBuffer, * in which case, this value will be the total amount of bytes written into dstBuffer. */ BMK_runOutcome_t BMK_benchFunction( BMK_benchFn_t benchFn, void* benchPayload, BMK_initFn_t initFn, void* initPayload, size_t blockCount, const void *const * srcBuffers, const size_t* srcSizes, void *const * dstBuffers, const size_t* dstCapacities, size_t* blockResults, unsigned nbLoops); /* ==== Benchmarking any function, providing intermediate results ==== */ /* state information needed by benchFunctionTimed */ typedef struct BMK_timedFnState_s BMK_timedFnState_t; BMK_timedFnState_t* BMK_createTimedFnState(unsigned nbSeconds); void BMK_resetTimedFnState(BMK_timedFnState_t* timedFnState, unsigned nbSeconds); void BMK_freeTimedFnState(BMK_timedFnState_t* state); /* define timedFnOutcome */ SUMTYPE_ERROR_RESULT(BMK_runTime_t, BMK_timedFnOutcome_t); /* check first if the return structure represents an error or a valid result */ int BMK_isSuccessful_timedFnOutcome(BMK_timedFnOutcome_t outcome); /* extract intermediate results from variant type. * note : this function will abort() program execution if result is not valid. * check result validity first, by using BMK_isSuccessful_timedFnOutcome() */ BMK_runTime_t BMK_extract_timedFnResult(BMK_timedFnOutcome_t outcome); /* Tells if nb of seconds set in timedFnState for all runs is spent. * note : this function will return 1 if BMK_benchFunctionTimed() has actually errored. */ int BMK_isCompleted_timedFnOutcome(BMK_timedFnOutcome_t outcome); /* BMK_benchFunctionTimed() : * Similar to BMK_benchFunction(), * tries to find automatically `nbLoops`, so that each run lasts approximately 1 second. * Note : minimum `nbLoops` is 1, a run may last more than 1 second if benchFn is slow. * Most arguments are the same as BMK_benchFunction() * Usage - initialize a timedFnState, selecting a total nbSeconds allocated for _all_ benchmarks run * call BMK_benchFunctionTimed() repetitively, collecting intermediate results (each run is supposed to last about 1 seconds) * Check if time budget is spent using BMK_isCompleted_timedFnOutcome() */ BMK_timedFnOutcome_t BMK_benchFunctionTimed( BMK_timedFnState_t* timedFnState, BMK_benchFn_t benchFn, void* benchPayload, BMK_initFn_t initFn, void* initPayload, size_t blockCount, const void *const * srcBlockBuffers, const size_t* srcBlockSizes, void *const * dstBlockBuffers, const size_t* dstBlockCapacities, size_t* blockResults); #endif /* BENCH_H_121279284357 */ #if defined (__cplusplus) } #endif