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