648db22b |
1 | /* |
2 | * Copyright (c) Meta Platforms, Inc. and affiliates. |
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) |
18 | extern "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 | \ |
44 | typedef struct { \ |
45 | baseType internal_never_use_directly; \ |
46 | int tag; \ |
47 | } variantName |
48 | |
49 | |
50 | typedef 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 | |
57 | VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t); |
58 | |
59 | /* check first if the return structure represents an error or a valid result */ |
60 | int 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 | */ |
66 | BMK_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: 0 on success, !0 on error |
85 | */ |
86 | int BMK_benchFiles( |
87 | const char* const * fileNamesTable, unsigned nbFiles, |
88 | const char* dictFileName, |
89 | int cLevel, const ZSTD_compressionParameters* compressionParams, |
90 | int displayLevel); |
91 | |
92 | |
93 | typedef enum { |
94 | BMK_both = 0, |
95 | BMK_decodeOnly = 1, |
96 | BMK_compressOnly = 2 |
97 | } BMK_mode_t; |
98 | |
99 | typedef struct { |
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*/ |
f535537f |
103 | size_t targetCBlockSize;/* Approximative size of compressed blocks */ |
648db22b |
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 */ |
109 | int ldmHashLog; |
110 | int ldmBucketSizeLog; |
111 | int ldmHashRateLog; |
112 | ZSTD_paramSwitch_e literalCompressionMode; |
113 | int useRowMatchFinder; /* use row-based matchfinder if possible */ |
114 | } BMK_advancedParams_t; |
115 | |
116 | /* returns default parameters used by nonAdvanced functions */ |
117 | BMK_advancedParams_t BMK_initAdvancedParams(void); |
118 | |
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); |
127 | |
128 | /*! BMK_syntheticTest() -- called from zstdcli */ |
129 | /* Generates a sample with datagen, using compressibility argument */ |
f535537f |
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 |
648db22b |
136 | * @return: 0 on success, !0 on error |
137 | */ |
138 | int BMK_syntheticTest(int cLevel, double compressibility, |
139 | const ZSTD_compressionParameters* compressionParams, |
140 | int displayLevel, const BMK_advancedParams_t* adv); |
141 | |
142 | |
143 | |
144 | /* === Benchmark Zstandard in a memory-to-memory scenario === */ |
145 | |
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 |
161 | * @return: |
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(), |
165 | * it will contain : |
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 |
170 | */ |
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); |
176 | |
177 | |
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 |
183 | */ |
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); |
191 | |
192 | |
193 | |
194 | #endif /* BENCH_ZSTD_H_3242387 */ |
195 | |
196 | #if defined (__cplusplus) |
197 | } |
198 | #endif |