zstd-ruby 1.5.5.0 → 1.5.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76dbffc6a0a13fccd92ea93abd90e33c4a26ab2ac2972877b7928a515e37033e
-  data.tar.gz: 21e3eba574ac94d9f34ac0d33732435ed3fd2373e9db921702a74d2a2c9d606a
+  metadata.gz: 1fe1a5bcfa102673b36ea9a48096636faa76535095211998cddfe316775a3d78
+  data.tar.gz: e2a96d0d1d2bdda0bc3d34080df219aeaa8c5274a2dac7a838730fce54ebe4f6
 SHA512:
-  metadata.gz: 4f8c40ad6eaa9b014467fc57651f857713767f7930b2e7e2060c50ff58d05262416d0e9cb1427f440298af577eeef5247daec1866a55003ca6d9b2e2ea6212de
-  data.tar.gz: 5836f8061f7588081df400bf0705fcc74003029ec9ef9225e43f5ba5a0b19ec747af71cf0e34f150212a5efd90b9e1ea5ebe49a7231297e3f2ab8080bbf8247d
+  metadata.gz: 6bdffd7e5b2d824fdf5ebad116ef4b965c4d4d2a77898df5a51623020db6fddf0e4562aa4d80de7f8978fa5f557ce85e56d19042667c379b3ac97c3a274a9d11
+  data.tar.gz: 639a3d64cf8a8fa36a10cf180560a4102516d4da21e3100c1cdd724732fb583449c828ac4eeef6f9bad89c2f22467f7adf80b083116121ccff8d356c58246966

data/.gitignore

@@ -19,3 +19,5 @@ vendor/
 .rspec_status
 
 .ruby-version
+
+.vscode

data/README.md

@@ -10,7 +10,7 @@ See https://github.com/facebook/zstd
 Fork from https://github.com/jarredholman/ruby-zstd.
 
 ## Zstd version
