diff options
| -rw-r--r-- | doc/lz4_manual.html | 25 | ||||
| -rw-r--r-- | doc/lz4frame_manual.html | 22 | ||||
| -rw-r--r-- | lib/lz4frame.h | 21 |
3 files changed, 42 insertions, 26 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index 5e04263..4c4734a 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -304,19 +304,22 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, <BR></pre> <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()). +</b><p> Use this to prepare a context for a new chain of calls to a streaming API + (e.g., LZ4_compress_fast_continue()). + + Note: + To stay on the safe side, when LZ4_stream_t is used for the first time, + it should be either created using LZ4_createStream() or + initialized using LZ4_resetStream(). Note: 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()). + When an LZ4_stream_t is known to be in an internally coherent state, + it will be prepared for a new compression with almost no work. + Otherwise, it will fall back to the full, expensive reset. LZ4_streams are guaranteed to be in a valid state when: - returned from LZ4_createStream() @@ -329,9 +332,11 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, call that fully reset the state (e.g., LZ4_compress_fast_extState()) and that returned success - When a stream isn't known to be in a valid state, it is not safe to pass to - any fastReset or streaming function. It must first be cleansed by the full - LZ4_resetStream(). + Note: + A stream that was used in a compression call that did not return success + (e.g., LZ4_compress_fast_continue()), can still be passed to this function, + however, it's history is not preserved because of previous compression + failure. </p></pre><BR> diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html index 72e6782..2b16045 100644 --- a/doc/lz4frame_manual.html +++ b/doc/lz4frame_manual.html @@ -157,15 +157,19 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); </p></pre><BR> <pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); -</b><p> Provides minimum dstCapacity required to guarantee compression success - given a srcSize and preferences, covering worst case scenario. +</b><p> Provides minimum dstCapacity required to guarantee success of + LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. + When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. + Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). + When invoking LZ4F_compressUpdate() multiple times, + if the output buffer is gradually filled up instead of emptied and re-used from its start, + one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). + @return is always the same for a srcSize and prefsPtr. prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. - Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(), - Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. - It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd(). - Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin(). - Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. - When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. + tech details : + @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. + It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). + @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). </p></pre><BR> @@ -194,6 +198,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default. @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx) or an error code if it fails (which can be tested using LZ4F_isError()) + Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). </p></pre><BR> @@ -206,6 +211,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default. @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark), or an error code if it fails (which can be tested using LZ4F_isError()) + Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr). A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task. </p></pre><BR> diff --git a/lib/lz4frame.h b/lib/lz4frame.h index 599f17e..7c7c34e 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -248,6 +248,7 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx); /*---- Compression ----*/ #define LZ4F_HEADER_SIZE_MAX 19 /* LZ4 Frame header size can vary from 7 to 19 bytes */ + /*! LZ4F_compressBegin() : * will write the frame header into dstBuffer. * dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes. @@ -260,15 +261,19 @@ LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, const LZ4F_preferences_t* prefsPtr); /*! LZ4F_compressBound() : - * Provides minimum dstCapacity required to guarantee compression success - * given a srcSize and preferences, covering worst case scenario. + * Provides minimum dstCapacity required to guarantee success of + * LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario. + * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead. + * Note that the result is only valid for a single invocation of LZ4F_compressUpdate(). + * When invoking LZ4F_compressUpdate() multiple times, + * if the output buffer is gradually filled up instead of emptied and re-used from its start, + * one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound(). + * @return is always the same for a srcSize and prefsPtr. * prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario. - * Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(), - * Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. - * It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd(). - * Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin(). - * Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers. - * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations. + * tech details : + * @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes. + * It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd(). + * @return doesn't include frame header, as it was already generated by LZ4F_compressBegin(). */ LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr); |