added code documentation on heap mode
and also on decompress_continue variants.
GitOrigin-RevId: 586e9a4c6db004fe6dc298b508aa364e22996bdb
Change-Id: I87225680e05363cf356156850cc99c47f9ee5abf
diff --git a/lib/README.md b/lib/README.md
index c1e7b1e..a86cd0d 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -115,6 +115,15 @@
(embedded, bootloader, etc).
For more details, see description of this macro in `lib/lz4.h`.
+- `LZ4_HEAPMODE` : Select how stateless compression functions like `LZ4_compress_default()`
+ allocate memory for their hash table,
+ in memory stack (0:default, fastest), or in memory heap (1:requires malloc()).
+
+- `LZ4HC_HEAPMODE` : Select how stateless HC compression functions like `LZ4_compress_HC()`
+ allocate memory for their workspace:
+ in stack (0), or in heap (1:default).
+ Since workspace is rather large, stack can be inconvenient, hence heap mode is recommended.
+
- `LZ4F_HEAPMODE` : selects how `LZ4F_compressFrame()` allocates the compression state,
either on stack (default, value 0) or using heap memory (value 1).
diff --git a/lib/lz4.c b/lib/lz4.c
index 104227c..4f05257 100644
--- a/lib/lz4.c
+++ b/lib/lz4.c
@@ -37,7 +37,8 @@
**************************************/
/*
* LZ4_HEAPMODE :
- * Select how default compression functions will allocate memory for their hash table,
+ * Select how stateless compression functions like `LZ4_compress_default()`
+ * allocate memory for their hash table,
* in memory stack (0:default, fastest), or in memory heap (1:requires malloc()).
*/
#ifndef LZ4_HEAPMODE
diff --git a/lib/lz4.h b/lib/lz4.h
index 491c608..f7b255d 100644
--- a/lib/lz4.h
+++ b/lib/lz4.h
@@ -189,8 +189,9 @@
LZ4LIB_API int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity);
/*! LZ4_decompress_safe() :
- * compressedSize : is the exact complete size of the compressed block.
- * dstCapacity : is the size of destination buffer (which must be already allocated), presumed an upper bound of decompressed size.
+ * @compressedSize : is the exact complete size of the compressed block.
+ * @dstCapacity : is the size of destination buffer (which must be already allocated),
+ * is an upper bound of decompressed size.
* @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity)
* If destination buffer is not large enough, decoding will stop and output an error code (negative value).
* If the source stream is detected malformed, the function will stop decoding and return a negative result.
@@ -443,11 +444,24 @@
LZ4LIB_API int LZ4_decoderRingBufferSize(int maxBlockSize);
#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize)) /* for static allocation; maxBlockSize presumed valid */
-/*! LZ4_decompress_*_continue() :
- * These decoding functions allow decompression of consecutive blocks in "streaming" mode.
- * A block is an unsplittable entity, it must be presented entirely to a decompression function.
- * Decompression functions only accepts one block at a time.
- * The last 64KB of previously decoded data *must* remain available and unmodified at the memory position where they were decoded.
+/*! LZ4_decompress_safe_continue() :
+ * This decoding function allows decompression of consecutive blocks in "streaming" mode.
+ * The difference with the usual independent blocks is that
+ * new blocks are allowed to find references into former blocks.
+ * A block is an unsplittable entity, and must be presented entirely to the decompression function.
+ * LZ4_decompress_safe_continue() only accepts one block at a time.
+ * It's modeled after `LZ4_decompress_safe()` and behaves similarly.
+ *
+ * @LZ4_streamDecode : decompression state, tracking the position in memory of past data
+ * @compressedSize : exact complete size of one compressed block.
+ * @dstCapacity : size of destination buffer (which must be already allocated),
+ * must be an upper bound of decompressed size.
+ * @return : number of bytes decompressed into destination buffer (necessarily <= dstCapacity)
+ * If destination buffer is not large enough, decoding will stop and output an error code (negative value).
+ * If the source stream is detected malformed, the function will stop decoding and return a negative result.
+ *
+ * The last 64KB of previously decoded data *must* remain available and unmodified
+ * at the memory position where they were previously decoded.
* If less than 64KB of data has been decoded, all the data must be present.
*
* Special : if decompression side sets a ring buffer, it must respect one of the following conditions :
@@ -474,10 +488,10 @@
int srcSize, int dstCapacity);
-/*! LZ4_decompress_*_usingDict() :
- * These decoding functions work the same as
- * a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue()
- * They are stand-alone, and don't need an LZ4_streamDecode_t structure.
+/*! LZ4_decompress_safe_usingDict() :
+ * Works the same as
+ * a combination of LZ4_setStreamDecode() followed by LZ4_decompress_safe_continue()
+ * However, it's stateless: it doesn't need any LZ4_streamDecode_t state.
* Dictionary is presumed stable : it must remain accessible and unmodified during decompression.
* Performance tip : Decompression speed can be substantially increased
* when dst == dictStart + dictSize.
@@ -487,6 +501,12 @@
int srcSize, int dstCapacity,
const char* dictStart, int dictSize);
+/*! LZ4_decompress_safe_partial_usingDict() :
+ * Behaves the same as LZ4_decompress_safe_partial()
+ * with the added ability to specify a memory segment for past data.
+ * Performance tip : Decompression speed can be substantially increased
+ * when dst == dictStart + dictSize.
+ */
LZ4LIB_API int
LZ4_decompress_safe_partial_usingDict(const char* src, char* dst,
int compressedSize,
diff --git a/lib/lz4hc.c b/lib/lz4hc.c
index 446f55d..88fbdc7 100644
--- a/lib/lz4hc.c
+++ b/lib/lz4hc.c
@@ -39,9 +39,10 @@
***************************************/
/*! HEAPMODE :
- * Select how default compression function will allocate workplace memory,
- * in stack (0:fastest), or in heap (1:requires malloc()).
- * Since workplace is rather large, heap mode is recommended.
+ * Select how stateless HC compression functions like `LZ4_compress_HC()`
+ * allocate memory for their workspace:
+ * in stack (0:fastest), or in heap (1:default, requires malloc()).
+ * Since workspace is rather large, heap mode is recommended.
**/
#ifndef LZ4HC_HEAPMODE
# define LZ4HC_HEAPMODE 1
