Opaque, reusable compression / decompression contexts. More...

Modules
	Static Context API
	Caller-allocated, fixed-footprint compression / decompression contexts.

Functions
zxc_cctx *	zxc_create_cctx (const zxc_compress_opts_t *opts)
	Creates a reusable compression context.

void	zxc_free_cctx (zxc_cctx *cctx)
	Frees a compression context and its resources.

int64_t	zxc_compress_cctx (zxc_cctx cctx, const void src, size_t src_size, void dst, size_t dst_capacity, const zxc_compress_opts_t opts)
	Compresses data using a reusable context.

zxc_dctx *	zxc_create_dctx (void)
	Creates a reusable decompression context.

void	zxc_free_dctx (zxc_dctx *dctx)
	Frees a decompression context and its resources.

int64_t	zxc_decompress_dctx (zxc_dctx dctx, const void src, size_t src_size, void dst, size_t dst_capacity, const zxc_decompress_opts_t opts)
	Decompresses data using a reusable context.

int64_t	zxc_decompress_inplace_dctx (zxc_dctx dctx, void buffer, const size_t buffer_capacity, const size_t comp_size, const zxc_decompress_opts_t *opts)
	In-place decompression with a caller-supplied context.

Detailed Description

Opaque, reusable compression / decompression contexts.

Keeping a context across calls removes the per-call allocation overhead. The internal layout stays hidden behind an opaque pointer.

Function Documentation

◆ zxc_compress_cctx()

