benchzstd.h 8.6 KB

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