From bf9bf80f8d06aab75347ed6df62758511e91fbe3 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Mon, 15 Oct 2018 11:14:30 -0700 Subject: updated code documentation to clarify #589 --- doc/lz4_manual.html | 25 +++++++++++++++---------- doc/lz4frame_manual.html | 22 ++++++++++++++-------- 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, 
LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-
  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()).
+
  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.

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); 


size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
-
  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().

@@ -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).


@@ -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.


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); -- cgit v0.12