2 * Copyright (c) 2016-2020, Yann Collet, Facebook, Inc.
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;
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(),
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
94 BMK_benchOutcome_t BMK_benchFiles(
95 const char* const * fileNamesTable, unsigned nbFiles,
96 const char* dictFileName,
97 int cLevel, const ZSTD_compressionParameters* compressionParams,
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 */
117 int ldmBucketSizeLog;
119 ZSTD_literalCompressionMode_e literalCompressionMode;
120 } BMK_advancedParams_t;
122 /* returns default parameters used by nonAdvanced functions */
123 BMK_advancedParams_t BMK_initAdvancedParams(void);
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);
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
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(),
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
151 BMK_benchOutcome_t BMK_syntheticTest(
152 int cLevel, double compressibility,
153 const ZSTD_compressionParameters* compressionParams,
154 int displayLevel, const BMK_advancedParams_t* adv);
158 /* === Benchmark Zstandard in a memory-to-memory scenario === */
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
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(),
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
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);
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
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);
208 #endif /* BENCH_ZSTD_H_3242387 */
210 #if defined (__cplusplus)