diff options
Diffstat (limited to 'doc/lz4_manual.html')
-rw-r--r-- | doc/lz4_manual.html | 94 |
1 files changed, 50 insertions, 44 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index b738c8d..1c6dba7 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -155,9 +155,27 @@ 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>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. +<pre><b>void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); +</b><p> Use this to prepare an LZ4_stream_t for a new chain of dependent blocks + (e.g., LZ4_compress_fast_continue()). + + An LZ4_stream_t must be initialized once before usage. + This is automatically done when created by LZ4_createStream(). + However, should the LZ4_stream_t be simply declared on stack (for example), + it's necessary to initialize it first, using LZ4_initStream(). + + After init, start any new stream with LZ4_resetStream_fast(). + A same LZ4_stream_t can be re-used multiple times consecutively + and compress multiple streams, + provided that it starts each new stream with LZ4_resetStream_fast(). + + LZ4_resetStream_fast() is much faster than LZ4_initStream(), + but is not compatible with memory regions containing garbage data. + + Note: it's only useful to call LZ4_resetStream_fast() + in the context of streaming compression. + The *extState* functions perform their own resets. + Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive. </p></pre><BR> @@ -290,43 +308,6 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream); define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library. <BR></pre> -<pre><b>LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr); -</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 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() - - reset by LZ4_resetStream() - - memset(stream, 0, sizeof(LZ4_stream_t)), though this is discouraged - - the stream was in a valid state and was reset by LZ4_resetStream_fast() - - the stream was in a valid state and was then used in any compression call - that returned success - - the stream was in an indeterminate state and was used in a compression - call that fully reset the state (e.g., LZ4_compress_fast_extState()) and - that returned success - - 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> - <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(). @@ -394,10 +375,27 @@ union LZ4_stream_u { 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 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 ! + LZ4_stream_t can also be created using LZ4_createStream(), which is recommended. + The structure definition can be convenient for static allocation + (on stack, or as part of larger structure). + Init this structure with LZ4_initStream() before first use. + note : only use this definition in association with static linking ! + this definition is not API/ABI safe, and may change in a future version. + +</p></pre><BR> + +<pre><b>LZ4_stream_t* LZ4_initStream (void* buffer, size_t size); +</b><p> An LZ4_stream_t structure must be initialized at least once. + This is automatically done when invoking LZ4_createStream(), + but it's not when the structure is simply declared on stack (for example). + + Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t. + It can also initialize any arbitrary buffer of sufficient size, + and will @return a pointer of proper type upon initialization. + + Note : initialization fails if size and alignment conditions are not respected. + In which case, the function will @return NULL. + Note2: An LZ4_stream_t structure guarantees correct alignment and size. </p></pre><BR> @@ -477,5 +475,13 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, </p></pre><BR> +<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr); +</b><p> An LZ4_stream_t structure must be initialized at least once. + This is done with LZ4_initStream(), or LZ4_resetStream(). + Consider switching to LZ4_initStream(), + invoking LZ4_resetStream() will trigger deprecation warnings in the future. + +</p></pre><BR> + </html> </body> |