Package org.lwjgl.util.lz4

Class 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. 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 buffers scenario is automatically detected and handled by LZ4_compress_HC_continue().

    Before starting compression, state must be properly initialized, using resetStreamHC. A first "fictional block" can then be designated as initial dictionary, using loadDictHC (Optional).

    Then, use compress_HC_continue to compress each successive block. Previous memory blocks (including initial dictionary when present) must remain accessible and unmodified during compression. dst buffer should be sized to handle worst case scenarios (see compressBound), to ensure operation success. Because in case of failure, the API does not guarantee context recovery, and context will have to be reset. If dst buffer budget cannot be ≥ compressBound, consider using compress_HC_continue_destSize instead.

    If, for any reason, previous data block can't be preserved unmodified in memory for next compression block, you can save it to a more stable memory space, using saveDictHC. Return value of saveDictHC is the size of dictionary effectively saved into safeBuffer.

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

      • LZ4_compress_HC

        public static int LZ4_compress_HC​(java.nio.ByteBuffer src,
                                  java.nio.ByteBuffer dst,
                                  int compressionLevel)
        Compress data from src into dst, using the more powerful but slower "HC" algorithm. dst must be already allocated.

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

        Parameters:
        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​(java.nio.ByteBuffer state,
                                             java.nio.ByteBuffer src,
                                             java.nio.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).

      • LZ4_createStreamHC

        public static long LZ4_createStreamHC()
        Creates memory for LZ4 HC streaming state.

        Newly created states are automatically initialized. Existing states can be re-used several times, using resetStreamHC.

      • 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

        public static void nLZ4_resetStreamHC​(long streamHCPtr,
                                      int compressionLevel)

      • LZ4_resetStreamHC

        public static void LZ4_resetStreamHC​(long streamHCPtr,
                                     int compressionLevel)

      • 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_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_compress_HC_destSize

        public static int nLZ4_compress_HC_destSize​(long LZ4HC_Data,
                                            long src,
                                            long dst,
                                            long srcSizePtr,
                                            int targetDstSize,
                                            int compressionLevel)
        Unsafe version of: compress_HC_destSize
        Parameters:
        srcSizePtr - value will be updated to indicate how much bytes were read from src

      • LZ4_compress_HC_destSize

        public static int LZ4_compress_HC_destSize​(java.nio.ByteBuffer LZ4HC_Data,
                                           java.nio.ByteBuffer src,
                                           java.nio.ByteBuffer dst,
                                           java.nio.IntBuffer srcSizePtr,
                                           int compressionLevel)
        Will try to compress as much data from src as possible that can fit into targetDstSize budget.
        Parameters:
        srcSizePtr - value will be updated to indicate how much bytes were read from src
        Returns:
        the number of bytes written into dst or 0 if compression fails

      • nLZ4_compress_HC_continue_destSize

        public static int nLZ4_compress_HC_continue_destSize​(long LZ4_streamHCPtr,
                                                     long src,
                                                     long dst,
                                                     long srcSizePtr,
                                                     int targetDstSize)
        Unsafe version of: compress_HC_continue_destSize
        Parameters:
        srcSizePtr - value will be updated to indicate how much bytes were read from src

      • LZ4_compress_HC_continue_destSize

        public static int LZ4_compress_HC_continue_destSize​(long LZ4_streamHCPtr,
                                                    java.nio.ByteBuffer src,
                                                    java.nio.ByteBuffer dst,
                                                    java.nio.IntBuffer srcSizePtr)
        Similar as compress_HC_continue, but will read a variable nb of bytes from src to fit into targetDstSize budget.
        Parameters:
        srcSizePtr - value will be updated to indicate how much bytes were read from src
        Returns:
        the number of bytes written into dst or 0 if compression fails

      • 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 2 invocations of LZ4_compress_HC_continue*().

      • 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 select decisions favoring decompression over compression ratio.

        Only works at highest compression settings (level ≥ CLEVEL_OPT_MIN)

        Since:
        version 1.8.2 (experimental)

      • 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 resetStreamHC).

        LZ4_streamHCs are guaranteed to be in a valid state when:

        • returned from createStreamHC
        • reset by resetStreamHC
        • 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

      • 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 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 resetStreamHC.

      • 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 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 LZ4_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.