Block API

Single-block compression/decompression without file framing. More...

Typedefs
typedef struct zxc_cctx_s	zxc_cctx
	Opaque reusable compression context (see zxc_create_cctx).
typedef struct zxc_dctx_s	zxc_dctx
	Opaque reusable decompression context (see zxc_create_dctx).

Functions
uint64_t	zxc_compress_block_bound (size_t input_size)
	Maximum compressed size for a single block.
uint64_t	zxc_decompress_block_bound (const size_t uncompressed_size)
	Minimum dst_capacity zxc_decompress_block() needs for a block of uncompressed_size bytes.
int64_t	zxc_compress_block (zxc_cctx *cctx, const void *src, size_t src_size, void *dst, size_t dst_capacity, const zxc_compress_opts_t *opts)
	Compresses a single block without file framing.
int64_t	zxc_decompress_block (zxc_dctx *dctx, const void *src, size_t src_size, void *dst, size_t dst_capacity, const zxc_decompress_opts_t *opts)
	Decompresses a single block produced by zxc_compress_block().
int64_t	zxc_decompress_block_safe (zxc_dctx *dctx, const void *src, const size_t src_size, void *dst, const size_t dst_capacity, const zxc_decompress_opts_t *opts)
	Decompresses a single block into an exactly-sized destination.
uint64_t	zxc_estimate_cctx_size (size_t src_size, int level)
	Estimates peak compression memory for a given block size and level.

Detailed Description

Single-block compression/decompression without file framing.

Each call handles one independent block and emits only block_header(8B) + payload + optional checksum(4B): no file header, EOF block, or footer. Meant for filesystem integrations that do their own block indexing and compress each block independently.

Typical usage

// Compress a single filesystem block
zxc_cctx* cctx = zxc_create_cctx(NULL);
zxc_compress_opts_t opts = { .level = 3 };
size_t bound = zxc_compress_block_bound(block_size);
void *dst = malloc(bound);
int64_t csize = zxc_compress_block(cctx, block, block_size, dst, bound, &opts);
 
// Decompress
zxc_dctx* dctx = zxc_create_dctx();
int64_t dsize = zxc_decompress_block(dctx, dst, csize, out, block_size, NULL);
 
zxc_free_cctx(cctx);
zxc_free_dctx(dctx);

Typedef Documentation

zxc_cctx

typedef struct zxc_cctx_s zxc_cctx

Opaque reusable compression context (see zxc_create_cctx).

Definition at line 327 of file zxc_buffer.h.

zxc_dctx

typedef struct zxc_dctx_s zxc_dctx

Opaque reusable decompression context (see zxc_create_dctx).

Definition at line 329 of file zxc_buffer.h.

Function Documentation

zxc_compress_block()

int64_t zxc_compress_block	(	zxc_cctx *	cctx,
		const void *	src,
		const size_t	src_size,
		void *	dst,
		const size_t	dst_capacity,
		const zxc_compress_opts_t *	opts
	)

Compresses a single block without file framing.

Output is block_header(8B) + payload + optional checksum(4B), readable by zxc_decompress_block(). The checksum covers the uncompressed bytes, seeded with position 0. One format-conformant block per call: src_size must not exceed ZXC_BLOCK_SIZE_MAX (2 MiB). For larger payloads use the frame API (zxc_compress) or the streaming API (zxc_cstream_*), which chunk transparently.

Parameters

[in,out]	cctx	Reusable compression context.
[in]	src	Source data.
[in]	src_size	Source size in bytes, in [1, ZXC_BLOCK_SIZE_MAX].
[out]	dst	Destination buffer.
[in]	dst_capacity	Capacity of dst (see zxc_compress_block_bound()).
[in]	opts	Compression options, or NULL for defaults. level, block_size, checksum_enabled and the dictionary fields are used; the shared table is rebuilt only when it changes. seekable is ignored and not remembered.

Note

src and dst must not overlap (same contract as memcpy).

Returns

Compressed block size (> 0), or a negative zxc_error_t. ZXC_ERROR_BAD_BLOCK_SIZE if src_size exceeds ZXC_BLOCK_SIZE_MAX; ZXC_ERROR_BAD_LEVEL on a static context for a level raise its workspace cannot accommodate (levels above ZXC_LEVEL_ULTRA are otherwise silently clamped); ZXC_ERROR_DICT_UNSUPPORTED on a static context with a dictionary.

Compresses a single block without file framing.

Public API; full contract in zxc_buffer.h. Produces one format-conformant block with no header / EOF / footer, so src_size must not exceed ZXC_BLOCK_SIZE_MAX (use the frame or streaming APIs for larger inputs). With a dictionary in opts, [dict | block] is assembled in the cctx-owned bounce buffer before encoding. Inner buffers are re-initialised when the effective block size changes, or when a per-call level raise into the optimal-parser tier requires the opt_scratch region; static contexts reject both cases instead (the workspace cannot grow).

Definition at line 1668 of file zxc_dispatch.c.

References zxc_compress_block_at().

zxc_compress_block_bound()

