Module org.elasticsearch.nativeaccess

Package org.elasticsearch.nativeaccess.lib

Interface ZstdLibrary

public interface ZstdLibrary

FFM binding for a subset of libzstd.

Java long parameters and return values map to C size_t, which is 8 bytes on every 64-bit platform Elasticsearch ships on. Binding these as int would leave the upper bits of the argument register undefined and cause libzstd to read garbage as part of the size — see #150690 for context.

The *Heap variants bind the same C symbol with @Critical so the linker can use the fast path when the caller passes on-heap memory segments.

See Also:

• zstd manual

Method Summary

Modifier and Type	Method	Description
long	compress(MemorySegment dst, long dstCap, MemorySegment src, long srcSize, int level)	Compress src as a single zstd frame into dst.
long	compressBound(long srcSize)	Maximum compressed size for a given source size, in the worst-case single-pass scenario.
long	compressHeap(MemorySegment dst, long dstCap, MemorySegment src, long srcSize, int level)	Heap-friendly variant of compress(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long, int): same C symbol bound with the critical linker option so on-heap MemorySegment arguments avoid a JNI copy.
MemorySegment	createDStream()	Allocate a streaming decompression context (ZSTD_DStream).
long	decompress(MemorySegment dst, long dstCap, MemorySegment src, long srcSize)	Decompress one or more complete zstd frames in src into dst.
long	decompressHeap(MemorySegment dst, long dstCap, MemorySegment src, long srcSize)	Heap-friendly variant of decompress(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long): same C symbol bound with the critical linker option so on-heap MemorySegment arguments avoid a JNI copy.
long	decompressStream(MemorySegment dstream, MemorySegment output, MemorySegment input)	Drive one step of streaming decompression.
long	dStreamInSize()	Recommended input buffer size for streaming decompression.
long	dStreamOutSize()	Recommended output buffer size for streaming decompression.
long	freeDStream(MemorySegment dstream)	Release a streaming decompression context previously obtained from createDStream().
String	getErrorName(long code)	Returns a human-readable name for the error encoded in code, or "No Error" when code is not an error.
boolean	isError(long code)	Tests whether a size_t return value from the one-shot or streaming APIs encodes an error.

Method Details

compressBound

long compressBound(long srcSize)

Maximum compressed size for a given source size, in the worst-case single-pass scenario.

See Also:

• ZSTD_compressBound

compress

long compress(MemorySegment dst,
 long dstCap,
 MemorySegment src,
 long srcSize,
 int level)

Compress src as a single zstd frame into dst.

Returns:

the compressed size written into dst (≤ dstCap), or an error code testable with isError(long).

See Also:

• ZSTD_compress

compressHeap

long compressHeap(MemorySegment dst,
 long dstCap,
 MemorySegment src,
 long srcSize,
 int level)

Heap-friendly variant of compress(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long, int): same C symbol bound with the critical linker option so on-heap MemorySegment arguments avoid a JNI copy. On JDK 21 the critical linker option is unavailable, so the binding is wrapped by ZstdHeapFallback.compressHeap(java.lang.invoke.MethodHandle, java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long, int) which stages the heap segments off-heap before the libzstd call.

decompress

long decompress(MemorySegment dst,
 long dstCap,
 MemorySegment src,
 long srcSize)

Decompress one or more complete zstd frames in src into dst. srcSize must be the exact size of the compressed input.

Returns:

the number of bytes written into dst (≤ dstCap), or an error code testable with isError(long).

See Also:

• ZSTD_decompress

decompressHeap

long decompressHeap(MemorySegment dst,
 long dstCap,
 MemorySegment src,
 long srcSize)

Heap-friendly variant of decompress(java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long): same C symbol bound with the critical linker option so on-heap MemorySegment arguments avoid a JNI copy. On JDK 21 the critical linker option is unavailable, so the binding is wrapped by ZstdHeapFallback.decompressHeap(java.lang.invoke.MethodHandle, java.lang.foreign.MemorySegment, long, java.lang.foreign.MemorySegment, long) which stages the heap segments off-heap before the libzstd call.

isError

boolean isError(long code)

Tests whether a size_t return value from the one-shot or streaming APIs encodes an error.

See Also:

• ZSTD_isError

getErrorName

String getErrorName(long code)

Returns a human-readable name for the error encoded in code, or "No Error" when code is not an error.

See Also:

• ZSTD_getErrorName

createDStream

MemorySegment createDStream()

Allocate a streaming decompression context (ZSTD_DStream). Returns NULL (i.e. a zero address) on allocation failure. The returned segment must be released with freeDStream(MemorySegment).

See Also:

• ZSTD_createDStream

freeDStream

long freeDStream(MemorySegment dstream)

Release a streaming decompression context previously obtained from createDStream(). Accepts a NULL address as a no-op.

See Also:

• ZSTD_freeDStream

dStreamInSize

long dStreamInSize()

Recommended input buffer size for streaming decompression.

See Also:

• ZSTD_DStreamInSize

dStreamOutSize

long dStreamOutSize()

Recommended output buffer size for streaming decompression. libzstd guarantees this is enough to flush at least one complete decompressed block.

See Also:

• ZSTD_DStreamOutSize

decompressStream

long decompressStream(MemorySegment dstream,
 MemorySegment output,
 MemorySegment input)

Drive one step of streaming decompression. Called repeatedly with the same context, advancing the pos fields on the ZSTD_outBuffer / ZSTD_inBuffer structs.

Returns:

0 when a frame is completely decoded and fully flushed, an error code testable with isError(long), or any other positive value, which is a hint at how many more input bytes are expected to complete the current frame.

See Also:

• ZSTD_decompressStream