Package org.lwjgl.util.lz4

Class LZ4HC

java.lang.Object
org.lwjgl.util.lz4.LZ4HC
public class LZ4HC extends 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 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). Note: In order for loadDictHC to create the correct data structure, it is essential to set the compression level before loading the dictionary.

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 Details

  • 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 is MAX_INPUT_SIZE

    • LZ4_compress_HC

      public static int LZ4_compress_HC(ByteBuffer src, ByteBuffer dst, int compressionLevel)
      Compress data from src into dst, using the powerful but slower "HC" algorithm.

      Compression is guaranteed to succeed if dstCapacity ≥ compressBound(srcSize)`

      Parameters:
      dst - must be already allocated
      compressionLevel - any value between 1 and CLEVEL_MAX will work. Values > CLEVEL_MAX behave the same as CLEVEL_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 as compress_HC, but using an externally allocated memory segment for state.

      state size is provided by sizeofStateHC. Memory segment must be aligned on 8-bytes boundaries (which a normal malloc() 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 from src

    • 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 from src to fit into targetDstSize budget.
      Parameters:
      srcSizePtr - on success, *srcSizePtr is updated to indicate how much bytes were read from src
      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 an LZ4_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 by initStreamHC).

      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.

    • nLZ4_loadDictHC

      public static int nLZ4_loadDictHC(long streamHCPtr, long dictionary, int dictSize)

    • LZ4_loadDictHC

      public static int LZ4_loadDictHC(long streamHCPtr, 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, ByteBuffer src, 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 from src. 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 to compress_HC_continue, but will read as much data as possible from src to fit into targetDstSize budget.
      Parameters:
      srcSizePtr - on success, *srcSizePtr will be updated to indicate how much bytes were read from src. 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, ByteBuffer safeBuffer)

    • 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 API allows for the efficient re-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 working LZ4_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.

      Since:
      1.10.0

    • nLZ4_initStreamHC

      public static long nLZ4_initStreamHC(long buffer, long size)
      Unsafe version of: initStreamHC

    • LZ4_initStreamHC

      public static long LZ4_initStreamHC(ByteBuffer buffer)
      Required before first use of a statically allocated LZ4_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 of LZ4_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 of compress_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 to resetStreamHC_fast while compress_HC_extStateHC starts with a call to initStreamHC.