created LZ4_initStream()

- promoted LZ4_resetStream_fast() to stable
- moved LZ4_resetStream() into deprecate, but without triggering a compiler warning
- update all sources to no longer rely on LZ4_resetStream()

note : LZ4_initStream() proposal is slightly different :
it's able to initialize any buffer, provided that it's large enough.
To this end, it accepts a void*, and returns an LZ4_stream_t*.

1 files changed, 43 insertions, 44 deletions

diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index b738c8d..5db3ec9 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -155,9 +155,23 @@ 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.
+  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 first using LZ4_initStream().
+
+  After that, 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.
+  For this reason, LZ4_stream_t must be initialized at least once,
  
 </p></pre><BR>
 
@@ -290,43 +304,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 +371,24 @@ 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.
+  While this is automatically done when invoking LZ4_createStream(),
+  it's not when the structure is simply declared on stack (for example).
+  Use this function to properly initialize a newly declared LZ4_stream_t.
+  It can also accept any arbitrary buffer of sufficient size as input,
+  and will return a pointer of proper type upon initialization.
+  Note : initialization can fail if size < sizeof(LZ4_stream_t).
+  In which case, the function will @return NULL.
  
 </p></pre><BR>
 
@@ -477,5 +468,13 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
  
 </p></pre><BR>
 
+<pre><b>//LZ4LIB_API 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>