|
||||
File indexing completed on 2024-05-18 08:30:07
0001 /* 0002 LZ4 HC - High Compression Mode of LZ4 0003 Header File 0004 Copyright (C) 2011-2020, Yann Collet. 0005 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) 0006 0007 Redistribution and use in source and binary forms, with or without 0008 modification, are permitted provided that the following conditions are 0009 met: 0010 0011 * Redistributions of source code must retain the above copyright 0012 notice, this list of conditions and the following disclaimer. 0013 * Redistributions in binary form must reproduce the above 0014 copyright notice, this list of conditions and the following disclaimer 0015 in the documentation and/or other materials provided with the 0016 distribution. 0017 0018 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 0019 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 0020 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 0021 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 0022 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 0023 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 0024 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 0025 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 0026 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 0027 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 0028 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 0029 0030 You can contact the author at : 0031 - LZ4 source repository : https://github.com/lz4/lz4 0032 - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c 0033 */ 0034 #ifndef LZ4_HC_H_19834876238432 0035 #define LZ4_HC_H_19834876238432 0036 0037 #if defined (__cplusplus) 0038 extern "C" { 0039 #endif 0040 0041 /* --- Dependency --- */ 0042 /* note : lz4hc requires lz4.h/lz4.c for compilation */ 0043 #include "lz4.h" /* stddef, LZ4LIB_API, LZ4_DEPRECATED */ 0044 0045 0046 /* --- Useful constants --- */ 0047 #define LZ4HC_CLEVEL_MIN 3 0048 #define LZ4HC_CLEVEL_DEFAULT 9 0049 #define LZ4HC_CLEVEL_OPT_MIN 10 0050 #define LZ4HC_CLEVEL_MAX 12 0051 0052 0053 /*-************************************ 0054 * Block Compression 0055 **************************************/ 0056 /*! LZ4_compress_HC() : 0057 * Compress data from `src` into `dst`, using the powerful but slower "HC" algorithm. 0058 * `dst` must be already allocated. 0059 * Compression is guaranteed to succeed if `dstCapacity >= LZ4_compressBound(srcSize)` (see "lz4.h") 0060 * Max supported `srcSize` value is LZ4_MAX_INPUT_SIZE (see "lz4.h") 0061 * `compressionLevel` : any value between 1 and LZ4HC_CLEVEL_MAX will work. 0062 * Values > LZ4HC_CLEVEL_MAX behave the same as LZ4HC_CLEVEL_MAX. 0063 * @return : the number of bytes written into 'dst' 0064 * or 0 if compression fails. 0065 */ 0066 LZ4LIB_API int LZ4_compress_HC (const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel); 0067 0068 0069 /* Note : 0070 * Decompression functions are provided within "lz4.h" (BSD license) 0071 */ 0072 0073 0074 /*! LZ4_compress_HC_extStateHC() : 0075 * Same as LZ4_compress_HC(), but using an externally allocated memory segment for `state`. 0076 * `state` size is provided by LZ4_sizeofStateHC(). 0077 * Memory segment must be aligned on 8-bytes boundaries (which a normal malloc() should do properly). 0078 */ 0079 LZ4LIB_API int LZ4_sizeofStateHC(void); 0080 LZ4LIB_API int LZ4_compress_HC_extStateHC(void* stateHC, const char* src, char* dst, int srcSize, int maxDstSize, int compressionLevel); 0081 0082 0083 /*! LZ4_compress_HC_destSize() : v1.9.0+ 0084 * Will compress as much data as possible from `src` 0085 * to fit into `targetDstSize` budget. 0086 * Result is provided in 2 parts : 0087 * @return : the number of bytes written into 'dst' (necessarily <= targetDstSize) 0088 * or 0 if compression fails. 0089 * `srcSizePtr` : on success, *srcSizePtr is updated to indicate how much bytes were read from `src` 0090 */ 0091 LZ4LIB_API int LZ4_compress_HC_destSize(void* stateHC, 0092 const char* src, char* dst, 0093 int* srcSizePtr, int targetDstSize, 0094 int compressionLevel); 0095 0096 0097 /*-************************************ 0098 * Streaming Compression 0099 * Bufferless synchronous API 0100 **************************************/ 0101 typedef union LZ4_streamHC_u LZ4_streamHC_t; /* incomplete type (defined later) */ 0102 0103 /*! LZ4_createStreamHC() and LZ4_freeStreamHC() : 0104 * These functions create and release memory for LZ4 HC streaming state. 0105 * Newly created states are automatically initialized. 0106 * A same state can be used multiple times consecutively, 0107 * starting with LZ4_resetStreamHC_fast() to start a new stream of blocks. 0108 */ 0109 LZ4LIB_API LZ4_streamHC_t* LZ4_createStreamHC(void); 0110 LZ4LIB_API int LZ4_freeStreamHC (LZ4_streamHC_t* streamHCPtr); 0111 0112 /* 0113 These functions compress data in successive blocks of any size, 0114 using previous blocks as dictionary, to improve compression ratio. 0115 One key assumption is that previous blocks (up to 64 KB) remain read-accessible while compressing next blocks. 0116 There is an exception for ring buffers, which can be smaller than 64 KB. 0117 Ring-buffer scenario is automatically detected and handled within LZ4_compress_HC_continue(). 0118 0119 Before starting compression, state must be allocated and properly initialized. 0120 LZ4_createStreamHC() does both, though compression level is set to LZ4HC_CLEVEL_DEFAULT. 0121 0122 Selecting the compression level can be done with LZ4_resetStreamHC_fast() (starts a new stream) 0123 or LZ4_setCompressionLevel() (anytime, between blocks in the same stream) (experimental). 0124 LZ4_resetStreamHC_fast() only works on states which have been properly initialized at least once, 0125 which is automatically the case when state is created using LZ4_createStreamHC(). 0126 0127 After reset, a first "fictional block" can be designated as initial dictionary, 0128 using LZ4_loadDictHC() (Optional). 0129 0130 Invoke LZ4_compress_HC_continue() to compress each successive block. 0131 The number of blocks is unlimited. 0132 Previous input blocks, including initial dictionary when present, 0133 must remain accessible and unmodified during compression. 0134 0135 It's allowed to update compression level anytime between blocks, 0136 using LZ4_setCompressionLevel() (experimental). 0137 0138 'dst' buffer should be sized to handle worst case scenarios 0139 (see LZ4_compressBound(), it ensures compression success). 0140 In case of failure, the API does not guarantee recovery, 0141 so the state _must_ be reset. 0142 To ensure compression success 0143 whenever `dst` buffer size cannot be made >= LZ4_compressBound(), 0144 consider using LZ4_compress_HC_continue_destSize(). 0145 0146 Whenever previous input blocks can't be preserved unmodified in-place during compression of next blocks, 0147 it's possible to copy the last blocks into a more stable memory space, using LZ4_saveDictHC(). 0148 Return value of LZ4_saveDictHC() is the size of dictionary effectively saved into 'safeBuffer' (<= 64 KB) 0149 0150 After completing a streaming compression, 0151 it's possible to start a new stream of blocks, using the same LZ4_streamHC_t state, 0152 just by resetting it, using LZ4_resetStreamHC_fast(). 0153 */ 0154 0155 LZ4LIB_API void LZ4_resetStreamHC_fast(LZ4_streamHC_t* streamHCPtr, int compressionLevel); /* v1.9.0+ */ 0156 LZ4LIB_API int LZ4_loadDictHC (LZ4_streamHC_t* streamHCPtr, const char* dictionary, int dictSize); 0157 0158 LZ4LIB_API int LZ4_compress_HC_continue (LZ4_streamHC_t* streamHCPtr, 0159 const char* src, char* dst, 0160 int srcSize, int maxDstSize); 0161 0162 /*! LZ4_compress_HC_continue_destSize() : v1.9.0+ 0163 * Similar to LZ4_compress_HC_continue(), 0164 * but will read as much data as possible from `src` 0165 * to fit into `targetDstSize` budget. 0166 * Result is provided into 2 parts : 0167 * @return : the number of bytes written into 'dst' (necessarily <= targetDstSize) 0168 * or 0 if compression fails. 0169 * `srcSizePtr` : on success, *srcSizePtr will be updated to indicate how much bytes were read from `src`. 0170 * Note that this function may not consume the entire input. 0171 */ 0172 LZ4LIB_API int LZ4_compress_HC_continue_destSize(LZ4_streamHC_t* LZ4_streamHCPtr, 0173 const char* src, char* dst, 0174 int* srcSizePtr, int targetDstSize); 0175 0176 LZ4LIB_API int LZ4_saveDictHC (LZ4_streamHC_t* streamHCPtr, char* safeBuffer, int maxDictSize); 0177 0178 0179 0180 /*^********************************************** 0181 * !!!!!! STATIC LINKING ONLY !!!!!! 0182 ***********************************************/ 0183 0184 /*-****************************************************************** 0185 * PRIVATE DEFINITIONS : 0186 * Do not use these definitions directly. 0187 * They are merely exposed to allow static allocation of `LZ4_streamHC_t`. 0188 * Declare an `LZ4_streamHC_t` directly, rather than any type below. 0189 * Even then, only do so in the context of static linking, as definitions may change between versions. 0190 ********************************************************************/ 0191 0192 #define LZ4HC_DICTIONARY_LOGSIZE 16 0193 #define LZ4HC_MAXD (1<<LZ4HC_DICTIONARY_LOGSIZE) 0194 #define LZ4HC_MAXD_MASK (LZ4HC_MAXD - 1) 0195 0196 #define LZ4HC_HASH_LOG 15 0197 #define LZ4HC_HASHTABLESIZE (1 << LZ4HC_HASH_LOG) 0198 #define LZ4HC_HASH_MASK (LZ4HC_HASHTABLESIZE - 1) 0199 0200 0201 /* Never ever use these definitions directly ! 0202 * Declare or allocate an LZ4_streamHC_t instead. 0203 **/ 0204 typedef struct LZ4HC_CCtx_internal LZ4HC_CCtx_internal; 0205 struct LZ4HC_CCtx_internal 0206 { 0207 LZ4_u32 hashTable[LZ4HC_HASHTABLESIZE]; 0208 LZ4_u16 chainTable[LZ4HC_MAXD]; 0209 const LZ4_byte* end; /* next block here to continue on current prefix */ 0210 const LZ4_byte* prefixStart; /* Indexes relative to this position */ 0211 const LZ4_byte* dictStart; /* alternate reference for extDict */ 0212 LZ4_u32 dictLimit; /* below that point, need extDict */ 0213 LZ4_u32 lowLimit; /* below that point, no more dict */ 0214 LZ4_u32 nextToUpdate; /* index from which to continue dictionary update */ 0215 short compressionLevel; 0216 LZ4_i8 favorDecSpeed; /* favor decompression speed if this flag set, 0217 otherwise, favor compression ratio */ 0218 LZ4_i8 dirty; /* stream has to be fully reset if this flag is set */ 0219 const LZ4HC_CCtx_internal* dictCtx; 0220 }; 0221 0222 #define LZ4_STREAMHC_MINSIZE 262200 /* static size, for inter-version compatibility */ 0223 union LZ4_streamHC_u { 0224 char minStateSize[LZ4_STREAMHC_MINSIZE]; 0225 LZ4HC_CCtx_internal internal_donotuse; 0226 }; /* previously typedef'd to LZ4_streamHC_t */ 0227 0228 /* LZ4_streamHC_t : 0229 * This structure allows static allocation of LZ4 HC streaming state. 0230 * This can be used to allocate statically on stack, or as part of a larger structure. 0231 * 0232 * Such state **must** be initialized using LZ4_initStreamHC() before first use. 0233 * 0234 * Note that invoking LZ4_initStreamHC() is not required when 0235 * the state was created using LZ4_createStreamHC() (which is recommended). 0236 * Using the normal builder, a newly created state is automatically initialized. 0237 * 0238 * Static allocation shall only be used in combination with static linking. 0239 */ 0240 0241 /* LZ4_initStreamHC() : v1.9.0+ 0242 * Required before first use of a statically allocated LZ4_streamHC_t. 0243 * Before v1.9.0 : use LZ4_resetStreamHC() instead 0244 */ 0245 LZ4LIB_API LZ4_streamHC_t* LZ4_initStreamHC(void* buffer, size_t size); 0246 0247 0248 /*-************************************ 0249 * Deprecated Functions 0250 **************************************/ 0251 /* see lz4.h LZ4_DISABLE_DEPRECATE_WARNINGS to turn off deprecation warnings */ 0252 0253 /* deprecated compression functions */ 0254 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC (const char* source, char* dest, int inputSize); 0255 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize); 0256 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC2 (const char* source, char* dest, int inputSize, int compressionLevel); 0257 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput(const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 0258 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC_withStateHC (void* state, const char* source, char* dest, int inputSize); 0259 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput_withStateHC (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); 0260 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC2_withStateHC (void* state, const char* source, char* dest, int inputSize, int compressionLevel); 0261 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput_withStateHC(void* state, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 0262 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize); 0263 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize, int maxOutputSize); 0264 0265 /* Obsolete streaming functions; degraded functionality; do not use! 0266 * 0267 * In order to perform streaming compression, these functions depended on data 0268 * that is no longer tracked in the state. They have been preserved as well as 0269 * possible: using them will still produce a correct output. However, use of 0270 * LZ4_slideInputBufferHC() will truncate the history of the stream, rather 0271 * than preserve a window-sized chunk of history. 0272 */ 0273 #if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) 0274 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") LZ4LIB_API void* LZ4_createHC (const char* inputBuffer); 0275 LZ4_DEPRECATED("use LZ4_freeStreamHC() instead") LZ4LIB_API int LZ4_freeHC (void* LZ4HC_Data); 0276 #endif 0277 LZ4_DEPRECATED("use LZ4_saveDictHC() instead") LZ4LIB_API char* LZ4_slideInputBufferHC (void* LZ4HC_Data); 0278 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC2_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int compressionLevel); 0279 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 0280 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") LZ4LIB_API int LZ4_sizeofStreamStateHC(void); 0281 LZ4_DEPRECATED("use LZ4_initStreamHC() instead") LZ4LIB_API int LZ4_resetStreamStateHC(void* state, char* inputBuffer); 0282 0283 0284 /* LZ4_resetStreamHC() is now replaced by LZ4_initStreamHC(). 0285 * The intention is to emphasize the difference with LZ4_resetStreamHC_fast(), 0286 * which is now the recommended function to start a new stream of blocks, 0287 * but cannot be used to initialize a memory segment containing arbitrary garbage data. 0288 * 0289 * It is recommended to switch to LZ4_initStreamHC(). 0290 * LZ4_resetStreamHC() will generate deprecation warnings in a future version. 0291 */ 0292 LZ4LIB_API void LZ4_resetStreamHC (LZ4_streamHC_t* streamHCPtr, int compressionLevel); 0293 0294 0295 #if defined (__cplusplus) 0296 } 0297 #endif 0298 0299 #endif /* LZ4_HC_H_19834876238432 */ 0300 0301 0302 /*-************************************************** 0303 * !!!!! STATIC LINKING ONLY !!!!! 0304 * Following definitions are considered experimental. 0305 * They should not be linked from DLL, 0306 * as there is no guarantee of API stability yet. 0307 * Prototypes will be promoted to "stable" status 0308 * after successful usage in real-life scenarios. 0309 ***************************************************/ 0310 #ifdef LZ4_HC_STATIC_LINKING_ONLY /* protection macro */ 0311 #ifndef LZ4_HC_SLO_098092834 0312 #define LZ4_HC_SLO_098092834 0313 0314 #define LZ4_STATIC_LINKING_ONLY /* LZ4LIB_STATIC_API */ 0315 #include "lz4.h" 0316 0317 #if defined (__cplusplus) 0318 extern "C" { 0319 #endif 0320 0321 /*! LZ4_setCompressionLevel() : v1.8.0+ (experimental) 0322 * It's possible to change compression level 0323 * between successive invocations of LZ4_compress_HC_continue*() 0324 * for dynamic adaptation. 0325 */ 0326 LZ4LIB_STATIC_API void LZ4_setCompressionLevel( 0327 LZ4_streamHC_t* LZ4_streamHCPtr, int compressionLevel); 0328 0329 /*! LZ4_favorDecompressionSpeed() : v1.8.2+ (experimental) 0330 * Opt. Parser will favor decompression speed over compression ratio. 0331 * Only applicable to levels >= LZ4HC_CLEVEL_OPT_MIN. 0332 */ 0333 LZ4LIB_STATIC_API void LZ4_favorDecompressionSpeed( 0334 LZ4_streamHC_t* LZ4_streamHCPtr, int favor); 0335 0336 /*! LZ4_resetStreamHC_fast() : v1.9.0+ 0337 * When an LZ4_streamHC_t is known to be in a internally coherent state, 0338 * it can often be prepared for a new compression with almost no work, only 0339 * sometimes falling back to the full, expensive reset that is always required 0340 * when the stream is in an indeterminate state (i.e., the reset performed by 0341 * LZ4_resetStreamHC()). 0342 * 0343 * LZ4_streamHCs are guaranteed to be in a valid state when: 0344 * - returned from LZ4_createStreamHC() 0345 * - reset by LZ4_resetStreamHC() 0346 * - memset(stream, 0, sizeof(LZ4_streamHC_t)) 0347 * - the stream was in a valid state and was reset by LZ4_resetStreamHC_fast() 0348 * - the stream was in a valid state and was then used in any compression call 0349 * that returned success 0350 * - the stream was in an indeterminate state and was used in a compression 0351 * call that fully reset the state (LZ4_compress_HC_extStateHC()) and that 0352 * returned success 0353 * 0354 * Note: 0355 * A stream that was last used in a compression call that returned an error 0356 * may be passed to this function. However, it will be fully reset, which will 0357 * clear any existing history and settings from the context. 0358 */ 0359 LZ4LIB_STATIC_API void LZ4_resetStreamHC_fast( 0360 LZ4_streamHC_t* LZ4_streamHCPtr, int compressionLevel); 0361 0362 /*! LZ4_compress_HC_extStateHC_fastReset() : 0363 * A variant of LZ4_compress_HC_extStateHC(). 0364 * 0365 * Using this variant avoids an expensive initialization step. It is only safe 0366 * to call if the state buffer is known to be correctly initialized already 0367 * (see above comment on LZ4_resetStreamHC_fast() for a definition of 0368 * "correctly initialized"). From a high level, the difference is that this 0369 * function initializes the provided state with a call to 0370 * LZ4_resetStreamHC_fast() while LZ4_compress_HC_extStateHC() starts with a 0371 * call to LZ4_resetStreamHC(). 0372 */ 0373 LZ4LIB_STATIC_API int LZ4_compress_HC_extStateHC_fastReset ( 0374 void* state, 0375 const char* src, char* dst, 0376 int srcSize, int dstCapacity, 0377 int compressionLevel); 0378 0379 /*! LZ4_attach_HC_dictionary() : 0380 * This is an experimental API that allows for the efficient use of a 0381 * static dictionary many times. 0382 * 0383 * Rather than re-loading the dictionary buffer into a working context before 0384 * each compression, or copying a pre-loaded dictionary's LZ4_streamHC_t into a 0385 * working LZ4_streamHC_t, this function introduces a no-copy setup mechanism, 0386 * in which the working stream references the dictionary stream in-place. 0387 * 0388 * Several assumptions are made about the state of the dictionary stream. 0389 * Currently, only streams which have been prepared by LZ4_loadDictHC() should 0390 * be expected to work. 0391 * 0392 * Alternatively, the provided dictionary stream pointer may be NULL, in which 0393 * case any existing dictionary stream is unset. 0394 * 0395 * A dictionary should only be attached to a stream without any history (i.e., 0396 * a stream that has just been reset). 0397 * 0398 * The dictionary will remain attached to the working stream only for the 0399 * current stream session. Calls to LZ4_resetStreamHC(_fast) will remove the 0400 * dictionary context association from the working stream. The dictionary 0401 * stream (and source buffer) must remain in-place / accessible / unchanged 0402 * through the lifetime of the stream session. 0403 */ 0404 LZ4LIB_STATIC_API void LZ4_attach_HC_dictionary( 0405 LZ4_streamHC_t *working_stream, 0406 const LZ4_streamHC_t *dictionary_stream); 0407 0408 #if defined (__cplusplus) 0409 } 0410 #endif 0411 0412 #endif /* LZ4_HC_SLO_098092834 */ 0413 #endif /* LZ4_HC_STATIC_LINKING_ONLY */
[ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
This page was automatically generated by the 2.3.5 LXR engine. The LXR team |