summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorYann Collet <cyan@fb.com>2019-05-31 18:56:59 (GMT)
committerYann Collet <cyan@fb.com>2019-05-31 18:56:59 (GMT)
commit5997e139f53169fa3a1c1b4418d2452a90b01602 (patch)
treedbd25376f49f487f91319c11d06ee8eaaeed577c
parent33cb8518ac385835cc17be9a770b27b40cd0e15b (diff)
downloadlz4-5997e139f53169fa3a1c1b4418d2452a90b01602.zip
lz4-5997e139f53169fa3a1c1b4418d2452a90b01602.tar.gz
lz4-5997e139f53169fa3a1c1b4418d2452a90b01602.tar.bz2
added more details for in-place documentation
-rw-r--r--doc/lz4_manual.html25
-rw-r--r--lib/lz4.h29
2 files changed, 28 insertions, 26 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index 083211d..1480089 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -364,23 +364,23 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
and decompression to start at beginning of the buffer.
Buffer size must feature some margin, hence be larger than final size.
- |<------------------------buffer----------------------------------->|
- |<------------compressed data---------->|
+ |<------------------------buffer--------------------------------->|
+ |<-----------compressed data--------->|
|<-----------decompressed size------------------>|
- |<-----margin----->|
+ |<----margin---->|
This technique is more useful for decompression,
since decompressed size is typically larger,
- and margin is mostly required to avoid stripe overflow, so it's short.
+ and margin is short.
In-place decompression will work inside any buffer
which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize).
This presumes that decompressedSize > compressedSize.
Otherwise, it means compression actually expanded data,
- which can happen when data is not compressible (already compressed, or encrypted),
and it would be more efficient to store such data with a flag indicating it's not compressed.
+ This can happen when data is not compressible (already compressed, or encrypted).
- For compression, margin is larger, as it must be able to cope with both
+ For in-place compression, margin is larger, as it must be able to cope with both
history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX,
and data expansion, which can happen when input is not compressible.
As a consequence, buffer size requirements are much higher,
@@ -388,10 +388,11 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
There are ways to limit this cost for compression :
- Reduce history size, by modifying LZ4_DISTANCE_MAX.
- Note that it is a compile-time constant, so all future compression will apply this parameter.
+ Note that it is a compile-time constant, so all compressions will apply this limit.
Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX,
so it's a reasonable trick when inputs are known to be small.
- Require the compressor to deliver a "maximum compressed size".
+ This is the `dstCapacity` parameter in `LZ4_compress*()`.
When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail,
in which case, the return code will be 0 (zero).
The caller must be ready for these cases to happen,
@@ -400,16 +401,16 @@ int LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
the amount of margin required for in-place compression.
In-place compression can work in any buffer
- which size is >= LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize)
+ which size is >= (maxCompressedSize)
with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success.
- This macro depends on both maxCompressedSize and LZ4_DISTANCE_MAX,
- so there are ways to reduce memory requirements by playing with them.
+ LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX,
+ so it's possible to reduce memory requirements by playing with them.
</p></pre><BR>
-<pre><b>#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ( (decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) </b>/**< note: presumes that compressedSize < decompressedSize */<b>
+<pre><b>#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) </b>/**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */<b>
</b></pre><BR>
-<pre><b>#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ( (maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) </b>/**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */<b>
+<pre><b>#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) </b>/**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */<b>
</b></pre><BR>
<a name="Chapter9"></a><h2>PRIVATE DEFINITIONS</h2><pre>
Do not use these definitions directly.
diff --git a/lib/lz4.h b/lib/lz4.h
index 383c2db..0dfa637 100644
--- a/lib/lz4.h
+++ b/lib/lz4.h
@@ -476,23 +476,23 @@ LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const
* and decompression to start at beginning of the buffer.
* Buffer size must feature some margin, hence be larger than final size.
*
- * |<------------------------buffer----------------------------------->|
- * |<------------compressed data---------->|
+ * |<------------------------buffer--------------------------------->|
+ * |<-----------compressed data--------->|
* |<-----------decompressed size------------------>|
- * |<-----margin----->|
+ * |<----margin---->|
*
* This technique is more useful for decompression,
* since decompressed size is typically larger,
- * and margin is mostly required to avoid stripe overflow, so it's short.
+ * and margin is short.
*
* In-place decompression will work inside any buffer
* which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize).
* This presumes that decompressedSize > compressedSize.
* Otherwise, it means compression actually expanded data,
- * which can happen when data is not compressible (already compressed, or encrypted),
* and it would be more efficient to store such data with a flag indicating it's not compressed.
+ * This can happen when data is not compressible (already compressed, or encrypted).
*
- * For compression, margin is larger, as it must be able to cope with both
+ * For in-place compression, margin is larger, as it must be able to cope with both
* history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX,
* and data expansion, which can happen when input is not compressible.
* As a consequence, buffer size requirements are much higher,
@@ -500,10 +500,11 @@ LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const
*
* There are ways to limit this cost for compression :
* - Reduce history size, by modifying LZ4_DISTANCE_MAX.
- * Note that it is a compile-time constant, so all future compression will apply this parameter.
+ * Note that it is a compile-time constant, so all compressions will apply this limit.
* Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX,
* so it's a reasonable trick when inputs are known to be small.
* - Require the compressor to deliver a "maximum compressed size".
+ * This is the `dstCapacity` parameter in `LZ4_compress*()`.
* When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail,
* in which case, the return code will be 0 (zero).
* The caller must be ready for these cases to happen,
@@ -512,21 +513,21 @@ LZ4LIB_STATIC_API void LZ4_attach_dictionary(LZ4_stream_t* workingStream, const
* the amount of margin required for in-place compression.
*
* In-place compression can work in any buffer
- * which size is >= LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize)
+ * which size is >= (maxCompressedSize)
* with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success.
- * This macro depends on both maxCompressedSize and LZ4_DISTANCE_MAX,
- * so there are ways to reduce memory requirements by playing with them.
+ * LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX,
+ * so it's possible to reduce memory requirements by playing with them.
*/
-#define LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize) (((decompressedSize) >> 8) + 32)
-#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ( (decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) /**< note: presumes that compressedSize < decompressedSize */
+#define LZ4_DECOMPRESS_INPLACE_MARGIN(compressedSize) (((compressedSize) >> 8) + 32)
+#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize) ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize)) /**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */
#ifndef LZ4_DISTANCE_MAX /* history window size; can be user-defined at compile time */
# define LZ4_DISTANCE_MAX 65535 /* set to maximum value by default */
#endif
-#define LZ4_COMPRESS_INPLACE_MARGIN (LZ4_DISTANCE_MAX + 32)
-#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ( (maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) /**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */
+#define LZ4_COMPRESS_INPLACE_MARGIN (LZ4_DISTANCE_MAX + 32) /* LZ4_DISTANCE_MAX can be safely replaced by srcSize when it's smaller */
+#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize) ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN) /**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */
#endif /* LZ4_STATIC_3504398509 */
#endif /* LZ4_STATIC_LINKING_ONLY */