From b827ecf72894156c1727482b145dc9e7a116dbc9 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Wed, 3 Dec 2014 23:19:11 +0100 Subject: Clarified a few comments --- Makefile | 7 +++--- NEWS | 1 + lib/lz4.c | 8 +++---- lib/lz4.h | 9 ++++++-- lib/lz4hc.c | 4 ++-- lib/lz4hc.h | 71 ++++++++++--------------------------------------------------- 6 files changed, 28 insertions(+), 72 deletions(-) diff --git a/Makefile b/Makefile index 66c8c4b..f5bf4b5 100644 --- a/Makefile +++ b/Makefile @@ -72,12 +72,13 @@ endif default: lz4programs - @cd $(PRGDIR); $(MAKE) -e -all: lz4programs +all: + @cd $(LZ4DIR); $(MAKE) -e all + @cd $(PRGDIR); $(MAKE) -e all lz4programs: - @cd $(PRGDIR); $(MAKE) -e all + @cd $(PRGDIR); $(MAKE) -e clean: @rm -f $(DISTRIBNAME) *.sha1 diff --git a/NEWS b/NEWS index f49535d..45e1871 100644 --- a/NEWS +++ b/NEWS @@ -3,6 +3,7 @@ Changed : endian and alignment code Changed : directory structure : new "lib" directory Updated : lz4io, now uses lz4frame Fixed : some alignment warnings under clang +Fixed : deprecated function LZ4_slideInputBufferHC() r124: New : LZ4 HC streaming mode diff --git a/lib/lz4.c b/lib/lz4.c index f8186b4..f70ac46 100644 --- a/lib/lz4.c +++ b/lib/lz4.c @@ -1316,11 +1316,9 @@ void* LZ4_create (const char* inputBuffer) char* LZ4_slideInputBuffer (void* LZ4_Data) { - LZ4_stream_t_internal* lz4ds = (LZ4_stream_t_internal*)LZ4_Data; - - LZ4_saveDict((LZ4_stream_t*)LZ4_Data, (char*)lz4ds->bufferStart, 64 KB); - - return (char*)(lz4ds->bufferStart + 64 KB); + LZ4_stream_t_internal* ctx = (LZ4_stream_t_internal*)LZ4_Data; + int dictSize = LZ4_saveDict((LZ4_stream_t*)ctx, (char*)ctx->bufferStart, 64 KB); + return (char*)(ctx->bufferStart + dictSize); } /* Obsolete compresson functions using User-allocated state */ diff --git a/lib/lz4.h b/lib/lz4.h index 22bbcb5..7392320 100644 --- a/lib/lz4.h +++ b/lib/lz4.h @@ -178,6 +178,8 @@ int LZ4_decompress_safe_partial (const char* source, char* dest, int compressedS * LZ4_stream_t * information structure to track an LZ4 stream. * important : init this structure content before first use ! + * note : only allocated directly the structure if you are statically linking LZ4 + * If you are using liblz4 as a DLL, please use below construction methods instead. */ typedef struct { long long table[LZ4_STREAMSIZE_U64]; } LZ4_stream_t; @@ -188,9 +190,10 @@ typedef struct { long long table[LZ4_STREAMSIZE_U64]; } LZ4_stream_t; void LZ4_resetStream (LZ4_stream_t* LZ4_streamPtr); /* - * If you prefer dynamic allocation methods, * LZ4_createStream will allocate and initialize an LZ4_stream_t structure * LZ4_freeStream releases its memory. + * In the context of a DLL (liblz4), please use these methods rather than the static struct. + * They are more future proof, in case of a change of LZ4_stream_t size. */ LZ4_stream_t* LZ4_createStream(void); int LZ4_freeStream (LZ4_stream_t* LZ4_streamPtr); @@ -241,7 +244,9 @@ typedef struct { unsigned long long table[LZ4_STREAMDECODESIZE_U64]; } LZ4_strea * LZ4_streamDecode_t * information structure to track an LZ4 stream. * init this structure content using LZ4_setStreamDecode or memset() before first use ! - * If you prefer dynamic allocation methods : + * + * In the context of a DLL (liblz4) please prefer usage of construction methods below. + * They are more future proof, in case of a change of LZ4_streamDecode_t size in the future. * LZ4_createStreamDecode will allocate and initialize an LZ4_streamDecode_t structure * LZ4_freeStreamDecode releases its memory. */ diff --git a/lib/lz4hc.c b/lib/lz4hc.c index c3e0b6d..6690e81 100644 --- a/lib/lz4hc.c +++ b/lib/lz4hc.c @@ -556,8 +556,8 @@ int LZ4_compressHC_limitedOutput(const char* source, char* dest, int inputSize, /***************************** - Using external allocation -*****************************/ + * Using external allocation + * ***************************/ int LZ4_sizeofStateHC(void) { return sizeof(LZ4HC_Data_Structure); } diff --git a/lib/lz4hc.h b/lib/lz4hc.h index 26ba6d3..ce813ab 100644 --- a/lib/lz4hc.h +++ b/lib/lz4hc.h @@ -108,21 +108,24 @@ They just use the externally allocated memory for state instead of allocating th #define LZ4_STREAMHCSIZE_U64 32774 #define LZ4_STREAMHCSIZE (LZ4_STREAMHCSIZE_U64 * sizeof(unsigned long long)) typedef struct { unsigned long long table[LZ4_STREAMHCSIZE_U64]; } LZ4_streamHC_t; - /* +LZ4_streamHC_t This structure allows static allocation of LZ4 HC streaming state. State must then be initialized using LZ4_resetStreamHC() before first use. -If you prefer dynamic allocation, please refer to functions below. +Static allocation should only be used with statically linked library. +If you want to use LZ4 as a DLL, please use construction functions below, which are more future-proof. */ + LZ4_streamHC_t* LZ4_createStreamHC(void); int LZ4_freeStreamHC (LZ4_streamHC_t* LZ4_streamHCPtr); - /* These functions create and release memory for LZ4 HC streaming state. Newly created states are already initialized. Existing state space can be re-used anytime using LZ4_resetStreamHC(). +If you use LZ4 as a DLL, please use these functions instead of direct struct allocation, +to avoid size mismatch between different versions. */ void LZ4_resetStreamHC (LZ4_streamHC_t* LZ4_streamHCPtr, int compressionLevel); @@ -152,70 +155,18 @@ using LZ4_saveDictHC(). /************************************** - Deprecated Streaming Functions -**************************************/ -/* Note : these streaming functions still follows the older model */ + * Deprecated Streaming Functions + * ************************************/ +/* Note : these streaming functions follows the older model, and should no longer be used */ void* LZ4_createHC (const char* inputBuffer); -//int LZ4_compressHC_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize); -//int LZ4_compressHC_limitedOutput_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int maxOutputSize); char* LZ4_slideInputBufferHC (void* LZ4HC_Data); int LZ4_freeHC (void* LZ4HC_Data); int LZ4_compressHC2_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int compressionLevel); int LZ4_compressHC2_limitedOutput_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); -/* -These functions allow the compression of dependent blocks, where each block benefits from prior 64 KB within preceding blocks. -In order to achieve this, it is necessary to start creating the LZ4HC Data Structure, thanks to the function : - -void* LZ4_createHC (const char* inputBuffer); -The result of the function is the (void*) pointer on the LZ4HC Data Structure. -This pointer will be needed in all other functions. -If the pointer returned is NULL, then the allocation has failed, and compression must be aborted. -The only parameter 'const char* inputBuffer' must, obviously, point at the beginning of input buffer. -The input buffer must be already allocated, and size at least 192KB. -'inputBuffer' will also be the 'const char* source' of the first block. - -All blocks are expected to lay next to each other within the input buffer, starting from 'inputBuffer'. -To compress each block, use either LZ4_compressHC_continue() or LZ4_compressHC_limitedOutput_continue(). -Their behavior are identical to LZ4_compressHC() or LZ4_compressHC_limitedOutput(), -but require the LZ4HC Data Structure as their first argument, and check that each block starts right after the previous one. -If next block does not begin immediately after the previous one, the compression will fail (return 0). - -When it's no longer possible to lay the next block after the previous one (not enough space left into input buffer), a call to : -char* LZ4_slideInputBufferHC(void* LZ4HC_Data); -must be performed. It will typically copy the latest 64KB of input at the beginning of input buffer. -Note that, for this function to work properly, minimum size of an input buffer must be 192KB. -==> The memory position where the next input data block must start is provided as the result of the function. - -Compression can then resume, using LZ4_compressHC_continue() or LZ4_compressHC_limitedOutput_continue(), as usual. - -When compression is completed, a call to LZ4_freeHC() will release the memory used by the LZ4HC Data Structure. -*/ - -int LZ4_sizeofStreamStateHC(void); -int LZ4_resetStreamStateHC(void* state, const char* inputBuffer); - -/* -These functions achieve the same result as : -void* LZ4_createHC (const char* inputBuffer); - -They are provided here to allow the user program to allocate memory using its own routines. - -To know how much space must be allocated, use LZ4_sizeofStreamStateHC(); -Note also that space must be aligned for pointers (32 or 64 bits). - -Once space is allocated, you must initialize it using : LZ4_resetStreamStateHC(void* state, const char* inputBuffer); -void* state is a pointer to the space allocated. -It must be aligned for pointers (32 or 64 bits), and be large enough. -The parameter 'const char* inputBuffer' must, obviously, point at the beginning of input buffer. -The input buffer must be already allocated, and size at least 192KB. -'inputBuffer' will also be the 'const char* source' of the first block. - -The same space can be re-used multiple times, just by initializing it each time with LZ4_resetStreamState(). -return value of LZ4_resetStreamStateHC() must be 0 is OK. -Any other value means there was an error (typically, state is not aligned for pointers (32 or 64 bits)). -*/ +int LZ4_sizeofStreamStateHC(void); +int LZ4_resetStreamStateHC(void* state, const char* inputBuffer); #if defined (__cplusplus) -- cgit v0.12