xref: /freebsd/sys/contrib/zstd/programs/benchzstd.h (revision a0483764f3d68669e9b7db074bcbd45b050166bb)
1*a0483764SConrad Meyer /*
2*a0483764SConrad Meyer  * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
3*a0483764SConrad Meyer  * All rights reserved.
4*a0483764SConrad Meyer  *
5*a0483764SConrad Meyer  * This source code is licensed under both the BSD-style license (found in the
6*a0483764SConrad Meyer  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
7*a0483764SConrad Meyer  * in the COPYING file in the root directory of this source tree).
8*a0483764SConrad Meyer  * You may select, at your option, one of the above-listed licenses.
9*a0483764SConrad Meyer  */
10*a0483764SConrad Meyer 
11*a0483764SConrad Meyer  /* benchzstd :
12*a0483764SConrad Meyer   * benchmark Zstandard compression / decompression
13*a0483764SConrad Meyer   * over a set of files or buffers
14*a0483764SConrad Meyer   * and display progress result and final summary
15*a0483764SConrad Meyer   */
16*a0483764SConrad Meyer 
17*a0483764SConrad Meyer #if defined (__cplusplus)
18*a0483764SConrad Meyer extern "C" {
19*a0483764SConrad Meyer #endif
20*a0483764SConrad Meyer 
21*a0483764SConrad Meyer #ifndef BENCH_ZSTD_H_3242387
22*a0483764SConrad Meyer #define BENCH_ZSTD_H_3242387
23*a0483764SConrad Meyer 
24*a0483764SConrad Meyer /* ===  Dependencies  === */
25*a0483764SConrad Meyer #include <stddef.h>   /* size_t */
26*a0483764SConrad Meyer #define ZSTD_STATIC_LINKING_ONLY   /* ZSTD_compressionParameters */
27*a0483764SConrad Meyer #include "zstd.h"     /* ZSTD_compressionParameters */
28*a0483764SConrad Meyer 
29*a0483764SConrad Meyer 
30*a0483764SConrad Meyer /* ===  Constants  === */
31*a0483764SConrad Meyer 
32*a0483764SConrad Meyer #define MB_UNIT 1000000
33*a0483764SConrad Meyer 
34*a0483764SConrad Meyer 
35*a0483764SConrad Meyer /* ===  Benchmark functions  === */
36*a0483764SConrad Meyer 
37*a0483764SConrad Meyer /* Creates a variant `typeName`, able to express "error or valid result".
38*a0483764SConrad Meyer  * Functions with return type `typeName`
39*a0483764SConrad Meyer  * must first check if result is valid, using BMK_isSuccessful_*(),
40*a0483764SConrad Meyer  * and only then can extract `baseType`.
41*a0483764SConrad Meyer  */
42*a0483764SConrad Meyer #define VARIANT_ERROR_RESULT(baseType, variantName)  \
43*a0483764SConrad Meyer                                              \
44*a0483764SConrad Meyer typedef struct {                             \
45*a0483764SConrad Meyer     baseType internal_never_use_directly;    \
46*a0483764SConrad Meyer     int tag;                                 \
47*a0483764SConrad Meyer } variantName
48*a0483764SConrad Meyer 
49*a0483764SConrad Meyer 
50*a0483764SConrad Meyer typedef struct {
51*a0483764SConrad Meyer     size_t cSize;
52*a0483764SConrad Meyer     unsigned long long cSpeed;   /* bytes / sec */
53*a0483764SConrad Meyer     unsigned long long dSpeed;
54*a0483764SConrad Meyer     size_t cMem;                 /* memory usage during compression */
55*a0483764SConrad Meyer } BMK_benchResult_t;
56*a0483764SConrad Meyer 
57*a0483764SConrad Meyer VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t);
58*a0483764SConrad Meyer 
59*a0483764SConrad Meyer /* check first if the return structure represents an error or a valid result */
60*a0483764SConrad Meyer int BMK_isSuccessful_benchOutcome(BMK_benchOutcome_t outcome);
61*a0483764SConrad Meyer 
62*a0483764SConrad Meyer /* extract result from variant type.
63*a0483764SConrad Meyer  * note : this function will abort() program execution if result is not valid
64*a0483764SConrad Meyer  *        check result validity first, by using BMK_isSuccessful_benchOutcome()
65*a0483764SConrad Meyer  */
66*a0483764SConrad Meyer BMK_benchResult_t BMK_extract_benchResult(BMK_benchOutcome_t outcome);
67*a0483764SConrad Meyer 
68*a0483764SConrad Meyer 
69*a0483764SConrad Meyer /*! BMK_benchFiles() -- called by zstdcli */
70*a0483764SConrad Meyer /*  Loads files from fileNamesTable into memory,
71*a0483764SConrad Meyer  *  and an optional dictionary from dictFileName (can be NULL),
72*a0483764SConrad Meyer  *  then uses benchMem().
73*a0483764SConrad Meyer  *  fileNamesTable - name of files to benchmark.
74*a0483764SConrad Meyer  *  nbFiles - number of files (size of fileNamesTable), must be > 0.
75*a0483764SConrad Meyer  *  dictFileName - name of dictionary file to load.
76*a0483764SConrad Meyer  *  cLevel - compression level to benchmark, errors if invalid.
77*a0483764SConrad Meyer  *  compressionParams - advanced compression Parameters.
78*a0483764SConrad Meyer  *  displayLevel - what gets printed:
79*a0483764SConrad Meyer  *      0 : no display;
80*a0483764SConrad Meyer  *      1 : errors;
81*a0483764SConrad Meyer  *      2 : + result + interaction + warnings;
82*a0483764SConrad Meyer  *      3 : + information;
83*a0483764SConrad Meyer  *      4 : + debug
84*a0483764SConrad Meyer  * @return:
85*a0483764SConrad Meyer  *      a variant, which expresses either an error, or a valid result.
86*a0483764SConrad Meyer  *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
87*a0483764SConrad Meyer  *      If yes, extract the valid result with BMK_extract_benchResult(),
88*a0483764SConrad Meyer  *      it will contain :
89*a0483764SConrad Meyer  *          .cSpeed: compression speed in bytes per second,
90*a0483764SConrad Meyer  *          .dSpeed: decompression speed in bytes per second,
91*a0483764SConrad Meyer  *          .cSize : compressed size, in bytes
92*a0483764SConrad Meyer  *          .cMem  : memory budget required for the compression context
93*a0483764SConrad Meyer  */
94*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchFiles(
95*a0483764SConrad Meyer                    const char* const * fileNamesTable, unsigned nbFiles,
96*a0483764SConrad Meyer                    const char* dictFileName,
97*a0483764SConrad Meyer                    int cLevel, const ZSTD_compressionParameters* compressionParams,
98*a0483764SConrad Meyer                    int displayLevel);
99*a0483764SConrad Meyer 
100*a0483764SConrad Meyer 
101*a0483764SConrad Meyer typedef enum {
102*a0483764SConrad Meyer     BMK_both = 0,
103*a0483764SConrad Meyer     BMK_decodeOnly = 1,
104*a0483764SConrad Meyer     BMK_compressOnly = 2
105*a0483764SConrad Meyer } BMK_mode_t;
106*a0483764SConrad Meyer 
107*a0483764SConrad Meyer typedef struct {
108*a0483764SConrad Meyer     BMK_mode_t mode;            /* 0: all, 1: compress only 2: decode only */
109*a0483764SConrad Meyer     unsigned nbSeconds;         /* default timing is in nbSeconds */
110*a0483764SConrad Meyer     size_t blockSize;           /* Maximum size of each block*/
111*a0483764SConrad Meyer     unsigned nbWorkers;         /* multithreading */
112*a0483764SConrad Meyer     unsigned realTime;          /* real time priority */
113*a0483764SConrad Meyer     int additionalParam;        /* used by python speed benchmark */
114*a0483764SConrad Meyer     unsigned ldmFlag;           /* enables long distance matching */
115*a0483764SConrad Meyer     unsigned ldmMinMatch;       /* below: parameters for long distance matching, see zstd.1.md */
116*a0483764SConrad Meyer     unsigned ldmHashLog;
117*a0483764SConrad Meyer     unsigned ldmBucketSizeLog;
118*a0483764SConrad Meyer     unsigned ldmHashRateLog;
119*a0483764SConrad Meyer } BMK_advancedParams_t;
120*a0483764SConrad Meyer 
121*a0483764SConrad Meyer /* returns default parameters used by nonAdvanced functions */
122*a0483764SConrad Meyer BMK_advancedParams_t BMK_initAdvancedParams(void);
123*a0483764SConrad Meyer 
124*a0483764SConrad Meyer /*! BMK_benchFilesAdvanced():
125*a0483764SConrad Meyer  *  Same as BMK_benchFiles(),
126*a0483764SConrad Meyer  *  with more controls, provided through advancedParams_t structure */
127*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchFilesAdvanced(
128*a0483764SConrad Meyer                    const char* const * fileNamesTable, unsigned nbFiles,
129*a0483764SConrad Meyer                    const char* dictFileName,
130*a0483764SConrad Meyer                    int cLevel, const ZSTD_compressionParameters* compressionParams,
131*a0483764SConrad Meyer                    int displayLevel, const BMK_advancedParams_t* adv);
132*a0483764SConrad Meyer 
133*a0483764SConrad Meyer /*! BMK_syntheticTest() -- called from zstdcli */
134*a0483764SConrad Meyer /*  Generates a sample with datagen, using compressibility argument */
135*a0483764SConrad Meyer /*  cLevel - compression level to benchmark, errors if invalid
136*a0483764SConrad Meyer  *  compressibility - determines compressibility of sample
137*a0483764SConrad Meyer  *  compressionParams - basic compression Parameters
138*a0483764SConrad Meyer  *  displayLevel - see benchFiles
139*a0483764SConrad Meyer  *  adv - see advanced_Params_t
140*a0483764SConrad Meyer  * @return:
141*a0483764SConrad Meyer  *      a variant, which expresses either an error, or a valid result.
142*a0483764SConrad Meyer  *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
143*a0483764SConrad Meyer  *      If yes, extract the valid result with BMK_extract_benchResult(),
144*a0483764SConrad Meyer  *      it will contain :
145*a0483764SConrad Meyer  *          .cSpeed: compression speed in bytes per second,
146*a0483764SConrad Meyer  *          .dSpeed: decompression speed in bytes per second,
147*a0483764SConrad Meyer  *          .cSize : compressed size, in bytes
148*a0483764SConrad Meyer  *          .cMem  : memory budget required for the compression context
149*a0483764SConrad Meyer  */
150*a0483764SConrad Meyer BMK_benchOutcome_t BMK_syntheticTest(
151*a0483764SConrad Meyer                           int cLevel, double compressibility,
152*a0483764SConrad Meyer                           const ZSTD_compressionParameters* compressionParams,
153*a0483764SConrad Meyer                           int displayLevel, const BMK_advancedParams_t* adv);
154*a0483764SConrad Meyer 
155*a0483764SConrad Meyer 
156*a0483764SConrad Meyer 
157*a0483764SConrad Meyer /* ===  Benchmark Zstandard in a memory-to-memory scenario  === */
158*a0483764SConrad Meyer 
159*a0483764SConrad Meyer /** BMK_benchMem() -- core benchmarking function, called in paramgrill
160*a0483764SConrad Meyer  *  applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer
161*a0483764SConrad Meyer  *  with specific compression parameters provided by other arguments using benchFunction
162*a0483764SConrad Meyer  *  (cLevel, comprParams + adv in advanced Mode) */
163*a0483764SConrad Meyer /*  srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode
164*a0483764SConrad Meyer  *  srcSize - size of data in srcBuffer
165*a0483764SConrad Meyer  *  fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately.
166*a0483764SConrad Meyer  *              note : sum(fileSizes) must be == srcSize.  (<== ensure it's properly checked)
167*a0483764SConrad Meyer  *  nbFiles - nb of segments
168*a0483764SConrad Meyer  *  cLevel - compression level
169*a0483764SConrad Meyer  *  comprParams - basic compression parameters
170*a0483764SConrad Meyer  *  dictBuffer - a dictionary if used, null otherwise
171*a0483764SConrad Meyer  *  dictBufferSize - size of dictBuffer, 0 otherwise
172*a0483764SConrad Meyer  *  diplayLevel - see BMK_benchFiles
173*a0483764SConrad Meyer  *  displayName - name used by display
174*a0483764SConrad Meyer  * @return:
175*a0483764SConrad Meyer  *      a variant, which expresses either an error, or a valid result.
176*a0483764SConrad Meyer  *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
177*a0483764SConrad Meyer  *      If yes, extract the valid result with BMK_extract_benchResult(),
178*a0483764SConrad Meyer  *      it will contain :
179*a0483764SConrad Meyer  *          .cSpeed: compression speed in bytes per second,
180*a0483764SConrad Meyer  *          .dSpeed: decompression speed in bytes per second,
181*a0483764SConrad Meyer  *          .cSize : compressed size, in bytes
182*a0483764SConrad Meyer  *          .cMem  : memory budget required for the compression context
183*a0483764SConrad Meyer  */
184*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize,
185*a0483764SConrad Meyer                         const size_t* fileSizes, unsigned nbFiles,
186*a0483764SConrad Meyer                         int cLevel, const ZSTD_compressionParameters* comprParams,
187*a0483764SConrad Meyer                         const void* dictBuffer, size_t dictBufferSize,
188*a0483764SConrad Meyer                         int displayLevel, const char* displayName);
189*a0483764SConrad Meyer 
190*a0483764SConrad Meyer 
191*a0483764SConrad Meyer /* BMK_benchMemAdvanced() : same as BMK_benchMem()
192*a0483764SConrad Meyer  * with following additional options :
193*a0483764SConrad Meyer  * dstBuffer - destination buffer to write compressed output in, NULL if none provided.
194*a0483764SConrad Meyer  * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL
195*a0483764SConrad Meyer  * adv = see advancedParams_t
196*a0483764SConrad Meyer  */
197*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize,
198*a0483764SConrad Meyer                         void* dstBuffer, size_t dstCapacity,
199*a0483764SConrad Meyer                         const size_t* fileSizes, unsigned nbFiles,
200*a0483764SConrad Meyer                         int cLevel, const ZSTD_compressionParameters* comprParams,
201*a0483764SConrad Meyer                         const void* dictBuffer, size_t dictBufferSize,
202*a0483764SConrad Meyer                         int displayLevel, const char* displayName,
203*a0483764SConrad Meyer                         const BMK_advancedParams_t* adv);
204*a0483764SConrad Meyer 
205*a0483764SConrad Meyer 
206*a0483764SConrad Meyer 
207*a0483764SConrad Meyer 
208*a0483764SConrad Meyer #endif   /* BENCH_ZSTD_H_3242387 */
209*a0483764SConrad Meyer 
210*a0483764SConrad Meyer #if defined (__cplusplus)
211*a0483764SConrad Meyer }
212*a0483764SConrad Meyer #endif
213