1 /* 2 * Copyright (c) 2016-2020, 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_literalCompressionMode_e literalCompressionMode; 120 } BMK_advancedParams_t; 121 122 /* returns default parameters used by nonAdvanced functions */ 123 BMK_advancedParams_t BMK_initAdvancedParams(void); 124 125 /*! BMK_benchFilesAdvanced(): 126 * Same as BMK_benchFiles(), 127 * with more controls, provided through advancedParams_t structure */ 128 BMK_benchOutcome_t BMK_benchFilesAdvanced( 129 const char* const * fileNamesTable, unsigned nbFiles, 130 const char* dictFileName, 131 int cLevel, const ZSTD_compressionParameters* compressionParams, 132 int displayLevel, const BMK_advancedParams_t* adv); 133 134 /*! BMK_syntheticTest() -- called from zstdcli */ 135 /* Generates a sample with datagen, using compressibility argument */ 136 /* cLevel - compression level to benchmark, errors if invalid 137 * compressibility - determines compressibility of sample 138 * compressionParams - basic compression Parameters 139 * displayLevel - see benchFiles 140 * adv - see advanced_Params_t 141 * @return: 142 * a variant, which expresses either an error, or a valid result. 143 * Use BMK_isSuccessful_benchOutcome() to check if function was successful. 144 * If yes, extract the valid result with BMK_extract_benchResult(), 145 * it will contain : 146 * .cSpeed: compression speed in bytes per second, 147 * .dSpeed: decompression speed in bytes per second, 148 * .cSize : compressed size, in bytes 149 * .cMem : memory budget required for the compression context 150 */ 151 BMK_benchOutcome_t BMK_syntheticTest( 152 int cLevel, double compressibility, 153 const ZSTD_compressionParameters* compressionParams, 154 int displayLevel, const BMK_advancedParams_t* adv); 155 156 157 158 /* === Benchmark Zstandard in a memory-to-memory scenario === */ 159 160 /** BMK_benchMem() -- core benchmarking function, called in paramgrill 161 * applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer 162 * with specific compression parameters provided by other arguments using benchFunction 163 * (cLevel, comprParams + adv in advanced Mode) */ 164 /* srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode 165 * srcSize - size of data in srcBuffer 166 * fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately. 167 * note : sum(fileSizes) must be == srcSize. (<== ensure it's properly checked) 168 * nbFiles - nb of segments 169 * cLevel - compression level 170 * comprParams - basic compression parameters 171 * dictBuffer - a dictionary if used, null otherwise 172 * dictBufferSize - size of dictBuffer, 0 otherwise 173 * displayLevel - see BMK_benchFiles 174 * displayName - name used by display 175 * @return: 176 * a variant, which expresses either an error, or a valid result. 177 * Use BMK_isSuccessful_benchOutcome() to check if function was successful. 178 * If yes, extract the valid result with BMK_extract_benchResult(), 179 * it will contain : 180 * .cSpeed: compression speed in bytes per second, 181 * .dSpeed: decompression speed in bytes per second, 182 * .cSize : compressed size, in bytes 183 * .cMem : memory budget required for the compression context 184 */ 185 BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize, 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 191 192 /* BMK_benchMemAdvanced() : same as BMK_benchMem() 193 * with following additional options : 194 * dstBuffer - destination buffer to write compressed output in, NULL if none provided. 195 * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL 196 * adv = see advancedParams_t 197 */ 198 BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize, 199 void* dstBuffer, size_t dstCapacity, 200 const size_t* fileSizes, unsigned nbFiles, 201 int cLevel, const ZSTD_compressionParameters* comprParams, 202 const void* dictBuffer, size_t dictBufferSize, 203 int displayLevel, const char* displayName, 204 const BMK_advancedParams_t* adv); 205 206 207 208 #endif /* BENCH_ZSTD_H_3242387 */ 209 210 #if defined (__cplusplus) 211 } 212 #endif 213