]>
git.proxmox.com Git - ceph.git/blob - ceph/src/zstd/lib/deprecated/zbuff.h
2 * Copyright (c) 2016-present, 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.
11 /* ***************************************************************
13 ******************************************************************/
14 /* The streaming API defined here is deprecated.
15 * Consider migrating towards ZSTD_compressStream() API in `zstd.h`
16 * See 'lib/README.md'.
17 *****************************************************************/
20 #if defined (__cplusplus)
24 #ifndef ZSTD_BUFFERED_H_23987
25 #define ZSTD_BUFFERED_H_23987
27 /* *************************************
29 ***************************************/
30 #include <stddef.h> /* size_t */
31 #include "zstd.h" /* ZSTD_CStream, ZSTD_DStream, ZSTDLIB_API */
34 /* ***************************************************************
36 *****************************************************************/
37 /* Deprecation warnings */
38 /* Should these warnings be a problem,
39 it is generally possible to disable them,
40 typically with -Wno-deprecated-declarations for gcc
41 or _CRT_SECURE_NO_WARNINGS in Visual.
42 Otherwise, it's also possible to define ZBUFF_DISABLE_DEPRECATE_WARNINGS */
43 #ifdef ZBUFF_DISABLE_DEPRECATE_WARNINGS
44 # define ZBUFF_DEPRECATED(message) ZSTDLIB_API /* disable deprecation warnings */
46 # if defined (__cplusplus) && (__cplusplus >= 201402) /* C++14 or greater */
47 # define ZBUFF_DEPRECATED(message) [[deprecated(message)]] ZSTDLIB_API
48 # elif (defined(__GNUC__) && (__GNUC__ >= 5)) || defined(__clang__)
49 # define ZBUFF_DEPRECATED(message) ZSTDLIB_API __attribute__((deprecated(message)))
50 # elif defined(__GNUC__) && (__GNUC__ >= 3)
51 # define ZBUFF_DEPRECATED(message) ZSTDLIB_API __attribute__((deprecated))
52 # elif defined(_MSC_VER)
53 # define ZBUFF_DEPRECATED(message) ZSTDLIB_API __declspec(deprecated(message))
55 # pragma message( "WARNING: You need to implement ZBUFF_DEPRECATED for this compiler" )
56 # define ZBUFF_DEPRECATED(message) ZSTDLIB_API
58 #endif /* ZBUFF_DISABLE_DEPRECATE_WARNINGS */
61 /* *************************************
63 ***************************************/
64 /* This is the easier "buffered" streaming API,
65 * using an internal buffer to lift all restrictions on user-provided buffers
66 * which can be any size, any place, for both input and output.
67 * ZBUFF and ZSTD are 100% interoperable,
68 * frames created by one can be decoded by the other one */
70 typedef ZSTD_CStream ZBUFF_CCtx
;
71 ZBUFF_DEPRECATED ( "use ZSTD_createCStream" ) ZBUFF_CCtx
* ZBUFF_createCCtx ( void );
72 ZBUFF_DEPRECATED ( "use ZSTD_freeCStream" ) size_t ZBUFF_freeCCtx ( ZBUFF_CCtx
* cctx
);
74 ZBUFF_DEPRECATED ( "use ZSTD_initCStream" ) size_t ZBUFF_compressInit ( ZBUFF_CCtx
* cctx
, int compressionLevel
);
75 ZBUFF_DEPRECATED ( "use ZSTD_initCStream_usingDict" ) size_t ZBUFF_compressInitDictionary ( ZBUFF_CCtx
* cctx
, const void * dict
, size_t dictSize
, int compressionLevel
);
77 ZBUFF_DEPRECATED ( "use ZSTD_compressStream" ) size_t ZBUFF_compressContinue ( ZBUFF_CCtx
* cctx
, void * dst
, size_t * dstCapacityPtr
, const void * src
, size_t * srcSizePtr
);
78 ZBUFF_DEPRECATED ( "use ZSTD_flushStream" ) size_t ZBUFF_compressFlush ( ZBUFF_CCtx
* cctx
, void * dst
, size_t * dstCapacityPtr
);
79 ZBUFF_DEPRECATED ( "use ZSTD_endStream" ) size_t ZBUFF_compressEnd ( ZBUFF_CCtx
* cctx
, void * dst
, size_t * dstCapacityPtr
);
81 /*-*************************************************
82 * Streaming compression - howto
84 * A ZBUFF_CCtx object is required to track streaming operation.
85 * Use ZBUFF_createCCtx() and ZBUFF_freeCCtx() to create/release resources.
86 * ZBUFF_CCtx objects can be reused multiple times.
88 * Start by initializing ZBUF_CCtx.
89 * Use ZBUFF_compressInit() to start a new compression operation.
90 * Use ZBUFF_compressInitDictionary() for a compression which requires a dictionary.
92 * Use ZBUFF_compressContinue() repetitively to consume input stream.
93 * *srcSizePtr and *dstCapacityPtr can be any size.
94 * The function will report how many bytes were read or written within *srcSizePtr and *dstCapacityPtr.
95 * Note that it may not consume the entire input, in which case it's up to the caller to present again remaining data.
96 * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each call, so save its content if it matters or change @dst .
97 * @return : a hint to preferred nb of bytes to use as input for next function call (it's just a hint, to improve latency)
98 * or an error code, which can be tested using ZBUFF_isError().
100 * At any moment, it's possible to flush whatever data remains within buffer, using ZBUFF_compressFlush().
101 * The nb of bytes written into `dst` will be reported into *dstCapacityPtr.
102 * Note that the function cannot output more than *dstCapacityPtr,
103 * therefore, some content might still be left into internal buffer if *dstCapacityPtr is too small.
104 * @return : nb of bytes still present into internal buffer (0 if it's empty)
105 * or an error code, which can be tested using ZBUFF_isError().
107 * ZBUFF_compressEnd() instructs to finish a frame.
108 * It will perform a flush and write frame epilogue.
109 * The epilogue is required for decoders to consider a frame completed.
110 * Similar to ZBUFF_compressFlush(), it may not be able to output the entire internal buffer content if *dstCapacityPtr is too small.
111 * In which case, call again ZBUFF_compressFlush() to complete the flush.
112 * @return : nb of bytes still present into internal buffer (0 if it's empty)
113 * or an error code, which can be tested using ZBUFF_isError().
115 * Hint : _recommended buffer_ sizes (not compulsory) : ZBUFF_recommendedCInSize() / ZBUFF_recommendedCOutSize()
116 * input : ZBUFF_recommendedCInSize==128 KB block size is the internal unit, use this value to reduce intermediate stages (better latency)
117 * output : ZBUFF_recommendedCOutSize==ZSTD_compressBound(128 KB) + 3 + 3 : ensures it's always possible to write/flush/end a full block. Skip some buffering.
118 * By using both, it ensures that input will be entirely consumed, and output will always contain the result, reducing intermediate buffering.
119 * **************************************************/
122 typedef ZSTD_DStream ZBUFF_DCtx
;
123 ZBUFF_DEPRECATED ( "use ZSTD_createDStream" ) ZBUFF_DCtx
* ZBUFF_createDCtx ( void );
124 ZBUFF_DEPRECATED ( "use ZSTD_freeDStream" ) size_t ZBUFF_freeDCtx ( ZBUFF_DCtx
* dctx
);
126 ZBUFF_DEPRECATED ( "use ZSTD_initDStream" ) size_t ZBUFF_decompressInit ( ZBUFF_DCtx
* dctx
);
127 ZBUFF_DEPRECATED ( "use ZSTD_initDStream_usingDict" ) size_t ZBUFF_decompressInitDictionary ( ZBUFF_DCtx
* dctx
, const void * dict
, size_t dictSize
);
129 ZBUFF_DEPRECATED ( "use ZSTD_decompressStream" ) size_t ZBUFF_decompressContinue ( ZBUFF_DCtx
* dctx
,
130 void * dst
, size_t * dstCapacityPtr
,
131 const void * src
, size_t * srcSizePtr
);
133 /*-***************************************************************************
134 * Streaming decompression howto
136 * A ZBUFF_DCtx object is required to track streaming operations.
137 * Use ZBUFF_createDCtx() and ZBUFF_freeDCtx() to create/release resources.
138 * Use ZBUFF_decompressInit() to start a new decompression operation,
139 * or ZBUFF_decompressInitDictionary() if decompression requires a dictionary.
140 * Note that ZBUFF_DCtx objects can be re-init multiple times.
142 * Use ZBUFF_decompressContinue() repetitively to consume your input.
143 * *srcSizePtr and *dstCapacityPtr can be any size.
144 * The function will report how many bytes were read or written by modifying *srcSizePtr and *dstCapacityPtr.
145 * Note that it may not consume the entire input, in which case it's up to the caller to present remaining input again.
146 * The content of `dst` will be overwritten (up to *dstCapacityPtr) at each function call, so save its content if it matters, or change `dst`.
147 * @return : 0 when a frame is completely decoded and fully flushed,
148 * 1 when there is still some data left within internal buffer to flush,
149 * >1 when more data is expected, with value being a suggested next input size (it's just a hint, which helps latency),
150 * or an error code, which can be tested using ZBUFF_isError().
152 * Hint : recommended buffer sizes (not compulsory) : ZBUFF_recommendedDInSize() and ZBUFF_recommendedDOutSize()
153 * output : ZBUFF_recommendedDOutSize== 128 KB block size is the internal unit, it ensures it's always possible to write a full block when decoded.
154 * input : ZBUFF_recommendedDInSize == 128KB + 3;
155 * just follow indications from ZBUFF_decompressContinue() to minimize latency. It should always be <= 128 KB + 3 .
156 * *******************************************************************************/
159 /* *************************************
161 ***************************************/
162 ZBUFF_DEPRECATED ( "use ZSTD_isError" ) unsigned ZBUFF_isError ( size_t errorCode
);
163 ZBUFF_DEPRECATED ( "use ZSTD_getErrorName" ) const char * ZBUFF_getErrorName ( size_t errorCode
);
165 /** Functions below provide recommended buffer sizes for Compression or Decompression operations.
166 * These sizes are just hints, they tend to offer better latency */
167 ZBUFF_DEPRECATED ( "use ZSTD_CStreamInSize" ) size_t ZBUFF_recommendedCInSize ( void );
168 ZBUFF_DEPRECATED ( "use ZSTD_CStreamOutSize" ) size_t ZBUFF_recommendedCOutSize ( void );
169 ZBUFF_DEPRECATED ( "use ZSTD_DStreamInSize" ) size_t ZBUFF_recommendedDInSize ( void );
170 ZBUFF_DEPRECATED ( "use ZSTD_DStreamOutSize" ) size_t ZBUFF_recommendedDOutSize ( void );
172 #endif /* ZSTD_BUFFERED_H_23987 */
175 #ifdef ZBUFF_STATIC_LINKING_ONLY
176 #ifndef ZBUFF_STATIC_H_30298098432
177 #define ZBUFF_STATIC_H_30298098432
179 /* ====================================================================================
180 * The definitions in this section are considered experimental.
181 * They should never be used in association with a dynamic library, as they may change in the future.
182 * They are provided for advanced usages.
183 * Use them only in association with static linking.
184 * ==================================================================================== */
186 /*--- Dependency ---*/
187 #define ZSTD_STATIC_LINKING_ONLY /* ZSTD_parameters, ZSTD_customMem */
191 /*--- Custom memory allocator ---*/
192 /*! ZBUFF_createCCtx_advanced() :
193 * Create a ZBUFF compression context using external alloc and free functions */
194 ZBUFF_DEPRECATED ( "use ZSTD_createCStream_advanced" ) ZBUFF_CCtx
* ZBUFF_createCCtx_advanced ( ZSTD_customMem customMem
);
196 /*! ZBUFF_createDCtx_advanced() :
197 * Create a ZBUFF decompression context using external alloc and free functions */
198 ZBUFF_DEPRECATED ( "use ZSTD_createDStream_advanced" ) ZBUFF_DCtx
* ZBUFF_createDCtx_advanced ( ZSTD_customMem customMem
);
201 /*--- Advanced Streaming Initialization ---*/
202 ZBUFF_DEPRECATED ( "use ZSTD_initDStream_usingDict" ) size_t ZBUFF_compressInit_advanced ( ZBUFF_CCtx
* zbc
,
203 const void * dict
, size_t dictSize
,
204 ZSTD_parameters params
, unsigned long long pledgedSrcSize
);
207 #endif /* ZBUFF_STATIC_H_30298098432 */
208 #endif /* ZBUFF_STATIC_LINKING_ONLY */
211 #if defined (__cplusplus)