From b21490232df113efc5fee7251edfc0511a346143 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 20 Sep 2022 12:49:51 -0700 Subject: added notes about LZ4_compressFrame() and stack/heap memory usage --- lib/lz4frame.c | 2 +- lib/lz4frame.h | 16 +++++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/lib/lz4frame.c b/lib/lz4frame.c index 4d991e1..d1cc5f0 100644 --- a/lib/lz4frame.c +++ b/lib/lz4frame.c @@ -54,7 +54,7 @@ **************************************/ /* * LZ4F_HEAPMODE : - * Select how LZ4F_compressFrame will allocate the Compression Context, + * Control how LZ4F_compressFrame allocates the Compression State, * either on stack (0:default, fastest), or in memory heap (1:requires malloc()). */ #ifndef LZ4F_HEAPMODE diff --git a/lib/lz4frame.h b/lib/lz4frame.h index 8d9380b..007cad7 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -215,9 +215,19 @@ LZ4FLIB_API int LZ4F_compressionLevel_max(void); /* v1.8.0+ */ LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); /*! LZ4F_compressFrame() : - * Compress an entire srcBuffer into a valid LZ4 frame. - * dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). - * The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default. + * Compress srcBuffer content into an LZ4-compressed frame. + * It's a one shot operation, all input content is consumed, and all output is generated. + * + * Note : it's a stateless operation (no LZ4F_cctx state needed). + * In order to reduce load on the allocator, LZ4F_compressFrame(), by default, + * uses the stack to allocate space for the compression state and some table. + * If this usage of the stack is too much for your application, + * consider compiling `lz4frame.c` with compile-time macro LZ4F_HEAPMODE set to 1 instead. + * All state allocations will use the Heap. + * It also means each invocation of LZ4F_compressFrame() will trigger several internal alloc/free invocations. + * + * @dstCapacity MUST be >= LZ4F_compressFrameBound(srcSize, preferencesPtr). + * @preferencesPtr is optional : one can provide NULL, in which case all preferences are set to default. * @return : number of bytes written into dstBuffer. * or an error code if it fails (can be tested using LZ4F_isError()) */ -- cgit v0.12