2 * Copyright (c) Meta Platforms, Inc. and affiliates.
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.
12 * benchmark Zstandard compression / decompression
13 * over a set of files or buffers
14 * and display progress result and final summary
17 #if defined (__cplusplus)
21 #ifndef BENCH_ZSTD_H_3242387
22 #define BENCH_ZSTD_H_3242387
24 /* === Dependencies === */
25 #include <stddef.h> /* size_t */
26 #define ZSTD_STATIC_LINKING_ONLY /* ZSTD_compressionParameters */
27 #include "../lib/zstd.h" /* ZSTD_compressionParameters */
30 /* === Constants === */
32 #define MB_UNIT 1000000
35 /* === Benchmark functions === */
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`.
42 #define VARIANT_ERROR_RESULT(baseType, variantName) \
45 baseType internal_never_use_directly; \
52 unsigned long long cSpeed; /* bytes / sec */
53 unsigned long long dSpeed;
54 size_t cMem; /* memory usage during compression */
57 VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t);
59 /* check first if the return structure represents an error or a valid result */
60 int BMK_isSuccessful_benchOutcome(BMK_benchOutcome_t outcome);
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()
66 BMK_benchResult_t BMK_extract_benchResult(BMK_benchOutcome_t outcome);
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:
81 * 2 : + result + interaction + warnings;
84 * @return: 0 on success, !0 on error
87 const char* const * fileNamesTable, unsigned nbFiles,
88 const char* dictFileName,
89 int cLevel, const ZSTD_compressionParameters* compressionParams,
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 int nbWorkers; /* multithreading */
104 unsigned realTime; /* real time priority */
105 int additionalParam; /* used by python speed benchmark */
106 int ldmFlag; /* enables long distance matching */
107 int ldmMinMatch; /* below: parameters for long distance matching, see zstd.1.md */
109 int ldmBucketSizeLog;
111 ZSTD_paramSwitch_e literalCompressionMode;
112 int useRowMatchFinder; /* use row-based matchfinder if possible */
113 } BMK_advancedParams_t;
115 /* returns default parameters used by nonAdvanced functions */
116 BMK_advancedParams_t BMK_initAdvancedParams(void);
118 /*! BMK_benchFilesAdvanced():
119 * Same as BMK_benchFiles(),
120 * with more controls, provided through advancedParams_t structure */
121 int BMK_benchFilesAdvanced(
122 const char* const * fileNamesTable, unsigned nbFiles,
123 const char* dictFileName,
124 int cLevel, const ZSTD_compressionParameters* compressionParams,
125 int displayLevel, const BMK_advancedParams_t* adv);
127 /*! BMK_syntheticTest() -- called from zstdcli */
128 /* Generates a sample with datagen, using compressibility argument */
129 /* cLevel - compression level to benchmark, errors if invalid
130 * compressibility - determines compressibility of sample
131 * compressionParams - basic compression Parameters
132 * displayLevel - see benchFiles
133 * adv - see advanced_Params_t
134 * @return: 0 on success, !0 on error
136 int BMK_syntheticTest(int cLevel, double compressibility,
137 const ZSTD_compressionParameters* compressionParams,
138 int displayLevel, const BMK_advancedParams_t* adv);
142 /* === Benchmark Zstandard in a memory-to-memory scenario === */
144 /** BMK_benchMem() -- core benchmarking function, called in paramgrill
145 * applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer
146 * with specific compression parameters provided by other arguments using benchFunction
147 * (cLevel, comprParams + adv in advanced Mode) */
148 /* srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode
149 * srcSize - size of data in srcBuffer
150 * fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately.
151 * note : sum(fileSizes) must be == srcSize. (<== ensure it's properly checked)
152 * nbFiles - nb of segments
153 * cLevel - compression level
154 * comprParams - basic compression parameters
155 * dictBuffer - a dictionary if used, null otherwise
156 * dictBufferSize - size of dictBuffer, 0 otherwise
157 * displayLevel - see BMK_benchFiles
158 * displayName - name used by display
160 * a variant, which expresses either an error, or a valid result.
161 * Use BMK_isSuccessful_benchOutcome() to check if function was successful.
162 * If yes, extract the valid result with BMK_extract_benchResult(),
164 * .cSpeed: compression speed in bytes per second,
165 * .dSpeed: decompression speed in bytes per second,
166 * .cSize : compressed size, in bytes
167 * .cMem : memory budget required for the compression context
169 BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize,
170 const size_t* fileSizes, unsigned nbFiles,
171 int cLevel, const ZSTD_compressionParameters* comprParams,
172 const void* dictBuffer, size_t dictBufferSize,
173 int displayLevel, const char* displayName);
176 /* BMK_benchMemAdvanced() : used by Paramgrill
177 * same as BMK_benchMem() with following additional options :
178 * dstBuffer - destination buffer to write compressed output in, NULL if none provided.
179 * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL
180 * adv = see advancedParams_t
182 BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize,
183 void* dstBuffer, size_t dstCapacity,
184 const size_t* fileSizes, unsigned nbFiles,
185 int cLevel, const ZSTD_compressionParameters* comprParams,
186 const void* dictBuffer, size_t dictBufferSize,
187 int displayLevel, const char* displayName,
188 const BMK_advancedParams_t* adv);
192 #endif /* BENCH_ZSTD_H_3242387 */
194 #if defined (__cplusplus)