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