uint64_t zxc_compress_block_bound

(

const size_t

input_size

)

Maximum compressed size for a single block.

Unlike zxc_compress_bound(), this excludes file header, EOF block, and footer overhead. Use it to size the destination of zxc_compress_block().

Parameters

[in]

input_size

Uncompressed block size in bytes (must be <= ZXC_BLOCK_SIZE_MAX).

Returns

Upper bound on the compressed block size, or 0 if input_size is out of range for the Block API or would overflow.

Maximum compressed size for a single block.

Definition at line 1046 of file zxc_common.c.

References ZXC_BLOCK_CHECKSUM_SIZE, ZXC_BLOCK_FORMAT_OVERHEAD, ZXC_BLOCK_HEADER_SIZE, and ZXC_BLOCK_SIZE_MAX.

Referenced by cs_compress_block_from(), ds_handle_need_file_header(), zxc_cstream_out_size(), and zxc_dstream_in_size().

zxc_decompress_block()

int64_t zxc_decompress_block	(	zxc_dctx *	dctx,
		const void *	src,
		const size_t	src_size,
		void *	dst,
		const size_t	dst_capacity,
		const zxc_decompress_opts_t *	opts
	)

Decompresses a single block produced by zxc_compress_block().

One format-conformant block per call: dst_capacity must not exceed ZXC_BLOCK_SIZE_MAX + ZXC_DECOMPRESS_TAIL_PAD (what zxc_decompress_block_bound() returns for the maximum block size). For payloads from the frame or streaming APIs, use zxc_decompress instead.

Parameters

[in,out]	dctx	Reusable decompression context.
[in]	src	Compressed block.
[in]	src_size	Compressed size in bytes.
[out]	dst	Destination buffer.
[in]	dst_capacity	At least the uncompressed size, at most ZXC_BLOCK_SIZE_MAX + ZXC_DECOMPRESS_TAIL_PAD. At zxc_decompress_block_bound() a dictionary-free block on a heap context decodes straight into dst, else possibly through a bounce.
[in]	opts	Decompression options, or NULL for defaults. checksum_enabled and the dictionary fields are used; a block carries no dictionary id, so pass the same (content, table) pair as at compression. Static context: ZXC_ERROR_DICT_UNSUPPORTED. The checksum is checked after decoding, at position 0: a frame's later blocks fail it.

Note

src and dst must not overlap (same contract as memcpy).

Returns

Decompressed size (> 0), or a negative zxc_error_t; ZXC_ERROR_BAD_BLOCK_SIZE if dst_capacity exceeds the per-block limit. Static context: the carved block is the effective capacity; a larger block is ZXC_ERROR_BAD_BLOCK_SIZE while it fits the workspace margin and fails like a too-small destination beyond it. On error dst holds whatever the decode wrote, all of it on ZXC_ERROR_BAD_CHECKSUM; its previous contents do not survive.

Decompresses a single block produced by zxc_compress_block().

Public API; full contract in zxc_buffer.h. Decodes one format-conformant block; the decoded payload cannot exceed ZXC_BLOCK_SIZE_MAX, so dst_capacity is bounded by ZXC_BLOCK_SIZE_MAX + ZXC_DECOMPRESS_TAIL_PAD. With a dictionary in opts the decode runs through the [dict | decode] bounce buffer; otherwise it goes straight into dst, and is redone through work_buf if a tight tail aborted it, leaving dst partly written.

Definition at line 1848 of file zxc_dispatch.c.

References zxc_decompress_opts_t::checksum_enabled, zxc_decompress_opts_t::dict, zxc_cctx_t::dict_buffer, zxc_cctx_t::dict_size, ZXC_BLOCK_HEADER_SIZE, zxc_block_size_ceil(), ZXC_BLOCK_SIZE_MAX, zxc_ctx_sync_dict_huf(), zxc_dctx_prepare(), zxc_decode_bounce(), zxc_decompress_chunk_wrapper(), ZXC_DECOMPRESS_TAIL_PAD, ZXC_DICT_SIZE_MAX, ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_DST_TOO_SMALL, ZXC_ERROR_NULL_INPUT, ZXC_ERROR_OVERFLOW, ZXC_OK, ZXC_OPTS_DICT_HUF, ZXC_OPTS_DICT_SIZE, and zxc_static_decompress_block().

Referenced by zxc_decompress_block_safe().

zxc_decompress_block_bound()

uint64_t zxc_decompress_block_bound

(

const size_t

uncompressed_size

)

Minimum dst_capacity zxc_decompress_block() needs for a block of uncompressed_size bytes.

The decoder uses speculative (wild-copy) writes on its fast path, so it needs a tail pad beyond the declared size: with this value a dictionary-free block decodes straight into dst on a heap context; without it, through a bounce and a copy. A dictionary block always bounces, needing the dictionary and the payload contiguous, and so does an over-sized static context.

Parameters

[in]

uncompressed_size

Original block size in bytes (must be <= ZXC_BLOCK_SIZE_MAX).

Returns

