Class LZ4HC
- java.lang.Object
-
- org.lwjgl.util.lz4.LZ4HC
-
public class LZ4HC extends java.lang.ObjectNative 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.
createStreamHCdoes 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_continueto 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).dstbuffer 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 wheneverdstbuffer 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_tstate, just by resetting it, usingLZ4_resetStreamHC_fast().
-
-
Field Summary
Fields Modifier and Type Field Description static intLZ4_STREAMHCSIZE
LZ4_STREAMHCSIZE_VOIDPstatic intLZ4HC_CLEVEL_DEFAULT
LZ4HC_CLEVEL_MAX
LZ4HC_CLEVEL_MIN
LZ4HC_CLEVEL_OPT_MINCompression level.static intLZ4HC_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 voidLZ4_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 intLZ4_compress_HC(java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)Compress data fromsrcintodst, using the powerful but slower "HC" algorithm.static intLZ4_compress_HC_continue(long streamHCPtr, java.nio.ByteBuffer src, java.nio.ByteBuffer dst)static intLZ4_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 fromsrcto fit intotargetDstSizebudget.static intLZ4_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 fromsrcto fit intotargetDstSizebudget.static intLZ4_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 intLZ4_compress_HC_extStateHC_fastReset(java.nio.ByteBuffer state, java.nio.ByteBuffer src, java.nio.ByteBuffer dst, int compressionLevel)A variant ofcompress_HC_extStateHC.static longLZ4_createStreamHC()Creates memory for LZ4 HC streaming state.static voidLZ4_favorDecompressionSpeed(long LZ4_streamHCPtr, boolean favor)Parser will favor decompression speed over compression ratio.static intLZ4_freeStreamHC(long streamHCPtr)Releases memory for LZ4 HC streaming state.static longLZ4_initStreamHC(java.nio.ByteBuffer buffer)Required before first use of a statically allocatedLZ4_streamHC_t.static intLZ4_loadDictHC(long streamHCPtr, java.nio.ByteBuffer dictionary)static voidLZ4_resetStreamHC_fast(long LZ4_streamHCPtr, int compressionLevel)When anLZ4_streamHC_tis 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 intLZ4_saveDictHC(long streamHCPtr, java.nio.ByteBuffer safeBuffer)static voidLZ4_setCompressionLevel(long LZ4_streamHCPtr, int compressionLevel)It's possible to change compression level between successive invocations ofLZ4_compress_HC_continue*()for dynamic adaptation.static intLZ4_sizeofStateHC()static voidnLZ4_attach_HC_dictionary(long working_stream, long dictionary_stream)Unsafe version of:attach_HC_dictionarystatic intnLZ4_compress_HC(long src, long dst, int srcSize, int dstCapacity, int compressionLevel)Unsafe version of:compress_HCstatic intnLZ4_compress_HC_continue(long streamHCPtr, long src, long dst, int srcSize, int maxDstSize)static intnLZ4_compress_HC_continue_destSize(long streamHCPtr, long src, long dst, long srcSizePtr, int targetDstSize)Unsafe version of:compress_HC_continue_destSizestatic intnLZ4_compress_HC_destSize(long stateHC, long src, long dst, long srcSizePtr, int targetDstSize, int compressionLevel)Unsafe version of:compress_HC_destSizestatic intnLZ4_compress_HC_extStateHC(long state, long src, long dst, int srcSize, int maxDstSize, int compressionLevel)Unsafe version of:compress_HC_extStateHCstatic intnLZ4_compress_HC_extStateHC_fastReset(long state, long src, long dst, int srcSize, int dstCapacity, int compressionLevel)Unsafe version of:compress_HC_extStateHC_fastResetstatic voidnLZ4_favorDecompressionSpeed(long LZ4_streamHCPtr, int favor)Unsafe version of:favorDecompressionSpeedstatic intnLZ4_freeStreamHC(long streamHCPtr)Unsafe version of:freeStreamHCstatic longnLZ4_initStreamHC(long buffer, long size)Unsafe version of:initStreamHCstatic intnLZ4_loadDictHC(long streamHCPtr, long dictionary, int dictSize)static voidnLZ4_resetStreamHC_fast(long LZ4_streamHCPtr, int compressionLevel)Unsafe version of:resetStreamHC_faststatic intnLZ4_saveDictHC(long streamHCPtr, long safeBuffer, int maxDictSize)static voidnLZ4_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
- See Also:
- Constant Field Values
-
LZ4_STREAMHCSIZE_VOIDP
-
-
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 fromsrcintodst, 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_MAXwill work. Values >CLEVEL_MAXbehave the same asCLEVEL_MAX.- Returns:
- the number of bytes written into
dstor 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.statesize 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,*srcSizePtris 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 fromsrcto fit intotargetDstSizebudget.- Parameters:
srcSizePtr- on success,*srcSizePtris 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_fastto 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_tis 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_streamHCs 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,*srcSizePtrwill 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 fromsrcto fit intotargetDstSizebudget.- Parameters:
srcSizePtr- on success,*srcSizePtrwill 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_fastfor a definition of "correctly initialized"). From a high level, the difference is that this function initializes the provided state with a call toresetStreamHC_fastwhilecompress_HC_extStateHCstarts 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_tinto 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
loadDictHCshould 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_fastwill 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.
-
-