Static Context API

Caller-allocated, fixed-footprint compression / decompression contexts. More...

Functions
size_t	zxc_static_cctx_workspace_size (const size_t block_size, const int level)
	Exact size of a static compression workspace.
zxc_cctx *	zxc_init_static_cctx (void *workspace, const size_t workspace_size, const zxc_compress_opts_t *opts)
	Initialises a compression context inside a caller-supplied workspace.
size_t	zxc_static_dctx_workspace_size (const size_t block_size)
	Exact size of a static decompression workspace.
zxc_dctx *	zxc_init_static_dctx (void *workspace, const size_t workspace_size, const size_t block_size)
	Initialises a decompression context inside a caller-supplied workspace.

Detailed Description

Caller-allocated, fixed-footprint compression / decompression contexts.

Mirrors the Reusable Context API, but the whole context (handle + persistent buffers) lives in one buffer the caller allocates and owns. Required wherever the library must not touch the host allocator on the hot path: Linux kernel filesystems (one workspace per mount, from vmalloc / kmalloc up front), heapless embedded targets (.bss or stack workspace), sandboxed runtimes on a fixed memory budget.

The trade-off: the workspace is pinned to one block_size and level at init time and cannot grow afterwards, so a workload mixing block sizes must size for the largest one up front.

Typical usage

size_t ws_sz = zxc_static_cctx_workspace_size(64 * 1024, ZXC_LEVEL_DEFAULT);
void *ws = aligned_alloc(64, ws_sz);                   // or kmalloc, vmalloc, .bss
zxc_compress_opts_t opts = { .level = ZXC_LEVEL_DEFAULT, .block_size = 64 * 1024 };
zxc_cctx *cctx = zxc_init_static_cctx(ws, ws_sz, &opts);
 
for (each block) zxc_compress_cctx(cctx, src, n, dst, cap, NULL);
 
// zxc_free_cctx is a no-op on a static cctx; the caller owns @c ws.
free(ws);

Function Documentation

zxc_init_static_cctx()

zxc_cctx * zxc_init_static_cctx	(	void *	workspace,
		const size_t	workspace_size,
		const zxc_compress_opts_t *	opts
	)

Initialises a compression context inside a caller-supplied workspace.

workspace_size must be at least zxc_static_cctx_workspace_size for the same block_size and level. The workspace must be cache-line (64-byte) aligned and must outlive the returned handle. The caller owns it; zxc_free_cctx is a no-op on this handle.

Locked parameters

block_size, level and checksum_enabled are pinned at init time. A later zxc_compress_cctx call asking for a different block_size returns ZXC_ERROR_BAD_BLOCK_SIZE without re-initialising. A different level / checksum_enabled is honoured per call without re-partitioning, except a raise into ZXC_LEVEL_DENSITY on a workspace carved below it: the optimal-parser scratch is absent, so the call returns ZXC_ERROR_BAD_LEVEL. Dictionaries are rejected too: ZXC_ERROR_DICT_UNSUPPORTED.

Parameters

[in,out]	workspace	Caller-allocated buffer, cache-line aligned.
[in]	workspace_size	Capacity of workspace in bytes.
[in]	opts	Must be non-NULL, with block_size and level set explicitly to size the workspace correctly.

Returns

Handle pointing inside workspace, or NULL if the workspace is too small or the options are invalid.

Definition at line 1981 of file zxc_dispatch.c.

References ZXC_BLOCK_SIZE_DEFAULT, zxc_cctx_compute_workspace_size(), zxc_cctx_init_in_workspace(), ZXC_LEVEL_DEFAULT, ZXC_LEVEL_ULTRA, ZXC_OK, and zxc_validate_block_size().

zxc_init_static_dctx()

zxc_dctx * zxc_init_static_dctx	(	void *	workspace,
		const size_t	workspace_size,
		const size_t	block_size
	)

Initialises a decompression context inside a caller-supplied workspace.

workspace_size must be at least zxc_static_dctx_workspace_size for the same block_size. The workspace must be cache-line aligned and must outlive the returned handle. The caller owns it; zxc_free_dctx is a no-op on this handle.

Locked block size

block_size is pinned at init time: an archive whose header declares a different block_size is rejected with ZXC_ERROR_BAD_BLOCK_SIZE; a block larger than it never decodes through the block API (see zxc_decompress_block() for the codes).

No dictionary

Any dictionary is rejected with ZXC_ERROR_DICT_UNSUPPORTED, since the workspace has no room for the prefix.

Parameters

[in,out]	workspace	Caller-allocated buffer, cache-line aligned.
[in]	workspace_size	Capacity of workspace in bytes.
[in]	block_size	Block size the decoder will accept.

Returns

Handle pointing inside workspace, or NULL if the workspace is too small or block_size is invalid.

Definition at line 2028 of file zxc_dispatch.c.

References zxc_cctx_compute_workspace_size(), zxc_cctx_init_in_workspace(), ZXC_OK, and zxc_validate_block_size().

zxc_static_cctx_workspace_size()

size_t zxc_static_cctx_workspace_size	(	const size_t	block_size,
		const int	level
	)

Exact size of a static compression workspace.

Sums the opaque zxc_cctx wrapper and every persistent sub-buffer the library partitions out of it (hash tables, chain table, sequence buffers, literal scratch, plus the optimal-parser scratch at ZXC_LEVEL_DENSITY). The workspace must be at least cache-line aligned, so round up for posix_memalign / aligned_alloc.

Parameters

[in]	block_size	Block size in bytes (power of two in [ZXC_BLOCK_SIZE_MIN, ZXC_BLOCK_SIZE_MAX]).
[in]	level	Compression level (1..7); levels at or above ZXC_LEVEL_DENSITY add the optimal-parser scratch (~8.125 x block_size).

Returns

Workspace size in bytes, or 0 if either argument is invalid.

Exact size of a static compression workspace.

Public API; see zxc_buffer.h. Sum of the cache-line-aligned handle header and the persistent buffer that zxc_init_static_cctx carves for the given block_size / level. Performs no allocation.

Definition at line 1973 of file zxc_dispatch.c.

References zxc_cctx_compute_workspace_size(), ZXC_LEVEL_ULTRA, and zxc_validate_block_size().

zxc_static_dctx_workspace_size()

size_t zxc_static_dctx_workspace_size

(

const size_t

block_size

)

Exact size of a static decompression workspace.

Unlike the compression variant this is independent of the archive's level: lit_buffer is always provisioned worst-case, because the decoder cannot know a block's literal encoding until it reads that block's header.

Parameters

[in]

block_size

Largest block size the decoder will meet (same constraints as everywhere else).

Returns

Workspace size in bytes, or 0 if block_size is invalid.

Exact size of a static decompression workspace.

Public API; see zxc_buffer.h. Sum of the cache-line-aligned handle header and the persistent buffer that zxc_init_static_dctx carves for the given block_size. Performs no allocation.

Definition at line 2021 of file zxc_dispatch.c.

References zxc_cctx_compute_workspace_size(), and zxc_validate_block_size().