-v1.5.5 (https://github.com/facebook/zstd/tree/v1.5.5)
+[v1.5.6](https://github.com/facebook/zstd/tree/v1.5.6)
 
 ## Installation
 
@@ -34,20 +34,22 @@ Or install it yourself as:
 require 'zstd-ruby'
 ```
 
-### Simple Compression
+### Compression
+
+#### Simple Compression
 
 ```ruby
 compressed_data = Zstd.compress(data)
-compressed_data = Zstd.compress(data, complession_level) # default compression_level is 0
+compressed_data = Zstd.compress(data, level: complession_level) # default compression_level is 3
 ```
 
-### Compression using Dictionary
+#### Compression with Dictionary
 ```ruby
 # dictionary is supposed to have been created using `zstd --train`
-compressed_using_dict = Zstd.compress_using_dict("", IO.read('dictionary_file'))
+compressed_using_dict = Zstd.compress("", dict: File.read('dictionary_file'))
 ```
 
-### Streaming Compression
+#### Streaming Compression
 ```ruby
 stream = Zstd::StreamingCompress.new
 stream << "abc" << "def"
@@ -66,19 +68,39 @@ res << stream.compress("def")
 res << stream.finish
 ```
 
-### Simple Decompression
+#### Streaming Compression with Dictionary
+```ruby
+stream = Zstd::StreamingCompress.new(dict: File.read('dictionary_file'))
+stream << "abc" << "def"
+res = stream.flush
+stream << "ghi"
+res << stream.finish
+```
+
+#### Streaming Compression with level and Dictionary
+```ruby
+stream = Zstd::StreamingCompress.new(level: 5, dict: File.read('dictionary_file'))
+stream << "abc" << "def"
+res = stream.flush
+stream << "ghi"
+res << stream.finish
+```
+
+### Decompression
+
+#### Simple Decompression
 
 ```ruby
 data = Zstd.decompress(compressed_data)
 ```
 
-### Decomporession using Dictionary
+#### Decompression with Dictionary
 ```ruby
 # dictionary is supposed to have been created using `zstd --train`
-Zstd.decompress_using_dict(compressed_using_dict, IO.read('dictionary_file'))
+Zstd.decompress(compressed_using_dict, dict: File.read('dictionary_file'))
 ```
 
-### Streaming Decompression
+#### Streaming Decompression
 ```ruby
 cstr = "" # Compressed data
 stream = Zstd::StreamingDecompress.new
@@ -87,7 +109,16 @@ result << stream.decompress(cstr[0, 10])
 result << stream.decompress(cstr[10..-1])
 ```
 
-### Skippable flame
+#### Streaming Decompression with dictionary
+```ruby
+cstr = "" # Compressed data
+stream = Zstd::StreamingDecompress.new(dict: File.read('dictionary_file'))
+result = ''
+result << stream.decompress(cstr[0, 10])
+result << stream.decompress(cstr[10..-1])
+```
+
+### Skippable frame
 
 ```ruby
 compressed_data_with_skippable_frame = Zstd.write_skippable_frame(compressed_data, "sample data")
@@ -96,6 +127,45 @@ Zstd.read_skippable_frame(compressed_data_with_skippable_frame)
 # => "sample data"
 ```
 
+### Stream Writer and Reader Wrapper
+**EXPERIMENTAL**
+
+* These features are experimental and may be subject to API changes in future releases.
+* There may be performance and compatibility issues, so extensive testing is required before production use.
+* If you have any questions, encounter bugs, or have suggestions, please report them via [GitHub issues](https://github.com/SpringMT/zstd-ruby/issues).
+
+#### Zstd::StreamWriter
+
+```ruby
+require 'stringio'
+require 'zstd-ruby'
+
+io = StringIO.new
+stream = Zstd::StreamWriter.new(io)
+stream.write("abc")
+stream.finish
+
+io.rewind
+# Retrieve the compressed data
+compressed_data = io.read
+```
+
+#### Zstd::StreamReader
+
+```ruby
+require 'stringio'
+require 'zstd-ruby' # Add the appropriate require statement if necessary
+
+io = StringIO.new(compressed_data)
+reader = Zstd::StreamReader.new(io)
+
+# Read and output the decompressed data
+puts reader.read(10)  # 'abc'
+puts reader.read(10)  # 'def'
+puts reader.read(10)  # '' (end of data)
+```
+
+
 ## JRuby
 This gem does not support JRuby.
 

data/ext/zstdruby/common.h

@@ -1,7 +1,11 @@
 #ifndef ZSTD_RUBY_H
 #define ZSTD_RUBY_H 1
 
-#include "ruby.h"
+#include <ruby.h>
+#ifdef HAVE_RUBY_THREAD_H
+#include <ruby/thread.h>
+#endif
+#include <stdbool.h>
 #include "./libzstd/zstd.h"
 
 static int convert_compression_level(VALUE compression_level_value)
@@ -12,4 +16,171 @@ static int convert_compression_level(VALUE compression_level_value)
   return NUM2INT(compression_level_value);
 }
 
+static void set_compress_params(ZSTD_CCtx* const ctx, VALUE level_from_args, VALUE kwargs)
+{
+  ID kwargs_keys[2];
+  kwargs_keys[0] = rb_intern("level");
+  kwargs_keys[1] = rb_intern("dict");
+  VALUE kwargs_values[2];
+  rb_get_kwargs(kwargs, kwargs_keys, 0, 2, kwargs_values);
+
+  int compression_level = ZSTD_CLEVEL_DEFAULT;
+  if (kwargs_values[0] != Qundef && kwargs_values[0] != Qnil) {
+    compression_level = convert_compression_level(kwargs_values[0]);
+  } else if (!NIL_P(level_from_args)) {
+    rb_warn("`level` in args is deprecated; use keyword args `level:` instead.");
+    compression_level = convert_compression_level(level_from_args);
+  }
+  ZSTD_CCtx_setParameter(ctx, ZSTD_c_compressionLevel, compression_level);
+
+  if (kwargs_values[1] != Qundef && kwargs_values[1] != Qnil) {
+    char* dict_buffer = RSTRING_PTR(kwargs_values[1]);
+    size_t dict_size = RSTRING_LEN(kwargs_values[1]);
+    size_t load_dict_ret = ZSTD_CCtx_loadDictionary(ctx, dict_buffer, dict_size);
+    if (ZSTD_isError(load_dict_ret)) {
+      ZSTD_freeCCtx(ctx);
+      rb_raise(rb_eRuntimeError, "%s", "ZSTD_CCtx_loadDictionary failed");
+    }
+  }
+}
+
+struct stream_compress_params {
+  ZSTD_CCtx* ctx;
+  ZSTD_outBuffer* output;
+  ZSTD_inBuffer* input;
+  ZSTD_EndDirective endOp;
+  size_t ret;
+};
+
+static void* stream_compress_wrapper(void* args)
+{
+    struct stream_compress_params* params = args;
+    params->ret = ZSTD_compressStream2(params->ctx, params->output, params->input, params->endOp);
+    return NULL;
+}
+
+static size_t zstd_stream_compress(ZSTD_CCtx* const ctx, ZSTD_outBuffer* output, ZSTD_inBuffer* input, ZSTD_EndDirective endOp, bool gvl)
+{
+#ifdef HAVE_RUBY_THREAD_H
+    if (gvl) {
+      return ZSTD_compressStream2(ctx, output, input, endOp);
+    } else {
+      struct stream_compress_params params = { ctx, output, input, endOp };
+      rb_thread_call_without_gvl(stream_compress_wrapper, &params, NULL, NULL);
+      return params.ret;
+    }
+#else
+    return ZSTD_compressStream2(ctx, output, input, endOp);
+#endif
+}
+
+struct compress_params {
+  ZSTD_CCtx* ctx;
+  char* output_data;
+  size_t output_size;
+  char* input_data;
+  size_t input_size;
+  size_t ret;
+};
+
+static void* compress_wrapper(void* args)
+{
+    struct compress_params* params = args;
+    params->ret = ZSTD_compress2(params->ctx ,params->output_data, params->output_size, params->input_data, params->input_size);
+    return NULL;
+}
+
+static size_t zstd_compress(ZSTD_CCtx* const ctx, char* output_data, size_t output_size, char* input_data, size_t input_size, bool gvl)
+{
+#ifdef HAVE_RUBY_THREAD_H
+    if (gvl) {
+      return ZSTD_compress2(ctx , output_data, output_size, input_data, input_size);
+    } else {
+      struct compress_params params = { ctx, output_data, output_size, input_data, input_size };
+      rb_thread_call_without_gvl(compress_wrapper, &params, NULL, NULL);
+      return params.ret;
+    }
+#else
+    return ZSTD_compress2(ctx , output_data, output_size, input_data, input_size);
+#endif
+}
+
+static void set_decompress_params(ZSTD_DCtx* const dctx, VALUE kwargs)
+{
+  ID kwargs_keys[1];
+  kwargs_keys[0] = rb_intern("dict");
+  VALUE kwargs_values[1];
+  rb_get_kwargs(kwargs, kwargs_keys, 0, 1, kwargs_values);
+
+  if (kwargs_values[0] != Qundef && kwargs_values[0] != Qnil) {
+    char* dict_buffer = RSTRING_PTR(kwargs_values[0]);
+    size_t dict_size = RSTRING_LEN(kwargs_values[0]);
+    size_t load_dict_ret = ZSTD_DCtx_loadDictionary(dctx, dict_buffer, dict_size);
+    if (ZSTD_isError(load_dict_ret)) {
+      ZSTD_freeDCtx(dctx);
+      rb_raise(rb_eRuntimeError, "%s", "ZSTD_CCtx_loadDictionary failed");
+    }
+  }
+}
+
+struct stream_decompress_params {
+  ZSTD_DCtx* dctx;
+  ZSTD_outBuffer* output;
+  ZSTD_inBuffer* input;
+  size_t ret;
+};
+
+static void* stream_decompress_wrapper(void* args)
+{
+    struct stream_decompress_params* params = args;
+    params->ret = ZSTD_decompressStream(params->dctx, params->output, params->input);
+    return NULL;
+}
+
+static size_t zstd_stream_decompress(ZSTD_DCtx* const dctx, ZSTD_outBuffer* output, ZSTD_inBuffer* input, bool gvl)
+{
+#ifdef HAVE_RUBY_THREAD_H
+    if (gvl) {
+      return ZSTD_decompressStream(dctx, output, input);
+    } else {
+      struct stream_decompress_params params = { dctx, output, input };
+      rb_thread_call_without_gvl(stream_decompress_wrapper, &params, NULL, NULL);
+      return params.ret;
+    }
+#else
+    return ZSTD_decompressStream(dctx, output, input);
+#endif
+}
+
+struct decompress_params {
+  ZSTD_DCtx* dctx;
+  char* output_data;
+  size_t output_size;
+  char* input_data;
+  size_t input_size;
+  size_t ret;
+};
+
+static void* decompress_wrapper(void* args)
+{
+    struct decompress_params* params = args;
+    params->ret = ZSTD_decompressDCtx(params->dctx, params->output_data, params->output_size, params->input_data, params->input_size);
+    return NULL;
+}
+
+static size_t zstd_decompress(ZSTD_DCtx* const dctx, char* output_data, size_t output_size, char* input_data, size_t input_size, bool gvl)
+{
+#ifdef HAVE_RUBY_THREAD_H
+    if (gvl) {
+      return ZSTD_decompressDCtx(dctx, output_data, output_size, input_data, input_size);
+    } else {
+      struct decompress_params params = { dctx, output_data, output_size, input_data, input_size };
+      rb_thread_call_without_gvl(decompress_wrapper, &params, NULL, NULL);
+      return params.ret;
+    }
+#else
+    return ZSTD_decompressDCtx(dctx, output_data, output_size, input_data, input_size);
+#endif
+}
+
 #endif /* ZSTD_RUBY_H */

data/ext/zstdruby/extconf.rb

@@ -1,6 +1,8 @@
 require "mkmf"
 
-$CFLAGS = '-I. -O3 -std=c99 -DZSTD_STATIC_LINKING_ONLY'
+have_func('rb_gc_mark_movable')
+
+$CFLAGS = '-I. -O3 -std=c99 -DZSTD_STATIC_LINKING_ONLY -DZSTD_MULTITHREAD -pthread -DDEBUGLEVEL=0'
 $CPPFLAGS += " -fdeclspec" if CONFIG['CXX'] =~ /clang/
 
 Dir.chdir File.expand_path('..', __FILE__) do

data/ext/zstdruby/libzstd/common/allocations.h

@@ -14,7 +14,7 @@
 #define ZSTD_DEPS_NEED_MALLOC
 #include "zstd_deps.h"   /* ZSTD_malloc, ZSTD_calloc, ZSTD_free, ZSTD_memset */
 
-#include "mem.h" /* MEM_STATIC */
+#include "compiler.h" /* MEM_STATIC */
 #define ZSTD_STATIC_LINKING_ONLY
 #include "../zstd.h" /* ZSTD_customMem */
 

data/ext/zstdruby/libzstd/common/bitstream.h

@@ -90,19 +90,20 @@ MEM_STATIC size_t BIT_closeCStream(BIT_CStream_t* bitC);
 /*-********************************************
 *  bitStream decoding API (read backward)
 **********************************************/
+typedef size_t BitContainerType;
 typedef struct {
-    size_t   bitContainer;
+    BitContainerType bitContainer;
     unsigned bitsConsumed;
     const char* ptr;
     const char* start;
     const char* limitPtr;
 } BIT_DStream_t;
 
-typedef enum { BIT_DStream_unfinished = 0,
-               BIT_DStream_endOfBuffer = 1,
-               BIT_DStream_completed = 2,
-               BIT_DStream_overflow = 3 } BIT_DStream_status;  /* result of BIT_reloadDStream() */
-               /* 1,2,4,8 would be better for bitmap combinations, but slows down performance a bit ... :( */
+typedef enum { BIT_DStream_unfinished = 0,  /* fully refilled */
+               BIT_DStream_endOfBuffer = 1, /* still some bits left in bitstream */
+               BIT_DStream_completed = 2,   /* bitstream entirely consumed, bit-exact */
+               BIT_DStream_overflow = 3     /* user requested more bits than present in bitstream */
+    } BIT_DStream_status;  /* result of BIT_reloadDStream() */
 
 MEM_STATIC size_t   BIT_initDStream(BIT_DStream_t* bitD, const void* srcBuffer, size_t srcSize);
 MEM_STATIC size_t   BIT_readBits(BIT_DStream_t* bitD, unsigned nbBits);
@@ -112,7 +113,7 @@ MEM_STATIC unsigned BIT_endOfDStream(const BIT_DStream_t* bitD);
 
 /* Start by invoking BIT_initDStream().
 *  A chunk of the bitStream is then stored into a local register.
-*  Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (size_t).
+*  Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (BitContainerType).
 *  You can then retrieve bitFields stored into the local register, **in reverse order**.
 *  Local register is explicitly reloaded from memory by the BIT_reloadDStream() method.
 *  A reload guarantee a minimum of ((8*sizeof(bitD->bitContainer))-7) bits when its result is BIT_DStream_unfinished.
@@ -162,7 +163,7 @@ MEM_STATIC size_t BIT_initCStream(BIT_CStream_t* bitC,
     return 0;
 }
 
-MEM_STATIC FORCE_INLINE_ATTR size_t BIT_getLowerBits(size_t bitContainer, U32 const nbBits)
+FORCE_INLINE_TEMPLATE size_t BIT_getLowerBits(size_t bitContainer, U32 const nbBits)
 {
 #if defined(STATIC_BMI2) && STATIC_BMI2 == 1 && !defined(ZSTD_NO_INTRINSICS)
     return  _bzhi_u64(bitContainer, nbBits);
@@ -267,22 +268,22 @@ MEM_STATIC size_t BIT_initDStream(BIT_DStream_t* bitD, const void* srcBuffer, si
         bitD->bitContainer = *(const BYTE*)(bitD->start);
         switch(srcSize)
         {
-        case 7: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[6]) << (sizeof(bitD->bitContainer)*8 - 16);
+        case 7: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[6]) << (sizeof(bitD->bitContainer)*8 - 16);
                 ZSTD_FALLTHROUGH;
 
-        case 6: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[5]) << (sizeof(bitD->bitContainer)*8 - 24);
+        case 6: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[5]) << (sizeof(bitD->bitContainer)*8 - 24);
                 ZSTD_FALLTHROUGH;
 
-        case 5: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[4]) << (sizeof(bitD->bitContainer)*8 - 32);
+        case 5: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[4]) << (sizeof(bitD->bitContainer)*8 - 32);
                 ZSTD_FALLTHROUGH;
 
-        case 4: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[3]) << 24;
+        case 4: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[3]) << 24;
                 ZSTD_FALLTHROUGH;
 
-        case 3: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[2]) << 16;
+        case 3: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[2]) << 16;
                 ZSTD_FALLTHROUGH;
 
-        case 2: bitD->bitContainer += (size_t)(((const BYTE*)(srcBuffer))[1]) <<  8;
+        case 2: bitD->bitContainer += (BitContainerType)(((const BYTE*)(srcBuffer))[1]) <<  8;
                 ZSTD_FALLTHROUGH;
 
         default: break;
@@ -297,12 +298,12 @@ MEM_STATIC size_t BIT_initDStream(BIT_DStream_t* bitD, const void* srcBuffer, si
     return srcSize;
 }
 
-MEM_STATIC FORCE_INLINE_ATTR size_t BIT_getUpperBits(size_t bitContainer, U32 const start)
+FORCE_INLINE_TEMPLATE size_t BIT_getUpperBits(BitContainerType bitContainer, U32 const start)
 {
     return bitContainer >> start;
 }
 
-MEM_STATIC FORCE_INLINE_ATTR size_t BIT_getMiddleBits(size_t bitContainer, U32 const start, U32 const nbBits)
+FORCE_INLINE_TEMPLATE size_t BIT_getMiddleBits(BitContainerType bitContainer, U32 const start, U32 const nbBits)
 {
     U32 const regMask = sizeof(bitContainer)*8 - 1;
     /* if start > regMask, bitstream is corrupted, and result is undefined */
@@ -325,7 +326,7 @@ MEM_STATIC FORCE_INLINE_ATTR size_t BIT_getMiddleBits(size_t bitContainer, U32 c
  *  On 32-bits, maxNbBits==24.
  *  On 64-bits, maxNbBits==56.
  * @return : value extracted */
-MEM_STATIC  FORCE_INLINE_ATTR size_t BIT_lookBits(const BIT_DStream_t*  bitD, U32 nbBits)
+FORCE_INLINE_TEMPLATE size_t BIT_lookBits(const BIT_DStream_t*  bitD, U32 nbBits)
 {
     /* arbitrate between double-shift and shift+mask */
 #if 1
@@ -348,7 +349,7 @@ MEM_STATIC size_t BIT_lookBitsFast(const BIT_DStream_t* bitD, U32 nbBits)
     return (bitD->bitContainer << (bitD->bitsConsumed & regMask)) >> (((regMask+1)-nbBits) & regMask);
 }
 
-MEM_STATIC FORCE_INLINE_ATTR void BIT_skipBits(BIT_DStream_t* bitD, U32 nbBits)
+FORCE_INLINE_TEMPLATE void BIT_skipBits(BIT_DStream_t* bitD, U32 nbBits)
 {
     bitD->bitsConsumed += nbBits;
 }
@@ -357,7 +358,7 @@ MEM_STATIC FORCE_INLINE_ATTR void BIT_skipBits(BIT_DStream_t* bitD, U32 nbBits)
  *  Read (consume) next n bits from local register and update.
  *  Pay attention to not read more than nbBits contained into local register.
  * @return : extracted value. */
-MEM_STATIC FORCE_INLINE_ATTR size_t BIT_readBits(BIT_DStream_t* bitD, unsigned nbBits)
+FORCE_INLINE_TEMPLATE size_t BIT_readBits(BIT_DStream_t* bitD, unsigned nbBits)
 {
     size_t const value = BIT_lookBits(bitD, nbBits);
     BIT_skipBits(bitD, nbBits);
@@ -374,6 +375,21 @@ MEM_STATIC size_t BIT_readBitsFast(BIT_DStream_t* bitD, unsigned nbBits)
     return value;
 }
 
+/*! BIT_reloadDStream_internal() :
+ *  Simple variant of BIT_reloadDStream(), with two conditions:
+ *  1. bitstream is valid : bitsConsumed <= sizeof(bitD->bitContainer)*8
+ *  2. look window is valid after shifted down : bitD->ptr >= bitD->start
+ */
+MEM_STATIC BIT_DStream_status BIT_reloadDStream_internal(BIT_DStream_t* bitD)
+{
+    assert(bitD->bitsConsumed <= sizeof(bitD->bitContainer)*8);
+    bitD->ptr -= bitD->bitsConsumed >> 3;
+    assert(bitD->ptr >= bitD->start);
+    bitD->bitsConsumed &= 7;
+    bitD->bitContainer = MEM_readLEST(bitD->ptr);
+    return BIT_DStream_unfinished;
+}
+
 /*! BIT_reloadDStreamFast() :
  *  Similar to BIT_reloadDStream(), but with two differences:
  *  1. bitsConsumed <= sizeof(bitD->bitContainer)*8 must hold!
@@ -384,31 +400,35 @@ MEM_STATIC BIT_DStream_status BIT_reloadDStreamFast(BIT_DStream_t* bitD)
 {
     if (UNLIKELY(bitD->ptr < bitD->limitPtr))
         return BIT_DStream_overflow;
-    assert(bitD->bitsConsumed <= sizeof(bitD->bitContainer)*8);
-    bitD->ptr -= bitD->bitsConsumed >> 3;
-    bitD->bitsConsumed &= 7;
-    bitD->bitContainer = MEM_readLEST(bitD->ptr);
-    return BIT_DStream_unfinished;
+    return BIT_reloadDStream_internal(bitD);
 }
 
 /*! BIT_reloadDStream() :
  *  Refill `bitD` from buffer previously set in BIT_initDStream() .
- *  This function is safe, it guarantees it will not read beyond src buffer.
+ *  This function is safe, it guarantees it will not never beyond src buffer.
  * @return : status of `BIT_DStream_t` internal register.
  *           when status == BIT_DStream_unfinished, internal register is filled with at least 25 or 57 bits */
-MEM_STATIC FORCE_INLINE_ATTR BIT_DStream_status BIT_reloadDStream(BIT_DStream_t* bitD)
+FORCE_INLINE_TEMPLATE BIT_DStream_status BIT_reloadDStream(BIT_DStream_t* bitD)
 {
-    if (bitD->bitsConsumed > (sizeof(bitD->bitContainer)*8))  /* overflow detected, like end of stream */
+    /* note : once in overflow mode, a bitstream remains in this mode until it's reset */
+    if (UNLIKELY(bitD->bitsConsumed > (sizeof(bitD->bitContainer)*8))) {
+        static const BitContainerType zeroFilled = 0;
+        bitD->ptr = (const char*)&zeroFilled; /* aliasing is allowed for char */
+        /* overflow detected, erroneous scenario or end of stream: no update */
         return BIT_DStream_overflow;
+    }
+
+    assert(bitD->ptr >= bitD->start);
 
     if (bitD->ptr >= bitD->limitPtr) {
-        return BIT_reloadDStreamFast(bitD);
+        return BIT_reloadDStream_internal(bitD);
     }
     if (bitD->ptr == bitD->start) {
+        /* reached end of bitStream => no update */
         if (bitD->bitsConsumed < sizeof(bitD->bitContainer)*8) return BIT_DStream_endOfBuffer;
         return BIT_DStream_completed;
     }
-    /* start < ptr < limitPtr */
+    /* start < ptr < limitPtr => cautious update */
     {   U32 nbBytes = bitD->bitsConsumed >> 3;
         BIT_DStream_status result = BIT_DStream_unfinished;
         if (bitD->ptr - nbBytes < bitD->start) {