diff options
| -rw-r--r-- | doc/lz4_manual.html | 131 | ||||
| -rw-r--r-- | doc/lz4frame_manual.html | 14 | ||||
| -rw-r--r-- | lib/lz4.h | 155 |
3 files changed, 152 insertions, 148 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index 6ebf8d28..39a48f39 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -21,7 +21,7 @@ </ol> <hr> <a name="Chapter1"></a><h2>Introduction</h2><pre> - LZ4 is lossless compression algorithm, providing compression speed at 400 MB/s per core, + LZ4 is lossless compression algorithm, providing compression speed at 500 MB/s per core, scalable with multi-cores CPU. It features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. @@ -37,15 +37,15 @@ An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md), take care of encoding standard metadata alongside LZ4-compressed blocks. - If your application requires interoperability, it's recommended to use it. - A library is provided to take care of it, see lz4frame.h. + Frame format is required for interoperability. + It is delivered through a companion API, declared in lz4frame.h. <BR></pre> <a name="Chapter2"></a><h2>Version</h2><pre></pre> <pre><b>int LZ4_versionNumber (void); </b>/**< library version number; useful to check dll version */<b> </b></pre><BR> -<pre><b>const char* LZ4_versionString (void); </b>/**< library version string; unseful to check dll version */<b> +<pre><b>const char* LZ4_versionString (void); </b>/**< library version string; useful to check dll version */<b> </b></pre><BR> <a name="Chapter3"></a><h2>Tuning parameter</h2><pre></pre> @@ -53,8 +53,8 @@ # define LZ4_MEMORY_USAGE 14 #endif </b><p> Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) - Increasing memory usage improves compression ratio - Reduced memory usage may improve speed, thanks to cache effect + Increasing memory usage improves compression ratio. + Reduced memory usage may improve speed, thanks to better cache locality. Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache </p></pre><BR> @@ -68,21 +68,21 @@ It also runs faster, so it's a recommended setting. If the function cannot compress 'src' into a more limited 'dst' budget, compression stops *immediately*, and the function result is zero. - Note : as a consequence, 'dst' content is not valid. - Note 2 : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). + In which case, 'dst' content is undefined (invalid). srcSize : max supported value is LZ4_MAX_INPUT_SIZE. dstCapacity : size of buffer 'dst' (which must be already allocated) - return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) - or 0 if compression fails + @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) + or 0 if compression fails + Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). </p></pre><BR> <pre><b>int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); </b><p> compressedSize : is the exact complete size of the compressed block. dstCapacity : is the size of destination buffer, which must be already allocated. - return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) + @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) If destination buffer is not large enough, decoding will stop and output an error code (negative value). If the source stream is detected malformed, the function will stop decoding and return a negative result. - This function is protected against malicious data packets. + Note : This function is protected against malicious data packets (never writes outside 'dst' buffer, nor read outside 'source' buffer). </p></pre><BR> <a name="Chapter5"></a><h2>Advanced Functions</h2><pre></pre> @@ -107,10 +107,11 @@ <pre><b>int LZ4_sizeofState(void); int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); -</b><p> Same compression function, just using an externally allocated memory space to store compression state. - Use LZ4_sizeofState() to know how much memory must be allocated, - and allocate it on 8-bytes boundaries (using malloc() typically). - Then, provide this buffer as 'void* state' to compression function. +</b><p> Same as LZ4_compress_fast(), using an externally allocated memory space for its state. + Use LZ4_sizeofState() to know how much memory must be allocated, + and allocate it on 8-bytes boundaries (using `malloc()` typically). + Then, provide this buffer as `void* state` to compression function. + </p></pre><BR> <pre><b>int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePtr, int targetDstSize); @@ -132,7 +133,7 @@ int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int src and now `LZ4_decompress_safe()` can be as fast and sometimes faster than `LZ4_decompress_fast()`. Moreover, LZ4_decompress_fast() is not protected vs malformed input, as it doesn't perform full validation of compressed data. As a consequence, this function is no longer recommended, and may be deprecated in future versions. - It's only remaining specificity is that it can decompress data without knowing its compressed size. + It's last remaining specificity is that it can decompress data without knowing its compressed size. originalSize : is the uncompressed size to regenerate. `dst` must be already allocated, its size must be >= 'originalSize' bytes. @@ -175,13 +176,6 @@ int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int src <a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre> -<pre><b>LZ4_stream_t* LZ4_createStream(void); -int LZ4_freeStream (LZ4_stream_t* streamPtr); -</b><p> LZ4_createStream() will allocate and initialize an `LZ4_stream_t` structure. - LZ4_freeStream() releases its memory. - -</p></pre><BR> - <pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); </b><p> An LZ4_stream_t structure can be allocated once and re-used multiple times. Use this function to start compressing a new stream. @@ -198,7 +192,7 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr); <pre><b>int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); </b><p> Compress 'src' content using data from previously compressed blocks, for better compression ratio. - 'dst' buffer must be already allocated. + 'dst' buffer must be already allocated. If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. @return : size of compressed block @@ -206,10 +200,10 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr); Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. Each block has precise boundaries. + Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. - Each block must be decompressed separately, calling LZ4_decompress_*() with associated metadata. - Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory! + Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. Make sure that buffers are separated, by at least one byte. @@ -217,7 +211,7 @@ int LZ4_freeStream (LZ4_stream_t* streamPtr); Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. - Note 5 : After an error, the stream status is invalid, it can only be reset or freed. + Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. </p></pre><BR> @@ -250,7 +244,7 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); </p></pre><BR> <pre><b>int LZ4_decoderRingBufferSize(int maxBlockSize); -#define LZ4_DECODER_RING_BUFFER_SIZE(mbs) (65536 + 14 + (mbs)) </b>/* for static allocation; mbs presumed valid */<b> +#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) </b>/* for static allocation; maxBlockSize presumed valid */<b> </b><p> Note : in a ring buffer scenario (optional), blocks are presumed decompressed next to each other up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), @@ -295,32 +289,34 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, </b><p> These decoding functions work the same as a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue() They are stand-alone, and don't need an LZ4_streamDecode_t structure. - Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. + Dictionary is presumed stable : it must remain accessible and unmodified during decompression. + Performance tip : Decompression speed can be substantially increased + when dst == dictStart + dictSize. </p></pre><BR> <a name="Chapter8"></a><h2>Unstable declarations</h2><pre> - Declarations in this section should be considered unstable. - Use at your own peril, etc., etc. - They may be removed in the future. - Their signatures may change. + Declarations in this section must be considered unstable. + Their signatures may change, or may be removed in the future. + They are therefore only safe to depend on + when the caller is statically linked against the library. + To access their declarations, define LZ4_STATIC_LINKING_ONLY. <BR></pre> -<pre><b>void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); +<pre><b>LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); </b><p> Use this, like LZ4_resetStream(), to prepare a context for a new chain of calls to a streaming API (e.g., LZ4_compress_fast_continue()). Note: - Using this in advance of a non- streaming-compression function is redundant, - and potentially bad for performance, since they all perform their own custom - reset internally. + Using this in advance of a non-streaming-compression function is redundant, + since they all perform their own custom reset internally. Differences from LZ4_resetStream(): When an LZ4_stream_t is known to be in a internally coherent state, - it can often be prepared for a new compression with almost no work, only - sometimes falling back to the full, expensive reset that is always required - when the stream is in an indeterminate state (i.e., the reset performed by - LZ4_resetStream()). + it can often be prepared for a new compression with almost no work, + only sometimes falling back to the full, expensive reset + that is always required when the stream is in an indeterminate state + (i.e., the reset performed by LZ4_resetStream()). LZ4_streams are guaranteed to be in a valid state when: - returned from LZ4_createStream() @@ -339,22 +335,21 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, </p></pre><BR> -<pre><b>int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); +<pre><b>LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); </b><p> A variant of LZ4_compress_fast_extState(). - Using this variant avoids an expensive initialization step. It is only safe - to call if the state buffer is known to be correctly initialized already - (see above comment on LZ4_resetStream_fast() for a definition of "correctly - initialized"). From a high level, the difference is that this function - initializes the provided state with a call to something like - LZ4_resetStream_fast() while LZ4_compress_fast_extState() starts with a - call to LZ4_resetStream(). + Using this variant avoids an expensive initialization step. + It is only safe to call if the state buffer is known to be correctly initialized already + (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). + From a high level, the difference is that + this function initializes the provided state with a call to something like LZ4_resetStream_fast() + while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). </p></pre><BR> -<pre><b>void LZ4_attach_dictionary(LZ4_stream_t *working_stream, const LZ4_stream_t *dictionary_stream); -</b><p> This is an experimental API that allows for the efficient use of a - static dictionary many times. +<pre><b>LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const LZ4_stream_t* dictionaryStream); +</b><p> This is an experimental API that allows + efficient use of a static dictionary many times. Rather than re-loading the dictionary buffer into a working context before each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a @@ -365,8 +360,8 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, Currently, only streams which have been prepared by LZ4_loadDict() should be expected to work. - Alternatively, the provided dictionary stream pointer may be NULL, in which - case any existing dictionary stream is unset. + Alternatively, the provided dictionaryStream may be NULL, + in which case any existing dictionary stream is unset. If a dictionary is provided, it replaces any pre-existing stream history. The dictionary contents are the only history that can be referenced and @@ -381,9 +376,9 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, </p></pre><BR> <a name="Chapter9"></a><h2>Private definitions</h2><pre> - Do not use these definitions. - They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. - Using these definitions will expose code to API and/or ABI break in future versions of the library. + Do not use these definitions directly. + They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. + Accessing members will expose code to API and/or ABI break in future versions of the library. <BR></pre> <pre><b>typedef struct { @@ -406,11 +401,11 @@ union LZ4_stream_u { unsigned long long table[LZ4_STREAMSIZE_U64]; LZ4_stream_t_internal internal_donotuse; } ; </b>/* previously typedef'd to LZ4_stream_t */<b> -</b><p> information structure to track an LZ4 stream. - init this structure before first use. - note : only use in association with static linking ! - this definition is not API/ABI safe, - it may change in a future version ! +</b><p> information structure to track an LZ4 stream. + init this structure with LZ4_resetStream() before first use. + note : only use in association with static linking ! + this definition is not API/ABI safe, + it may change in a future version ! </p></pre><BR> @@ -420,11 +415,11 @@ union LZ4_streamDecode_u { unsigned long long table[LZ4_STREAMDECODESIZE_U64]; LZ4_streamDecode_t_internal internal_donotuse; } ; </b>/* previously typedef'd to LZ4_streamDecode_t */<b> -</b><p> information structure to track an LZ4 stream during decompression. - init this structure using LZ4_setStreamDecode (or memset()) before first use - note : only use in association with static linking ! - this definition is not API/ABI safe, - and may change in a future version ! +</b><p> information structure to track an LZ4 stream during decompression. + init this structure using LZ4_setStreamDecode() before first use. + note : only use in association with static linking ! + this definition is not API/ABI safe, + and may change in a future version ! </p></pre><BR> diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index fb8e0ceb..af1853e3 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -84,19 +84,21 @@ LZ4F_blockChecksum_t blockChecksumFlag; </b>/* 1: each block followed by a checksum of block's compressed data; 0: disabled (default) */<b> } LZ4F_frameInfo_t; </b><p> makes it possible to set or read frame parameters. - It's not required to set all fields, as long as the structure was initially memset() to zero. - For all fields, 0 sets it to default value + Structure must be first init to 0, using memset() or LZ4F_INIT_FRAMEINFO, + setting all parameters to default. + It's then possible to update selectively some parameters </p></pre><BR> <pre><b>typedef struct { LZ4F_frameInfo_t frameInfo; int compressionLevel; </b>/* 0: default (fast mode); values > LZ4HC_CLEVEL_MAX count as LZ4HC_CLEVEL_MAX; values < 0 trigger "fast acceleration" */<b> - unsigned autoFlush; </b>/* 1: always flush, to reduce usage of internal buffers */<b> - unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4LZ4HC_CLEVEL_OPT_MIN) */ /* >= v1.8.2 */<b> + unsigned autoFlush; </b>/* 1: always flush; reduces usage of internal buffers */<b> + unsigned favorDecSpeed; </b>/* 1: parser favors decompression speed vs compression ratio. Only works for high compression modes (>= LZ4HC_CLEVEL_OPT_MIN) */ /* v1.8.2+ */<b> unsigned reserved[3]; </b>/* must be zero for forward compatibility */<b> } LZ4F_preferences_t; -</b><p> makes it possible to supply detailed compression parameters to the stream interface. - Structure is presumed initially memset() to zero, representing default settings. +</b><p> makes it possible to supply advanced compression instructions to streaming interface. + Structure must be first init to 0, using memset() or LZ4F_INIT_PREFERENCES, + setting all parameters to default. All reserved fields must be set to zero. </p></pre><BR> @@ -103,7 +103,7 @@ extern "C" { #define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION) LZ4LIB_API int LZ4_versionNumber (void); /**< library version number; useful to check dll version */ -LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; unseful to check dll version */ +LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; useful to check dll version */ /*-************************************ @@ -112,14 +112,15 @@ LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; /*! * LZ4_MEMORY_USAGE : * Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) - * Increasing memory usage improves compression ratio - * Reduced memory usage may improve speed, thanks to cache effect + * Increasing memory usage improves compression ratio. + * Reduced memory usage may improve speed, thanks to better cache locality. * Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache */ #ifndef LZ4_MEMORY_USAGE # define LZ4_MEMORY_USAGE 14 #endif + /*-************************************ * Simple Functions **************************************/ @@ -130,21 +131,22 @@ LZ4LIB_API const char* LZ4_versionString (void); /**< library version string; It also runs faster, so it's a recommended setting. If the function cannot compress 'src' into a more limited 'dst' budget, compression stops *immediately*, and the function result is zero. - Note : as a consequence, 'dst' content is not valid. - Note 2 : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). + In which case, 'dst' content is undefined (invalid). srcSize : max supported value is LZ4_MAX_INPUT_SIZE. dstCapacity : size of buffer 'dst' (which must be already allocated) - return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) - or 0 if compression fails */ + @return : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity) + or 0 if compression fails + Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer). +*/ LZ4LIB_API int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity); /*! LZ4_decompress_safe() : compressedSize : is the exact complete size of the compressed block. dstCapacity : is the size of destination buffer, which must be already allocated. - return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) + @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity) If destination buffer is not large enough, decoding will stop and output an error code (negative value). If the source stream is detected malformed, the function will stop decoding and return a negative result. - This function is protected against malicious data packets. + Note : This function is protected against malicious data packets (never writes outside 'dst' buffer, nor read outside 'source' buffer). */ LZ4LIB_API int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity); @@ -155,8 +157,7 @@ LZ4LIB_API int LZ4_decompress_safe (const char* src, char* dst, int compressedSi #define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ #define LZ4_COMPRESSBOUND(isize) ((unsigned)(isize) > (unsigned)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize)/255) + 16) -/*! -LZ4_compressBound() : +/*! LZ4_compressBound() : Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible) This function is primarily useful for memory allocation purposes (destination buffer size). Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). @@ -167,8 +168,7 @@ LZ4_compressBound() : */ LZ4LIB_API int LZ4_compressBound(int inputSize); -/*! -LZ4_compress_fast() : +/*! LZ4_compress_fast() : Same as LZ4_compress_default(), but allows selection of "acceleration" factor. The larger the acceleration value, the faster the algorithm, but also the lesser the compression. It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed. @@ -178,13 +178,12 @@ LZ4_compress_fast() : LZ4LIB_API int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); -/*! -LZ4_compress_fast_extState() : - Same compression function, just using an externally allocated memory space to store compression state. - Use LZ4_sizeofState() to know how much memory must be allocated, - and allocate it on 8-bytes boundaries (using malloc() typically). - Then, provide this buffer as 'void* state' to compression function. -*/ +/*! LZ4_compress_fast_extState() : + * Same as LZ4_compress_fast(), using an externally allocated memory space for its state. + * Use LZ4_sizeofState() to know how much memory must be allocated, + * and allocate it on 8-bytes boundaries (using `malloc()` typically). + * Then, provide this buffer as `void* state` to compression function. + */ LZ4LIB_API int LZ4_sizeofState(void); LZ4LIB_API int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); @@ -210,7 +209,7 @@ LZ4LIB_API int LZ4_compress_destSize (const char* src, char* dst, int* srcSizePt * and now `LZ4_decompress_safe()` can be as fast and sometimes faster than `LZ4_decompress_fast()`. * Moreover, LZ4_decompress_fast() is not protected vs malformed input, as it doesn't perform full validation of compressed data. * As a consequence, this function is no longer recommended, and may be deprecated in future versions. - * It's only remaining specificity is that it can decompress data without knowing its compressed size. + * It's last remaining specificity is that it can decompress data without knowing its compressed size. * * originalSize : is the uncompressed size to regenerate. * `dst` must be already allocated, its size must be >= 'originalSize' bytes. @@ -257,10 +256,6 @@ LZ4LIB_API int LZ4_decompress_safe_partial (const char* src, char* dst, int srcS ***********************************************/ typedef union LZ4_stream_u LZ4_stream_t; /* incomplete type (defined later) */ -/*! LZ4_createStream() and LZ4_freeStream() : - * LZ4_createStream() will allocate and initialize an `LZ4_stream_t` structure. - * LZ4_freeStream() releases its memory. - */ LZ4LIB_API LZ4_stream_t* LZ4_createStream(void); LZ4LIB_API int LZ4_freeStream (LZ4_stream_t* streamPtr); @@ -280,7 +275,7 @@ LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, in /*! LZ4_compress_fast_continue() : * Compress 'src' content using data from previously compressed blocks, for better compression ratio. - * 'dst' buffer must be already allocated. + * 'dst' buffer must be already allocated. * If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. * * @return : size of compressed block @@ -288,10 +283,10 @@ LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, in * * Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block. * Each block has precise boundaries. + * Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata. * It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together. - * Each block must be decompressed separately, calling LZ4_decompress_*() with associated metadata. * - * Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory! + * Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory ! * * Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB. * Make sure that buffers are separated, by at least one byte. @@ -299,7 +294,7 @@ LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, in * * Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB. * - * Note 5 : After an error, the stream status is invalid, it can only be reset or freed. + * Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed. */ LZ4LIB_API int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); @@ -335,7 +330,7 @@ LZ4LIB_API int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_str */ LZ4LIB_API int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize); -/*! LZ4_decoderRingBufferSize() : v1.8.2 +/*! LZ4_decoderRingBufferSize() : v1.8.2+ * Note : in a ring buffer scenario (optional), * blocks are presumed decompressed next to each other * up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize), @@ -347,7 +342,7 @@ LZ4LIB_API int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const * or 0 if there is an error (invalid maxBlockSize). */ LZ4LIB_API int LZ4_decoderRingBufferSize(int maxBlockSize); -#define LZ4_DECODER_RING_BUFFER_SIZE(mbs) (65536 + 14 + (mbs)) /* for static allocation; mbs presumed valid */ +#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) /* for static allocation; maxBlockSize presumed valid */ /*! LZ4_decompress_*_continue() : * These decoding functions allow decompression of consecutive blocks in "streaming" mode. @@ -382,7 +377,9 @@ LZ4LIB_API int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecod * These decoding functions work the same as * a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue() * They are stand-alone, and don't need an LZ4_streamDecode_t structure. - * Dictionary is presumed stable : it must remain accessible and unmodified during next decompression. + * Dictionary is presumed stable : it must remain accessible and unmodified during decompression. + * Performance tip : Decompression speed can be substantially increased + * when dst == dictStart + dictSize. */ LZ4LIB_API int LZ4_decompress_safe_usingDict (const char* src, char* dst, int srcSize, int dstCapcity, const char* dictStart, int dictSize); LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize); @@ -395,29 +392,41 @@ LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int or /*-************************************ * Unstable declarations ************************************** - * Declarations in this section should be considered unstable. - * Use at your own peril, etc., etc. - * They may be removed in the future. - * Their signatures may change. + * Declarations in this section must be considered unstable. + * Their signatures may change, or may be removed in the future. + * They are therefore only safe to depend on + * when the caller is statically linked against the library. + * To access their declarations, define LZ4_STATIC_LINKING_ONLY. **************************************/ #ifdef LZ4_STATIC_LINKING_ONLY +/* By default, symbols in this section aren't published into shared/dynamic libraries. + * You can override this behavior and force them to be published + * by defining LZ4_PUBLISH_STATIC_FUNCTIONS. + * Use at your own risk. + */ + +#ifdef LZ4_PUBLISH_STATIC_FUNCTIONS +#define LZ4LIB_STATIC_API LZ4LIB_API +#else +#define LZ4LIB_STATIC_API +#endif + /*! LZ4_resetStream_fast() : * Use this, like LZ4_resetStream(), to prepare a context for a new chain of * calls to a streaming API (e.g., LZ4_compress_fast_continue()). * * Note: - * Using this in advance of a non- streaming-compression function is redundant, - * and potentially bad for performance, since they all perform their own custom - * reset internally. + * Using this in advance of a non-streaming-compression function is redundant, + * since they all perform their own custom reset internally. * * Differences from LZ4_resetStream(): * When an LZ4_stream_t is known to be in a internally coherent state, - * it can often be prepared for a new compression with almost no work, only - * sometimes falling back to the full, expensive reset that is always required - * when the stream is in an indeterminate state (i.e., the reset performed by - * LZ4_resetStream()). + * it can often be prepared for a new compression with almost no work, + * only sometimes falling back to the full, expensive reset + * that is always required when the stream is in an indeterminate state + * (i.e., the reset performed by LZ4_resetStream()). * * LZ4_streams are guaranteed to be in a valid state when: * - returned from LZ4_createStream() @@ -434,24 +443,23 @@ LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int or * any fastReset or streaming function. It must first be cleansed by the full * LZ4_resetStream(). */ -LZ4LIB_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); +LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); /*! LZ4_compress_fast_extState_fastReset() : * A variant of LZ4_compress_fast_extState(). * - * Using this variant avoids an expensive initialization step. It is only safe - * to call if the state buffer is known to be correctly initialized already - * (see above comment on LZ4_resetStream_fast() for a definition of "correctly - * initialized"). From a high level, the difference is that this function - * initializes the provided state with a call to something like - * LZ4_resetStream_fast() while LZ4_compress_fast_extState() starts with a - * call to LZ4_resetStream(). + * Using this variant avoids an expensive initialization step. + * It is only safe to call if the state buffer is known to be correctly initialized already + * (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized"). + * From a high level, the difference is that + * this function initializes the provided state with a call to something like LZ4_resetStream_fast() + * while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream(). */ -LZ4LIB_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); +LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration); /*! LZ4_attach_dictionary() : - * This is an experimental API that allows for the efficient use of a - * static dictionary many times. + * This is an experimental API that allows + * efficient use of a static dictionary many times. * * Rather than re-loading the dictionary buffer into a working context before * each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a @@ -462,8 +470,8 @@ LZ4LIB_API int LZ4_compress_fast_extState_fastReset (void* state, const char* sr * Currently, only streams which have been prepared by LZ4_loadDict() should * be expected to work. * - * Alternatively, the provided dictionary stream pointer may be NULL, in which - * case any existing dictionary stream is unset. + * Alternatively, the provided dictionaryStream may be NULL, + * in which case any existing dictionary stream is unset. * * If a dictionary is provided, it replaces any pre-existing stream history. * The dictionary contents are the only history that can be referenced and @@ -475,16 +483,17 @@ LZ4LIB_API int LZ4_compress_fast_extState_fastReset (void* state, const char* sr * stream (and source buffer) must remain in-place / accessible / unchanged * through the completion of the first compression call on the stream. */ -LZ4LIB_API void LZ4_attach_dictionary(LZ4_stream_t *working_stream, const LZ4_stream_t *dictionary_stream); +LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const LZ4_stream_t* dictionaryStream); #endif + /*-************************************ * Private definitions ************************************** - * Do not use these definitions. - * They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. - * Using these definitions will expose code to API and/or ABI break in future versions of the library. + * Do not use these definitions directly. + * They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`. + * Accessing members will expose code to API and/or ABI break in future versions of the library. **************************************/ #define LZ4_HASHLOG (LZ4_MEMORY_USAGE-2) #define LZ4_HASHTABLESIZE (1 << LZ4_MEMORY_USAGE) @@ -533,13 +542,12 @@ typedef struct { #endif -/*! - * LZ4_stream_t : - * information structure to track an LZ4 stream. - * init this structure before first use. - * note : only use in association with static linking ! - * this definition is not API/ABI safe, - * it may change in a future version ! +/*! LZ4_stream_t : + * information structure to track an LZ4 stream. + * init this structure with LZ4_resetStream() before first use. + * note : only use in association with static linking ! + * this definition is not API/ABI safe, + * it may change in a future version ! */ #define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4) #define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long)) @@ -549,13 +557,12 @@ union LZ4_stream_u { } ; /* previously typedef'd to LZ4_stream_t */ -/*! - * LZ4_streamDecode_t : - * information structure to track an LZ4 stream during decompression. - * init this structure using LZ4_setStreamDecode (or memset()) before first use - * note : only use in association with static linking ! - * this definition is not API/ABI safe, - * and may change in a future version ! +/*! LZ4_streamDecode_t : + * information structure to track an LZ4 stream during decompression. + * init this structure using LZ4_setStreamDecode() before first use. + * note : only use in association with static linking ! + * this definition is not API/ABI safe, + * and may change in a future version ! */ #define LZ4_STREAMDECODESIZE_U64 4 #define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long)) |