1/*
2 * Copyright (c) Yann Collet, Facebook, Inc.
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)
18extern "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                                             \
44typedef struct {                             \
45    baseType internal_never_use_directly;    \
46    int tag;                                 \
47} variantName
48
49
50typedef 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
57VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t);
58
59/* check first if the return structure represents an error or a valid result */
60int 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 */
66BMK_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:
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(),
88 *      it will contain :
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
93 */
94BMK_benchOutcome_t BMK_benchFiles(
95                   const char* const * fileNamesTable, unsigned nbFiles,
96                   const char* dictFileName,
97                   int cLevel, const ZSTD_compressionParameters* compressionParams,
98                   int displayLevel);
99
100
101typedef enum {
102    BMK_both = 0,
103    BMK_decodeOnly = 1,
104    BMK_compressOnly = 2
105} BMK_mode_t;
106
107typedef struct {
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 */
116    int ldmHashLog;
117    int ldmBucketSizeLog;
118    int ldmHashRateLog;
119    ZSTD_paramSwitch_e literalCompressionMode;
120    int useRowMatchFinder;  /* use row-based matchfinder if possible */
121} BMK_advancedParams_t;
122
123/* returns default parameters used by nonAdvanced functions */
124BMK_advancedParams_t BMK_initAdvancedParams(void);
125
126/*! BMK_benchFilesAdvanced():
127 *  Same as BMK_benchFiles(),
128 *  with more controls, provided through advancedParams_t structure */
129BMK_benchOutcome_t BMK_benchFilesAdvanced(
130                   const char* const * fileNamesTable, unsigned nbFiles,
131                   const char* dictFileName,
132                   int cLevel, const ZSTD_compressionParameters* compressionParams,
133                   int displayLevel, const BMK_advancedParams_t* adv);
134
135/*! BMK_syntheticTest() -- called from zstdcli */
136/*  Generates a sample with datagen, using compressibility argument */
137/*  cLevel - compression level to benchmark, errors if invalid
138 *  compressibility - determines compressibility of sample
139 *  compressionParams - basic compression Parameters
140 *  displayLevel - see benchFiles
141 *  adv - see advanced_Params_t
142 * @return:
143 *      a variant, which expresses either an error, or a valid result.
144 *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
145 *      If yes, extract the valid result with BMK_extract_benchResult(),
146 *      it will contain :
147 *          .cSpeed: compression speed in bytes per second,
148 *          .dSpeed: decompression speed in bytes per second,
149 *          .cSize : compressed size, in bytes
150 *          .cMem  : memory budget required for the compression context
151 */
152BMK_benchOutcome_t BMK_syntheticTest(
153                          int cLevel, double compressibility,
154                          const ZSTD_compressionParameters* compressionParams,
155                          int displayLevel, const BMK_advancedParams_t* adv);
156
157
158
159/* ===  Benchmark Zstandard in a memory-to-memory scenario  === */
160
161/** BMK_benchMem() -- core benchmarking function, called in paramgrill
162 *  applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer
163 *  with specific compression parameters provided by other arguments using benchFunction
164 *  (cLevel, comprParams + adv in advanced Mode) */
165/*  srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode
166 *  srcSize - size of data in srcBuffer
167 *  fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately.
168 *              note : sum(fileSizes) must be == srcSize.  (<== ensure it's properly checked)
169 *  nbFiles - nb of segments
170 *  cLevel - compression level
171 *  comprParams - basic compression parameters
172 *  dictBuffer - a dictionary if used, null otherwise
173 *  dictBufferSize - size of dictBuffer, 0 otherwise
174 *  displayLevel - see BMK_benchFiles
175 *  displayName - name used by display
176 * @return:
177 *      a variant, which expresses either an error, or a valid result.
178 *      Use BMK_isSuccessful_benchOutcome() to check if function was successful.
179 *      If yes, extract the valid result with BMK_extract_benchResult(),
180 *      it will contain :
181 *          .cSpeed: compression speed in bytes per second,
182 *          .dSpeed: decompression speed in bytes per second,
183 *          .cSize : compressed size, in bytes
184 *          .cMem  : memory budget required for the compression context
185 */
186BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize,
187                        const size_t* fileSizes, unsigned nbFiles,
188                        int cLevel, const ZSTD_compressionParameters* comprParams,
189                        const void* dictBuffer, size_t dictBufferSize,
190                        int displayLevel, const char* displayName);
191
192
193/* BMK_benchMemAdvanced() : same as BMK_benchMem()
194 * with following additional options :
195 * dstBuffer - destination buffer to write compressed output in, NULL if none provided.
196 * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL
197 * adv = see advancedParams_t
198 */
199BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize,
200                        void* dstBuffer, size_t dstCapacity,
201                        const size_t* fileSizes, unsigned nbFiles,
202                        int cLevel, const ZSTD_compressionParameters* comprParams,
203                        const void* dictBuffer, size_t dictBufferSize,
204                        int displayLevel, const char* displayName,
205                        const BMK_advancedParams_t* adv);
206
207
208
209#endif   /* BENCH_ZSTD_H_3242387 */
210
211#if defined (__cplusplus)
212}
213#endif
214