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 199