int64_t zxc_compress_cctx	(	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 data using a reusable context.

Like zxc_compress(), but reuses cctx's buffers instead of allocating per call. The context re-initialises itself when block_size changes, or when a level raise into ZXC_LEVEL_DENSITY needs the optimal-parser scratch that lower-level inits skip. On a static (caller-workspace) context such a raise returns ZXC_ERROR_BAD_LEVEL instead, since the workspace cannot grow.

Options are sticky: each entry point remembers the options it uses for later calls that pass NULL, starting from zxc_create_cctx(): level, block_size, checksum_enabled and seekable here, the first three for zxc_compress_block(). Levels above ZXC_LEVEL_ULTRA are silently clamped. Dictionary options are the exception: honoured as in zxc_compress() but never remembered, so pass them on every call; the shared table is rebuilt only when it changes. A static context returns ZXC_ERROR_DICT_UNSUPPORTED for any dictionary. seekable appends the seek table as zxc_compress() does, without allocating, static contexts included.

Parameters

[in,out]	cctx	Reusable compression context.
[in]	src	Source data; may be NULL when `src_size` is 0.
[in]	src_size	Source size in bytes; 0 writes the empty archive, as zxc_compress() does, without carving the encoder workspace.
[out]	dst	Destination buffer.
[in]	dst_capacity	Capacity of `dst`.
[in]	opts	Options, or NULL to reuse the sticky settings.

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

Returns: Compressed size (> 0), or a negative zxc_error_t.

Public API; full contract in zxc_buffer.h. Same frame walk and dictionary binding as zxc_compress(), empty source included; buffers re-carved only when [dict | block] or the parser tier changes, shared table rebuilt only when it changes.

Definition at line 1195 of file zxc_dispatch.c.

References zxc_block_header_t::block_type, zxc_compress_opts_t::checksum_enabled, zxc_compress_opts_t::dict, zxc_cctx_t::dict_buffer, zxc_cctx_t::dict_size, zxc_compress_opts_t::seekable, ZXC_BLOCK_CHECKSUM_SIZE, zxc_block_size_ceil(), zxc_cctx_free(), zxc_cctx_init(), zxc_compress_chunk_wrapper(), zxc_ctx_sync_dict_huf(), zxc_dict_id(), ZXC_DICT_SIZE_MAX, zxc_digest_combine(), ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_BAD_LEVEL, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_DICT_UNSUPPORTED, ZXC_ERROR_MEMORY, ZXC_ERROR_NULL_INPUT, zxc_le32(), ZXC_LEVEL_DENSITY, ZXC_OK, ZXC_OPTS_BLOCK_SIZE, ZXC_OPTS_DICT_HUF, ZXC_OPTS_DICT_SIZE, ZXC_OPTS_LEVEL, zxc_validate_block_size(), zxc_write_block_header(), zxc_write_empty_frame(), zxc_write_file_footer(), zxc_write_file_header(), and zxc_write_seek_table_from_blocks().

◆ zxc_create_cctx()

zxc_cctx * zxc_create_cctx ( const zxc_compress_opts_t * opts )

Creates a reusable compression context.

With a non-NULL opts the context pre-allocates its buffers from the given level, block_size and checksum_enabled; with NULL, allocation is deferred to the first zxc_compress_cctx() call. Levels above ZXC_LEVEL_ULTRA are silently clamped. Free with zxc_free_cctx().

Parameters

[in] opts Options for eager init, or NULL for lazy init.

Returns: New context, or NULL on allocation failure or an invalid block size (not a power of two in range).

Definition at line 1145 of file zxc_dispatch.c.

References zxc_compress_opts_t::checksum_enabled, zxc_compress_opts_t::seekable, ZXC_BLOCK_SIZE_DEFAULT, ZXC_CALLOC, zxc_cctx_init(), ZXC_FREE, ZXC_LEVEL_DEFAULT, ZXC_OK, ZXC_OPTS_BLOCK_SIZE, ZXC_OPTS_LEVEL, and zxc_validate_block_size().

Referenced by zxc_cstream_create().

◆ zxc_create_dctx()

zxc_dctx * zxc_create_dctx ( void )

Creates a reusable decompression context.

Only the handle is allocated here: the working buffers are sized from the archive header, so they come on the first decode. Free with zxc_free_dctx().

Returns: New context, or NULL on allocation failure.

Definition at line 1349 of file zxc_dispatch.c.

References ZXC_CALLOC.

Referenced by zxc_decompress_inplace().

◆ zxc_decompress_dctx()

int64_t zxc_decompress_dctx	(	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 data using a reusable context.

Like zxc_decompress(), dictionary options included, but reuses dctx's buffers; the shared literal table is rebuilt only when it changes between calls. A static context returns ZXC_ERROR_DICT_UNSUPPORTED for any dictionary.

Asking without a destination: Same probe as zxc_decompress(), answered under this context's rules: a static context still rejects a foreign block size and a dictionary-bound archive.

Error codes changed after v0.14.0: They now match zxc_decompress() exactly. A truncated input reports ZXC_ERROR_SRC_TOO_SMALL and a malformed header reports what the header parse found (ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_BAD_VERSION, ZXC_ERROR_BAD_BLOCK_SIZE), where both used to flatten to ZXC_ERROR_NULL_INPUT or ZXC_ERROR_BAD_HEADER.

Parameters

[in,out]	dctx	Reusable decompression context.
[in]	src	Compressed data.
[in]	src_size	Compressed size in bytes.
[out]	dst	Destination buffer, or NULL to probe (see above).
[in]	dst_capacity	Capacity of `dst`.
[in]	opts	Decompression options, or NULL for defaults.

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

Returns: Decompressed size, 0 for an empty archive, or a negative zxc_error_t.

Decompresses data using a reusable context.

Public API; full contract in zxc_buffer.h. Same frame walk and dictionary binding as zxc_decompress(); the inner buffers are re-carved only when the block or dictionary size changes, the shared table only when it changes.

Definition at line 1397 of file zxc_dispatch.c.

References zxc_dctx_decode_container(), zxc_dctx_probe(), ZXC_DICT_SIZE_MAX, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_NULL_INPUT, ZXC_FRAME_MIN_SIZE, ZXC_OPTS_DICT_SIZE, and zxc_short_input_verdict().

◆ zxc_decompress_inplace_dctx()

int64_t zxc_decompress_inplace_dctx	(	zxc_dctx *	dctx,
		void *	buffer,
		const size_t	buffer_capacity,
		const size_t	comp_size,
		const zxc_decompress_opts_t *	opts
	)

In-place decompression with a caller-supplied context.

Same contract and error codes as zxc_decompress_inplace(), with dctx as the decode context. With a static context (zxc_init_static_dctx()) the call allocates nothing.

A static context rejects a foreign block size (ZXC_ERROR_BAD_BLOCK_SIZE) and any dictionary (ZXC_ERROR_DICT_UNSUPPORTED).

static uint8_t ws[...] __attribute__((aligned(64)));  // zxc_static_dctx_workspace_size(bs)
zxc_dctx* d = zxc_init_static_dctx(ws, sizeof(ws), bs);
// buf: zxc_decompress_inplace_bound() bytes, archive flush-right
int64_t n = zxc_decompress_inplace_dctx(d, buf, cap, archive_size, NULL);

Parameters

[in,out]	dctx	Decompression context (static or heap).
[in,out]	buffer	Work buffer holding the flush-right archive.
[in]	buffer_capacity	Total size of `buffer` in bytes.
[in]	comp_size	Size of the compressed archive in bytes.
[in]	opts	Decompression options, or NULL for defaults.

Returns: Decompressed size (> 0), 0 for an empty frame, or a negative zxc_error_t.

In-place decompression with a caller-supplied context.

Public API; full contract in zxc_buffer.h. The archive sits flush-right, at buffer + buffer_capacity - comp_size, and decodes left-to-right into buffer[0..]. Dictionary archives decode through the context's own bounce buffer, which does not alias buffer.

Definition at line 1417 of file zxc_dispatch.c.

References zxc_dctx_decode_frame(), ZXC_ERROR_NULL_INPUT, zxc_inplace_prepare(), and ZXC_OK.

◆ zxc_free_cctx()

void zxc_free_cctx ( zxc_cctx * cctx )

Frees a compression context and its resources.

NULL is a no-op.

Parameters

[in] cctx Context to free.

Frees a compression context and its resources.

Public API; see zxc_buffer.h. Frees the inner buffers and the handle. NULL-safe. For a static (caller-workspace) context this is a no-op, since the caller owns the workspace.

Definition at line 1178 of file zxc_dispatch.c.

References zxc_cctx_free(), and ZXC_FREE.

Referenced by zxc_cstream_create(), and zxc_cstream_free().