Class LZ4HC
Streaming Compression - Bufferless synchronous API
These functions compress data in successive blocks of any size, using previous blocks as dictionary, to improve compression ratio. One key assumption
is that previous blocks (up to 64 KB) remain read-accessible while compressing next blocks. There is an exception for ring buffers, which can be
smaller than 64 KB. Ring-buffer scenario is automatically detected and handled within compress_HC_continue
.
Before starting compression, state must be allocated and properly initialized. createStreamHC
does both, though compression level is set to
CLEVEL_DEFAULT
.
Selecting the compression level can be done with resetStreamHC_fast
(starts a new stream) setCompressionLevel
(anytime, between blocks in the
same stream) (experimental). LZ4_resetStreamHC_fast()
only works on states which have been properly initialized at least once, which is
automatically the case when state is created using LZ4_createStreamHC()
.
After reset, a first "fictional block" can be designated as initial dictionary, using loadDictHC
(Optional).
Invoke compress_HC_continue
to compress each successive block. The number of blocks is unlimited. Previous input blocks, including initial
dictionary when present, must remain accessible and unmodified during compression.
It's allowed to update compression level anytime between blocks, using LZ4_setCompressionLevel()
(experimental).
dst
buffer should be sized to handle worst case scenarios (see compressBound
, it ensures compression success). In case of failure, the API
does not guarantee recovery, so the state must be reset. To ensure compression success whenever dst
buffer size cannot be made ≥
LZ4_compressBound()
, consider using compress_HC_continue_destSize
.
Whenever previous input blocks can't be preserved unmodified in-place during compression of next blocks, it's possible to copy the last blocks into a
more stable memory space, using saveDictHC
. Return value of LZ4_saveDictHC()
is the size of dictionary effectively saved into
safeBuffer
(≤ 64 KB)
After completing a streaming compression, it's possible to start a new stream of blocks, using the same LZ4_streamHC_t
state, just by
resetting it, using LZ4_resetStreamHC_fast()
.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
static final int
Compression level.static final int
Compression level.static final int
Compression level.static final int
Compression level.static final int
static final int
static final int
static final int
static final int
static final int
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
LZ4_attach_HC_dictionary
(long working_stream, long dictionary_stream) This is an experimental API that allows for the efficient use of a static dictionary many times.static int
LZ4_compress_HC
(ByteBuffer src, ByteBuffer dst, int compressionLevel) Compress data fromsrc
intodst
, using the powerful but slower "HC" algorithm.static int
LZ4_compress_HC_continue
(long streamHCPtr, ByteBuffer src, ByteBuffer dst) static int
LZ4_compress_HC_continue_destSize
(long streamHCPtr, ByteBuffer src, ByteBuffer dst, IntBuffer srcSizePtr) Similar tocompress_HC_continue
, but will read as much data as possible fromsrc
to fit intotargetDstSize
budget.static int
LZ4_compress_HC_destSize
(ByteBuffer stateHC, ByteBuffer src, ByteBuffer dst, IntBuffer srcSizePtr, int compressionLevel) Will compress as much data as possible fromsrc
to fit intotargetDstSize
budget.static int
LZ4_compress_HC_extStateHC
(ByteBuffer state, ByteBuffer src, ByteBuffer dst, int compressionLevel) Same ascompress_HC
, but using an externally allocated memory segment forstate
.static int
LZ4_compress_HC_extStateHC_fastReset
(ByteBuffer state, ByteBuffer src, ByteBuffer dst, int compressionLevel) A variant ofcompress_HC_extStateHC
.static long
Creates memory for LZ4 HC streaming state.static void
LZ4_favorDecompressionSpeed
(long LZ4_streamHCPtr, boolean favor) Parser will favor decompression speed over compression ratio.static int
LZ4_freeStreamHC
(long streamHCPtr) Releases memory for LZ4 HC streaming state.static long
LZ4_initStreamHC
(ByteBuffer buffer) Required before first use of a statically allocatedLZ4_streamHC_t
.static int
LZ4_loadDictHC
(long streamHCPtr, ByteBuffer dictionary) static void
LZ4_resetStreamHC_fast
(long LZ4_streamHCPtr, int compressionLevel) When anLZ4_streamHC_t
is known to be in a internally coherent state, it can often be prepared for a new compression with almost no work, only sometimes falling back to the full, expensive reset that is always required when the stream is in an indeterminate state (i.e., the reset performed byinitStreamHC
).static int
LZ4_saveDictHC
(long streamHCPtr, ByteBuffer safeBuffer) static void
LZ4_setCompressionLevel
(long LZ4_streamHCPtr, int compressionLevel) It's possible to change compression level between successive invocations ofLZ4_compress_HC_continue*()
for dynamic adaptation.static int
static void
nLZ4_attach_HC_dictionary
(long working_stream, long dictionary_stream) Unsafe version of:attach_HC_dictionary
static int
nLZ4_compress_HC
(long src, long dst, int srcSize, int dstCapacity, int compressionLevel) Unsafe version of:compress_HC
static int
nLZ4_compress_HC_continue
(long streamHCPtr, long src, long dst, int srcSize, int maxDstSize) static int
nLZ4_compress_HC_continue_destSize
(long streamHCPtr, long src, long dst, long srcSizePtr, int targetDstSize) Unsafe version of:compress_HC_continue_destSize
static int
nLZ4_compress_HC_destSize
(long stateHC, long src, long dst, long srcSizePtr, int targetDstSize, int compressionLevel) Unsafe version of:compress_HC_destSize
static int
nLZ4_compress_HC_extStateHC
(long state, long src, long dst, int srcSize, int maxDstSize, int compressionLevel) Unsafe version of:compress_HC_extStateHC
static int
nLZ4_compress_HC_extStateHC_fastReset
(long state, long src, long dst, int srcSize, int dstCapacity, int compressionLevel) Unsafe version of:compress_HC_extStateHC_fastReset
static void
nLZ4_favorDecompressionSpeed
(long LZ4_streamHCPtr, int favor) Unsafe version of:favorDecompressionSpeed
static int
nLZ4_freeStreamHC
(long streamHCPtr) Unsafe version of:freeStreamHC
static long
nLZ4_initStreamHC
(long buffer, long size) Unsafe version of:initStreamHC
static int
nLZ4_loadDictHC
(long streamHCPtr, long dictionary, int dictSize) static void
nLZ4_resetStreamHC_fast
(long LZ4_streamHCPtr, int compressionLevel) Unsafe version of:resetStreamHC_fast
static int
nLZ4_saveDictHC
(long streamHCPtr, long safeBuffer, int maxDictSize) static void
nLZ4_setCompressionLevel
(long LZ4_streamHCPtr, int compressionLevel) Unsafe version of:setCompressionLevel
-
Field Details
-
LZ4HC_CLEVEL_MIN
public static final int LZ4HC_CLEVEL_MINCompression level.- See Also:
-
LZ4HC_CLEVEL_DEFAULT
public static final int LZ4HC_CLEVEL_DEFAULTCompression level.- See Also:
-
LZ4HC_CLEVEL_OPT_MIN
public static final int LZ4HC_CLEVEL_OPT_MINCompression level.- See Also:
-
LZ4HC_CLEVEL_MAX
public static final int LZ4HC_CLEVEL_MAXCompression level.- See Also:
-
LZ4HC_DICTIONARY_LOGSIZE
public static final int LZ4HC_DICTIONARY_LOGSIZE- See Also:
-
LZ4HC_MAXD
public static final int LZ4HC_MAXD- See Also:
-
LZ4HC_MAXD_MASK
public static final int LZ4HC_MAXD_MASK- See Also:
-
LZ4HC_HASH_LOG
public static final int LZ4HC_HASH_LOG- See Also:
-
LZ4HC_HASHTABLESIZE
public static final int LZ4HC_HASHTABLESIZE- See Also:
-
LZ4HC_HASH_MASK
public static final int LZ4HC_HASH_MASK- See Also:
-
LZ4_STREAMHC_MINSIZE
public static final int LZ4_STREAMHC_MINSIZE- See Also:
-
-
Method Details
-
nLZ4_compress_HC
public static int nLZ4_compress_HC(long src, long dst, int srcSize, int dstCapacity, int compressionLevel) Unsafe version of:compress_HC
- Parameters:
srcSize
- max supported value isMAX_INPUT_SIZE
-
LZ4_compress_HC
Compress data fromsrc
intodst
, using the powerful but slower "HC" algorithm.Compression is guaranteed to succeed if
dstCapacity
≥compressBound
(srcSize)
`- Parameters:
dst
- must be already allocatedcompressionLevel
- any value between 1 andCLEVEL_MAX
will work. Values >CLEVEL_MAX
behave the same asCLEVEL_MAX
.- Returns:
- the number of bytes written into
dst
or 0 if compression fails
-
LZ4_sizeofStateHC
public static int LZ4_sizeofStateHC() -
nLZ4_compress_HC_extStateHC
public static int nLZ4_compress_HC_extStateHC(long state, long src, long dst, int srcSize, int maxDstSize, int compressionLevel) Unsafe version of:compress_HC_extStateHC
-
LZ4_compress_HC_extStateHC
public static int LZ4_compress_HC_extStateHC(ByteBuffer state, ByteBuffer src, ByteBuffer dst, int compressionLevel) Same ascompress_HC
, but using an externally allocated memory segment forstate
.state
size is provided bysizeofStateHC
. Memory segment must be aligned on 8-bytes boundaries (which a normalmalloc()
should do properly). -
nLZ4_compress_HC_destSize
public static int nLZ4_compress_HC_destSize(long stateHC, long src, long dst, long srcSizePtr, int targetDstSize, int compressionLevel) Unsafe version of:compress_HC_destSize
- Parameters:
srcSizePtr
- on success,*srcSizePtr
is updated to indicate how much bytes were read fromsrc
-
LZ4_compress_HC_destSize
public static int LZ4_compress_HC_destSize(ByteBuffer stateHC, ByteBuffer src, ByteBuffer dst, IntBuffer srcSizePtr, int compressionLevel) Will compress as much data as possible fromsrc
to fit intotargetDstSize
budget.- Parameters:
srcSizePtr
- on success,*srcSizePtr
is updated to indicate how much bytes were read fromsrc
- Returns:
- the number of bytes written into
dst
(necessarily ≤targetDstSize
) or 0 if compression fails - Since:
- 1.9.0
-
LZ4_createStreamHC
public static long LZ4_createStreamHC()Creates memory for LZ4 HC streaming state.Newly created states are automatically initialized. A same state can be used multiple times consecutively, starting with
resetStreamHC_fast
to start a new stream of blocks. -
nLZ4_freeStreamHC
public static int nLZ4_freeStreamHC(long streamHCPtr) Unsafe version of:freeStreamHC
-
LZ4_freeStreamHC
public static int LZ4_freeStreamHC(long streamHCPtr) Releases memory for LZ4 HC streaming state. -
nLZ4_resetStreamHC_fast
public static void nLZ4_resetStreamHC_fast(long LZ4_streamHCPtr, int compressionLevel) Unsafe version of:resetStreamHC_fast
-
LZ4_resetStreamHC_fast
public static void LZ4_resetStreamHC_fast(long LZ4_streamHCPtr, int compressionLevel) When anLZ4_streamHC_t
is known to be in a internally coherent state, it can often be prepared for a new compression with almost no work, only sometimes falling back to the full, expensive reset that is always required when the stream is in an indeterminate state (i.e., the reset performed byinitStreamHC
).LZ4_streamHC
s are guaranteed to be in a valid state when:- returned from
createStreamHC
- reset by
initStreamHC
memset(stream, 0, sizeof(LZ4_streamHC_t))
- the stream was in a valid state and was reset by
resetStreamHC_fast
- the stream was in a valid state and was then used in any compression call that returned success
- the stream was in an indeterminate state and was used in a compression call that fully reset the state (
compress_HC_extStateHC
) and that returned success
Note: A stream that was last used in a compression call that returned an error may be passed to this function. However, it will be fully reset, which will clear any existing history and settings from the context.
- returned from
-
nLZ4_loadDictHC
public static int nLZ4_loadDictHC(long streamHCPtr, long dictionary, int dictSize) -
LZ4_loadDictHC
-
nLZ4_compress_HC_continue
public static int nLZ4_compress_HC_continue(long streamHCPtr, long src, long dst, int srcSize, int maxDstSize) -
LZ4_compress_HC_continue
-
nLZ4_compress_HC_continue_destSize
public static int nLZ4_compress_HC_continue_destSize(long streamHCPtr, long src, long dst, long srcSizePtr, int targetDstSize) Unsafe version of:compress_HC_continue_destSize
- Parameters:
srcSizePtr
- on success,*srcSizePtr
will be updated to indicate how much bytes were read fromsrc
. Note that this function may not consume the entire input.
-
LZ4_compress_HC_continue_destSize
public static int LZ4_compress_HC_continue_destSize(long streamHCPtr, ByteBuffer src, ByteBuffer dst, IntBuffer srcSizePtr) Similar tocompress_HC_continue
, but will read as much data as possible fromsrc
to fit intotargetDstSize
budget.- Parameters:
srcSizePtr
- on success,*srcSizePtr
will be updated to indicate how much bytes were read fromsrc
. Note that this function may not consume the entire input.- Returns:
- the number of bytes written into
dst
(necessarily ≤ targetDstSize) or 0 if compression fails - Since:
- 1.9.0
-
nLZ4_saveDictHC
public static int nLZ4_saveDictHC(long streamHCPtr, long safeBuffer, int maxDictSize) -
LZ4_saveDictHC
-
nLZ4_initStreamHC
public static long nLZ4_initStreamHC(long buffer, long size) Unsafe version of:initStreamHC
-
LZ4_initStreamHC
Required before first use of a statically allocatedLZ4_streamHC_t
.- Since:
- 1.9.0
-
nLZ4_setCompressionLevel
public static void nLZ4_setCompressionLevel(long LZ4_streamHCPtr, int compressionLevel) Unsafe version of:setCompressionLevel
-
LZ4_setCompressionLevel
public static void LZ4_setCompressionLevel(long LZ4_streamHCPtr, int compressionLevel) It's possible to change compression level between successive invocations ofLZ4_compress_HC_continue*()
for dynamic adaptation. -
nLZ4_favorDecompressionSpeed
public static void nLZ4_favorDecompressionSpeed(long LZ4_streamHCPtr, int favor) Unsafe version of:favorDecompressionSpeed
-
LZ4_favorDecompressionSpeed
public static void LZ4_favorDecompressionSpeed(long LZ4_streamHCPtr, boolean favor) Parser will favor decompression speed over compression ratio.Only applicable to levels ≥
CLEVEL_OPT_MIN
.- Since:
- version 1.8.2 (experimental)
-
nLZ4_compress_HC_extStateHC_fastReset
public static int nLZ4_compress_HC_extStateHC_fastReset(long state, long src, long dst, int srcSize, int dstCapacity, int compressionLevel) Unsafe version of:compress_HC_extStateHC_fastReset
-
LZ4_compress_HC_extStateHC_fastReset
public static int LZ4_compress_HC_extStateHC_fastReset(ByteBuffer state, ByteBuffer src, ByteBuffer dst, int compressionLevel) A variant ofcompress_HC_extStateHC
.Using this variant avoids an expensive initialization step. It is only safe to call if the state buffer is known to be correctly initialized already (see comment on
resetStreamHC_fast
for a definition of "correctly initialized"). From a high level, the difference is that this function initializes the provided state with a call toresetStreamHC_fast
whilecompress_HC_extStateHC
starts with a call toinitStreamHC
. -
nLZ4_attach_HC_dictionary
public static void nLZ4_attach_HC_dictionary(long working_stream, long dictionary_stream) Unsafe version of:attach_HC_dictionary
-
LZ4_attach_HC_dictionary
public static void LZ4_attach_HC_dictionary(long working_stream, long dictionary_stream) This is an experimental API that allows for the efficient use of a static dictionary many times.Rather than re-loading the dictionary buffer into a working context before each compression, or copying a pre-loaded dictionary's
LZ4_streamHC_t
into a workingLZ4_streamHC_t
, this function introduces a no-copy setup mechanism, in which the working stream references the dictionary stream in-place.Several assumptions are made about the state of the dictionary stream. Currently, only streams which have been prepared by
loadDictHC
should be expected to work.Alternatively, the provided dictionary stream pointer may be
NULL
, in which case any existing dictionary stream is unset.A dictionary should only be attached to a stream without any history (i.e., a stream that has just been reset).
The dictionary will remain attached to the working stream only for the current stream session. Calls to
resetStreamHC_fast
will remove the dictionary context association from the working stream. The dictionary stream (and source buffer) must remain in-place / accessible / unchanged through the lifetime of the stream session.
-