deps/libchdr/deps/zstd-1.5.5/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     int nbWorkers;          /* multithreading */
 104     unsigned realTime;      /* real time priority */
 105     int additionalParam;    /* used by python speed benchmark */
 106     int ldmFlag;            /* enables long distance matching */
 107     int ldmMinMatch;        /* below: parameters for long distance matching, see zstd.1.md */
 108     int ldmHashLog;
 109     int ldmBucketSizeLog;
 110     int ldmHashRateLog;
 111     ZSTD_paramSwitch_e literalCompressionMode;
 112     int useRowMatchFinder;  /* use row-based matchfinder if possible */
 113 } BMK_advancedParams_t;
 114
 115 /* returns default parameters used by nonAdvanced functions */
 116 BMK_advancedParams_t BMK_initAdvancedParams(void);
 117
 118 /*! BMK_benchFilesAdvanced():
 119  *  Same as BMK_benchFiles(),
 120  *  with more controls, provided through advancedParams_t structure */
 121 int BMK_benchFilesAdvanced(
 122                const char* const * fileNamesTable, unsigned nbFiles,
 123                const char* dictFileName,
 124                int cLevel, const ZSTD_compressionParameters* compressionParams,
 125                int displayLevel, const BMK_advancedParams_t* adv);
 126
 127 /*! BMK_syntheticTest() -- called from zstdcli */
 128 /*  Generates a sample with datagen, using compressibility argument */
 129 /*  cLevel - compression level to benchmark, errors if invalid
 130  *  compressibility - determines compressibility of sample
 131  *  compressionParams - basic compression Parameters
 132  *  displayLevel - see benchFiles
 133  *  adv - see advanced_Params_t
 134  * @return: 0 on success, !0 on error
 135  */
 136 int BMK_syntheticTest(int cLevel, double compressibility,
 137                       const ZSTD_compressionParameters* compressionParams,
 138                       int displayLevel, const BMK_advancedParams_t* adv);
 139
 140
 141
 142 /* ===  Benchmark Zstandard in a memory-to-memory scenario  === */
 143
 144 /** BMK_benchMem() -- core benchmarking function, called in paramgrill
 145  *  applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer
 146  *  with specific compression parameters provided by other arguments using benchFunction
 147  *  (cLevel, comprParams + adv in advanced Mode) */
 148 /*  srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode
 149  *  srcSize - size of data in srcBuffer
 150  *  fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately.
 151  *              note : sum(fileSizes) must be == srcSize.  (<== ensure it's properly checked)
 152  *  nbFiles - nb of segments
 153  *  cLevel - compression level
 154  *  comprParams - basic compression parameters
 155  *  dictBuffer - a dictionary if used, null otherwise
 156  *  dictBufferSize - size of dictBuffer, 0 otherwise
 157  *  displayLevel - see BMK_benchFiles
 158  *  displayName - name used by display
 159  * @return:
 160  *      a variant, which expresses either an error, or a valid result.
 161  *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
 162  *      If yes, extract the valid result with BMK_extract_benchResult(),
 163  *      it will contain :
 164  *          .cSpeed: compression speed in bytes per second,
 165  *          .dSpeed: decompression speed in bytes per second,
 166  *          .cSize : compressed size, in bytes
 167  *          .cMem  : memory budget required for the compression context
 168  */
 169 BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize,
 170                         const size_t* fileSizes, unsigned nbFiles,
 171                         int cLevel, const ZSTD_compressionParameters* comprParams,
 172                         const void* dictBuffer, size_t dictBufferSize,
 173                         int displayLevel, const char* displayName);
 174
 175
 176 /* BMK_benchMemAdvanced() : used by Paramgrill
 177  * same as BMK_benchMem() with following additional options :
 178  * dstBuffer - destination buffer to write compressed output in, NULL if none provided.
 179  * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL
 180  * adv = see advancedParams_t
 181  */
 182 BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize,
 183                         void* dstBuffer, size_t dstCapacity,
 184                         const size_t* fileSizes, unsigned nbFiles,
 185                         int cLevel, const ZSTD_compressionParameters* comprParams,
 186                         const void* dictBuffer, size_t dictBufferSize,
 187                         int displayLevel, const char* displayName,
 188                         const BMK_advancedParams_t* adv);
 189
 190
 191
 192 #endif   /* BENCH_ZSTD_H_3242387 */
 193
 194 #if defined (__cplusplus)
 195 }
 196 #endif