| 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 |