AuroraMiddleware/lz4
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

updated code documentation

Browse Source 
to clarify #589
This commit is contained in:
Yann Collet 2018-10-15 11:14:30 -07:00
parent 5bd197e838
commit bf9bf80f8d
3 changed files with 42 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/lz4_manual.html
View File

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

22
doc/lz4frame_manual.html
View File

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

21
lib/lz4frame.h
View File

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