Class LZ4HC
- java.lang.Object
-
- org.lwjgl.util.lz4.LZ4HC
-
public class LZ4HC extends java.lang.Object
Native bindings to the high-compression API of LZ4.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 toCLEVEL_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 usingLZ4_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 (seecompressBound
, it ensures compression success). In case of failure, the API does not guarantee recovery, so the state must be reset. To ensure compression success wheneverdst
buffer size cannot be made ≥LZ4_compressBound()
, consider usingcompress_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 ofLZ4_saveDictHC()
is the size of dictionary effectively saved intosafeBuffer
(≤ 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, usingLZ4_resetStreamHC_fast()
.
-
-
Field Summary
Fields Modifier and Type Field Description static int
LZ4_STREAMHCSIZE
LZ4_STREAMHCSIZE_SIZETstatic int
LZ4HC_CLEVEL_DEFAULT
LZ4HC_CLEVEL_MAX
LZ4HC_CLEVEL_MIN
LZ4HC_CLEVEL_OPT_MINCompression level.static int
LZ4HC_DICTIONARY_LOGSIZE
LZ4HC_HASH_LOG
LZ4HC_HASH_MASK
LZ4HC_HASHTABLESIZE
LZ4HC_MAXD
LZ4HC_MAXD_MASK
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description 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.static int
LZ4_compress_HC(java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)
Compress data fromsrc
intodst
, using the powerful but slower "HC" algorithm.static int
LZ4_compress_HC_continue(long streamHCPtr, java.nio.ByteBuffer src, java.nio.ByteBuffer dst)
static int
LZ4_compress_HC_continue_destSize(long streamHCPtr, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, java.nio.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(java.nio.ByteBuffer stateHC, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, java.nio.IntBuffer srcSizePtr, int compressionLevel)
Will compress as much data as possible fromsrc
to fit intotargetDstSize
budget.static int
LZ4_compress_HC_extStateHC(java.nio.ByteBuffer state, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)
Same ascompress_HC
, but using an externally allocated memory segment forstate
.static int
LZ4_compress_HC_extStateHC_fastReset(java.nio.ByteBuffer state, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)
A variant ofcompress_HC_extStateHC
.static long
LZ4_createStreamHC()
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(java.nio.ByteBuffer buffer)
Required before first use of a statically allocatedLZ4_streamHC_t
.static int
LZ4_loadDictHC(long streamHCPtr, java.nio.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, java.nio.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
LZ4_sizeofStateHC()
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 Detail
-
LZ4HC_CLEVEL_MIN, LZ4HC_CLEVEL_DEFAULT, LZ4HC_CLEVEL_OPT_MIN, LZ4HC_CLEVEL_MAX
Compression level.
-
LZ4HC_DICTIONARY_LOGSIZE
- See Also:
- Constant Field Values
-
LZ4HC_MAXD
- See Also:
- Constant Field Values
-
LZ4HC_MAXD_MASK
- See Also:
- Constant Field Values
-
LZ4HC_HASH_LOG
- See Also:
- Constant Field Values
-
LZ4HC_HASHTABLESIZE
- See Also:
- Constant Field Values
-
LZ4HC_HASH_MASK
- See Also:
- Constant Field Values
-
LZ4_STREAMHCSIZE
-
LZ4_STREAMHCSIZE_SIZET
public static final int LZ4_STREAMHCSIZE_SIZET
-
-
Method Detail
-
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
public static int LZ4_compress_HC(java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)
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(java.nio.ByteBuffer state, java.nio.ByteBuffer src, java.nio.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(java.nio.ByteBuffer stateHC, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, java.nio.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
public static int LZ4_loadDictHC(long streamHCPtr, java.nio.ByteBuffer dictionary)
-
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
public static int LZ4_compress_HC_continue(long streamHCPtr, java.nio.ByteBuffer src, java.nio.ByteBuffer dst)
-
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, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, java.nio.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
public static int LZ4_saveDictHC(long streamHCPtr, java.nio.ByteBuffer safeBuffer)
-
nLZ4_initStreamHC
public static long nLZ4_initStreamHC(long buffer, long size)
Unsafe version of:initStreamHC
-
LZ4_initStreamHC
public static long LZ4_initStreamHC(java.nio.ByteBuffer buffer)
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(java.nio.ByteBuffer state, java.nio.ByteBuffer src, java.nio.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.
-
-