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 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 */
110 int ldmBucketSizeLog;
112 ZSTD_paramSwitch_e literalCompressionMode;
113 int useRowMatchFinder; /* use row-based matchfinder if possible */
114 } BMK_advancedParams_t;
116 /* returns default parameters used by nonAdvanced functions */
117 BMK_advancedParams_t BMK_initAdvancedParams(void);
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);
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
138 int BMK_syntheticTest(int cLevel, double compressibility,
139 const ZSTD_compressionParameters* compressionParams,
140 int displayLevel, const BMK_advancedParams_t* adv);
144 /* === Benchmark Zstandard in a memory-to-memory scenario === */
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
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(),
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
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);
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
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);
194 #endif /* BENCH_ZSTD_H_3242387 */
196 #if defined (__cplusplus)