Minimum dst_capacity, or 0 if uncompressed_size is out of range for the Block API or would overflow.

Minimum dst_capacity zxc_decompress_block() needs for a block of uncompressed_size bytes.

The decoder uses speculative wild-copy writes on its fast path. Sizing the destination to uncompressed_size + ZXC_PAD_SIZE*66 guarantees the fast path is always reachable and that tail bounds checks never spuriously reject the last literals of a valid block.

Returns 0 if uncompressed_size exceeds ZXC_BLOCK_SIZE_MAX (the Block API limit), or if the arithmetic would overflow.

Definition at line 1068 of file zxc_common.c.

References ZXC_BLOCK_SIZE_MAX, and ZXC_DECOMPRESS_TAIL_PAD.

zxc_decompress_block_safe()

int64_t zxc_decompress_block_safe	(	zxc_dctx *	dctx,
		const void *	src,
		const size_t	src_size,
		void *	dst,
		const size_t	dst_capacity,
		const zxc_decompress_opts_t *	opts
	)

Decompresses a single block into an exactly-sized destination.

Same semantics as zxc_decompress_block(), except dst_capacity may equal the uncompressed size, with no ZXC_DECOMPRESS_TAIL_PAD margin. For integrations whose destination cannot be oversized (say, an exactly-sized page-aligned region). "In place" here means a tightly-sized destination, not an overlapping src / dst (see the note below).

Slightly slower than zxc_decompress_block() since it gives up the wild-copy overshoot the fast decoder relies on; output is bit-identical. RAW blocks forward straight to zxc_decompress_block(), only GLO/GHI take the strict-tail path.

Parameters

[in,out]	dctx	Reusable decompression context.
[in]	src	Compressed block.
[in]	src_size	Compressed size in bytes.
[out]	dst	Destination buffer.
[in]	dst_capacity	Capacity of dst: at least the original uncompressed size, at most ZXC_BLOCK_SIZE_MAX (no tail-pad margin needed, unlike zxc_decompress_block).
[in]	opts	Decompression options, or NULL for defaults. Same fields as zxc_decompress_block(); a dictionary routes through its bounce path.

Note

src and dst must not overlap (same contract as memcpy).

Returns

Decompressed size (> 0), or a negative zxc_error_t; ZXC_ERROR_BAD_BLOCK_SIZE if dst_capacity > ZXC_BLOCK_SIZE_MAX. Static context: same bound and codes as zxc_decompress_block(), a larger dst_capacity accepted alike. On error dst holds whatever the decode wrote, all of it on ZXC_ERROR_BAD_CHECKSUM.

Decompresses a single block into an exactly-sized destination.

Static dctx: shared static path. Heap dctx: dict inputs and RAW route to zxc_decompress_block, plain GLO/GHI use the strict decoder (no bounce buffer, no +ZXC_DECOMPRESS_TAIL_PAD).

Public API; full contract in zxc_buffer.h.

Definition at line 1916 of file zxc_dispatch.c.

References zxc_decompress_opts_t::checksum_enabled, zxc_decompress_opts_t::dict, zxc_decompress_opts_t::dict_size, ZXC_BLOCK_HEADER_SIZE, zxc_block_size_ceil(), ZXC_BLOCK_SIZE_MAX, zxc_dctx_prepare(), zxc_decompress_block(), zxc_decompress_chunk_wrapper_safe_public(), ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_NULL_INPUT, ZXC_OK, ZXC_OPTS_DICT_SIZE, and zxc_static_decompress_block().

zxc_estimate_cctx_size()

uint64_t zxc_estimate_cctx_size	(	const size_t	src_size,
		const int	level
	)

Estimates peak compression memory for a given block size and level.

Totals everything zxc_compress_block reserves for a src_size block: per-chunk working buffers (chain table, literals, sequence/token/offset/extras), the fixed hash tables and match-split histograms, and cache-line padding. At level >= 6 it also counts the opt_scratch region: ~8.125 x src_size for the optimal parser. Lazy-allocated on the first level-6 call, then kept for the cctx's lifetime.

Parameters

[in]	src_size	Uncompressed block size in bytes.
[in]	level	Compression level (1..7). Levels <= 5 share the same persistent footprint; levels >= 6 add the optimal-parser scratch.

Returns

Estimated peak cctx memory in bytes, or 0 if src_size is 0.

Estimates peak compression memory for a given block size and level.

Thin wrapper around zxc_cctx_compute_workspace_size for mode == 1 (compress), with src_size clamped up to a valid block size via zxc_block_size_ceil. The opaque wrapper struct allocated by zxc_create_cctx adds a fixed overhead (< 128 B) that is negligible next to the per-chunk buffers and is intentionally omitted.

For level >= 6 the figure includes the optimal-parser scratch (opt_scratch, ~8.125 bytes per chunk_size byte) used by the optimal parser and reused as transient package-merge scratch for the Huffman code-length builder.

Definition at line 1087 of file zxc_common.c.

References zxc_block_size_ceil(), and zxc_cctx_compute_workspace_size().