deps/libchdr/deps/zstd-1.5.6/programs/benchzstd.h

   1 /*
   2  * Copyright (c) Meta Platforms, Inc. and affiliates.
   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  /* benchzstd :
  12   * benchmark Zstandard compression / decompression
  13   * over a set of files or buffers
  14   * and display progress result and final summary
  15   */
  16
  17 #if defined (__cplusplus)
  18 extern "C" {
  19 #endif
  20
  21 #ifndef BENCH_ZSTD_H_3242387
  22 #define BENCH_ZSTD_H_3242387
  23
  24 /* ===  Dependencies  === */
  25 #include <stddef.h>   /* size_t */
  26 #define ZSTD_STATIC_LINKING_ONLY   /* ZSTD_compressionParameters */
  27 #include "../lib/zstd.h"     /* ZSTD_compressionParameters */
  28
  29
  30 /* ===  Constants  === */
  31
  32 #define MB_UNIT 1000000
  33
  34
  35 /* ===  Benchmark functions  === */
  36
  37 /* Creates a variant `typeName`, able to express "error or valid result".
  38  * Functions with return type `typeName`
  39  * must first check if result is valid, using BMK_isSuccessful_*(),
  40  * and only then can extract `baseType`.
  41  */
  42 #define VARIANT_ERROR_RESULT(baseType, variantName)  \
  43                                              \
  44 typedef struct {                             \
  45     baseType internal_never_use_directly;    \
  46     int tag;                                 \
  47 } variantName
  48
  49
  50 typedef struct {
  51     size_t cSize;
  52     unsigned long long cSpeed;   /* bytes / sec */
  53     unsigned long long dSpeed;
  54     size_t cMem;                 /* memory usage during compression */
  55 } BMK_benchResult_t;
  56
  57 VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t);
  58
  59 /* check first if the return structure represents an error or a valid result */
  60 int BMK_isSuccessful_benchOutcome(BMK_benchOutcome_t outcome);
  61
  62 /* extract result from variant type.
  63  * note : this function will abort() program execution if result is not valid
  64  *        check result validity first, by using BMK_isSuccessful_benchOutcome()
  65  */
  66 BMK_benchResult_t BMK_extract_benchResult(BMK_benchOutcome_t outcome);
  67
  68
  69 /*! BMK_benchFiles() -- called by zstdcli */
  70 /*  Loads files from fileNamesTable into memory,
  71  *  and an optional dictionary from dictFileName (can be NULL),
  72  *  then uses benchMem().
  73  *  fileNamesTable - name of files to benchmark.
  74  *  nbFiles - number of files (size of fileNamesTable), must be > 0.
  75  *  dictFileName - name of dictionary file to load.
  76  *  cLevel - compression level to benchmark, errors if invalid.
  77  *  compressionParams - advanced compression Parameters.
  78  *  displayLevel - what gets printed:
  79  *      0 : no display;
  80  *      1 : errors;
  81  *      2 : + result + interaction + warnings;
  82  *      3 : + information;
  83  *      4 : + debug
  84  * @return: 0 on success, !0 on error
  85  */
  86 int BMK_benchFiles(
  87             const char* const * fileNamesTable, unsigned nbFiles,
  88             const char* dictFileName,
  89             int cLevel, const ZSTD_compressionParameters* compressionParams,
  90             int displayLevel);
  91
  92
  93 typedef enum {
  94     BMK_both = 0,
  95     BMK_decodeOnly = 1,
  96     BMK_compressOnly = 2
  97 } BMK_mode_t;
  98
  99 typedef struct {
 100     BMK_mode_t mode;        /* 0: all, 1: compress only 2: decode only */
 101     unsigned nbSeconds;     /* default timing is in nbSeconds */
 102     size_t blockSize;       /* Maximum size of each block*/
 103     size_t targetCBlockSize;/* Approximative size of compressed blocks */
 104     int nbWorkers;          /* multithreading */
 105     unsigned realTime;      /* real time priority */
 106     int additionalParam;    /* used by python speed benchmark */
 107     int ldmFlag;            /* enables long distance matching */
 108     int ldmMinMatch;        /* below: parameters for long distance matching, see zstd.1.md */
 109     int ldmHashLog;
 110     int ldmBucketSizeLog;
 111     int ldmHashRateLog;
 112     ZSTD_paramSwitch_e literalCompressionMode;
 113     int useRowMatchFinder;  /* use row-based matchfinder if possible */
 114 } BMK_advancedParams_t;
 115
 116 /* returns default parameters used by nonAdvanced functions */
 117 BMK_advancedParams_t BMK_initAdvancedParams(void);
 118
 119 /*! BMK_benchFilesAdvanced():
 120  *  Same as BMK_benchFiles(),
 121  *  with more controls, provided through advancedParams_t structure */
 122 int BMK_benchFilesAdvanced(
 123                const char* const * fileNamesTable, unsigned nbFiles,
 124                const char* dictFileName,
 125                int cLevel, const ZSTD_compressionParameters* compressionParams,
 126                int displayLevel, const BMK_advancedParams_t* adv);
 127
 128 /*! BMK_syntheticTest() -- called from zstdcli */
 129 /*  Generates a sample with datagen, using compressibility argument */
 130 /* @cLevel - compression level to benchmark, errors if invalid
 131  * @compressibility - determines compressibility of sample, range [0.0 - 1.0]
 132  *        if @compressibility < 0.0, uses the lorem ipsum generator
 133  * @compressionParams - basic compression Parameters
 134  * @displayLevel - see benchFiles
 135  * @adv - see advanced_Params_t
 136  * @return: 0 on success, !0 on error
 137  */
 138 int BMK_syntheticTest(int cLevel, double compressibility,
 139                       const ZSTD_compressionParameters* compressionParams,
 140                       int displayLevel, const BMK_advancedParams_t* adv);
 141
 142
 143
 144 /* ===  Benchmark Zstandard in a memory-to-memory scenario  === */
 145
 146 /** BMK_benchMem() -- core benchmarking function, called in paramgrill
 147  *  applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer
 148  *  with specific compression parameters provided by other arguments using benchFunction
 149  *  (cLevel, comprParams + adv in advanced Mode) */
 150 /*  srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode
 151  *  srcSize - size of data in srcBuffer
 152  *  fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately.
 153  *              note : sum(fileSizes) must be == srcSize.  (<== ensure it's properly checked)
 154  *  nbFiles - nb of segments
 155  *  cLevel - compression level
 156  *  comprParams - basic compression parameters
 157  *  dictBuffer - a dictionary if used, null otherwise
 158  *  dictBufferSize - size of dictBuffer, 0 otherwise
 159  *  displayLevel - see BMK_benchFiles
 160  *  displayName - name used by display
 161  * @return:
 162  *      a variant, which expresses either an error, or a valid result.
 163  *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
 164  *      If yes, extract the valid result with BMK_extract_benchResult(),
 165  *      it will contain :
 166  *          .cSpeed: compression speed in bytes per second,
 167  *          .dSpeed: decompression speed in bytes per second,
 168  *          .cSize : compressed size, in bytes
 169  *          .cMem  : memory budget required for the compression context
 170  */
 171 BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize,
 172                         const size_t* fileSizes, unsigned nbFiles,
 173                         int cLevel, const ZSTD_compressionParameters* comprParams,
 174                         const void* dictBuffer, size_t dictBufferSize,
 175                         int displayLevel, const char* displayName);
 176
 177
 178 /* BMK_benchMemAdvanced() : used by Paramgrill
 179  * same as BMK_benchMem() with following additional options :
 180  * dstBuffer - destination buffer to write compressed output in, NULL if none provided.
 181  * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL
 182  * adv = see advancedParams_t
 183  */
 184 BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize,
 185                         void* dstBuffer, size_t dstCapacity,
 186                         const size_t* fileSizes, unsigned nbFiles,
 187                         int cLevel, const ZSTD_compressionParameters* comprParams,
 188                         const void* dictBuffer, size_t dictBufferSize,
 189                         int displayLevel, const char* displayName,
 190                         const BMK_advancedParams_t* adv);
 191
 192
 193
 194 #endif   /* BENCH_ZSTD_H_3242387 */
 195
 196 #if defined (__cplusplus)
 197 }
 198 #endif