diff options
-rw-r--r-- | lz4.c | 6 | ||||
-rw-r--r-- | lz4.h | 18 | ||||
-rw-r--r-- | lz4hc.c | 6 | ||||
-rw-r--r-- | lz4hc.h | 45 |
4 files changed, 38 insertions, 37 deletions
@@ -683,7 +683,7 @@ int LZ4_compress_limitedOutput(const char* source, char* dest, int inputSize, in /***************************************** - Experimental : Streaming functions + Experimental Continuous Block Mode *****************************************/ /* @@ -1177,7 +1177,7 @@ int LZ4_uncompress (const char* source, char* dest, int outputSize) { return LZ4 int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize) { return LZ4_decompress_safe(source, dest, isize, maxOutputSize); } -/* Obsolete Streaming functions */ +/* Obsolete CBM functions */ int LZ4_sizeofStreamState() { return LZ4_STREAMSIZE; } @@ -1236,7 +1236,7 @@ int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* return LZ4_compress_generic(state, source, dest, inputSize, maxOutputSize, limitedOutput, LZ4_64BITS ? byU32 : byPtr, noDict, noDictIssue); } -/* Obsolete streaming decompression functions */ +/* Obsolete CBM decompression functions */ int LZ4_decompress_safe_withPrefix64k(const char* source, char* dest, int compressedSize, int maxOutputSize) { @@ -170,7 +170,11 @@ int LZ4_decompress_safe_partial (const char* source, char* dest, int compressedS /*********************************************** - Experimental Streaming Compression Functions + Experimental Continuous Block Mode + + These functions allow the compression of continuous blocks, + where each block benefits from prior 64 KB within preceding blocks to achieve better compression ratio. + A flow of multiple continuous blocks is called a "stream". ***********************************************/ #define LZ4_STREAMSIZE_U32 ((1 << (LZ4_MEMORY_USAGE-2)) + 8) @@ -233,7 +237,7 @@ int LZ4_saveDict (LZ4_stream_t* LZ4_stream, char* safeBuffer, int dictSize); /************************************************ - Experimental Streaming Decompression Functions + Experimental CBM Decompression Functions ************************************************/ #define LZ4_STREAMDECODESIZE_U32 4 @@ -301,16 +305,8 @@ It is highly recommended to stop using these functions and migrated to newer one /* int LZ4_uncompress (const char* source, char* dest, int outputSize); */ /* int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); */ -/* - * If you prefer dynamic allocation methods, - * LZ4_createStreamDecode() - * provides a pointer (void*) towards an initialized LZ4_streamDecode_t structure. - * LZ4_free just frees it. - */ -/* void* LZ4_createStreamDecode(void); */ -/*int LZ4_free (void* LZ4_stream); yes, it's the same one as for compression */ -/* Obsolete streaming functions; use new streaming interface whenever possible */ +/* Obsolete CBM functions; use new CBM interface whenever possible */ void* LZ4_create (const char* inputBuffer); int LZ4_sizeofStreamState(void); int LZ4_resetStreamState(void* state, const char* inputBuffer); @@ -870,9 +870,9 @@ int LZ4_compressHC_limitedOutput_withStateHC (void* state, const char* source, c { return LZ4_compressHC2_limitedOutput_withStateHC (state, source, dest, inputSize, maxOutputSize, 0); } -/**************************** - Stream functions -****************************/ +/************************************** + Experimental Continuous Block Mode +**************************************/ int LZ4_compressHC_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize) { @@ -101,10 +101,13 @@ They just use the externally allocated memory area instead of allocating their o */ -/************************************** - Streaming Functions -**************************************/ -/* Note : these streaming functions still follows the older model */ +/*********************************************** + Experimental Continuous Block Mode + + These functions allow the compression of continuous blocks, + where each block benefits from prior 64 KB within preceding blocks to achieve better compression ratio. +***********************************************/ +/* Note : these CBM functions follow the older, more rigid, model */ 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); @@ -115,28 +118,33 @@ int LZ4_compressHC2_continue (void* LZ4HC_Data, const char* source, char* dest 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 : +Here is how it works : +First, start by 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 parameter 'const char* inputBuffer' must provide 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. +You will have to start your compression at this address. 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. +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 : +When it's no longer possible to lay the next block after the previous one (no more space left into input buffer), +you can free some space by calling : + 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. + +It will typically copy the latest 64KB of input at the beginning of input buffer. +Note that, for this function to work properly, the minimum size of input buffer must be 192KB. +==> The function result provides the memory position where the next input data block must be copied. Compression can then resume, using LZ4_compressHC_continue() or LZ4_compressHC_limitedOutput_continue(), as usual. @@ -148,6 +156,7 @@ 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. @@ -155,15 +164,11 @@ They are provided here to allow the user program to allocate memory using its ow 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. +Once space is allocated, you can reference it using a 'void*' pointer, which will be become the LZ4 HC Data Structure. +You can then follow previous instructions, using this pointer instead. 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. +return value of LZ4_resetStreamStateHC() must be 0 if OK. Any other value means there was an error (typically, state is not aligned for pointers (32 or 64 bits)). */ |