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