Platform abstractions, constants, and utility functions (private). More...

Data Structures
struct	zxc_pivco_tree_t
	A PivCo code tree: its canonical shape, by depth. More...

struct	zxc_dict_huf_state_t
	Frame-constant dictionary Huffman state, prebuilt once at attach. More...

Macros
#define	ZXC_HUF_MIN_LITERALS 139
	Absolute floor (in literals) below which a Huffman candidate is never evaluated.

Aligned Allocator Abstraction
Macros around the cache-line-aligned allocator used for compression workspace and per-context scratch buffers. The default is the pair defined below, wrapping `_aligned_malloc` on Windows and `posix_memalign` elsewhere - the core's only use of either. A host overrides both macros or neither; a vendored copy of this file defines both. Kernel builds align by hand over the slab allocator (see contrib/linux-kernel): `kmalloc` guarantees only `ARCH_KMALLOC_MINALIGN`, 8 bytes on x86 and on arm64 since 6.5, short of the cache line the workspace layout assumes.
static void *	zxc_aligned_malloc (const size_t size, const size_t alignment)
	Default cache-line-aligned allocator; release with zxc_aligned_free.

static void	zxc_aligned_free (void *ptr)
	Counterpart of zxc_aligned_malloc; NULL is a no-op.

#define	ZXC_ALIGNED_MALLOC(size, alignment) zxc_aligned_malloc(size, alignment)
	Cache-line-aligned allocator.

#define	ZXC_ALIGNED_FREE(ptr) zxc_aligned_free(ptr)
	Counterpart deallocator for ZXC_ALIGNED_MALLOC.

Population Count
`ZXC_POPCOUNT32` / `ZXC_POPCOUNT64`. Default: the builtins, libgcc calls without a hardware count; a kernel maps them onto `hweight32/64`.
static int	zxc_popcount32 (const uint32_t v)
	Portable SWAR popcount (MSVC).

static int	zxc_popcount64 (const uint64_t v)

#define	ZXC_POPCOUNT32(v) zxc_popcount32(v)

#define	ZXC_POPCOUNT64(v) zxc_popcount64(v)

File Format Constants
Header fields, block sizes, and related constants. The magic words are public, in zxc_constants.h.
static int	zxc_magic_prefix_ok (const uint8_t *p, const size_t n)
	Whether the first `n` bytes (up to 4) at `p` agree with the magic word, so a frame may start there: the check a reader makes as bytes arrive.

#define	ZXC_FILE_FORMAT_VERSION 9
	Current on-disk file format version.

#define	ZXC_PAD_SIZE 32
	Safety padding appended to buffers to tolerate overruns.

#define	ZXC_BLOCK_LIT_SLACK 32
	Readable bytes a GLO/GHI payload guarantees after its literal section.

#define	ZXC_DECOMPRESS_TAIL_PAD (ZXC_PAD_SIZE * 66)
	Tail padding required on the decompression destination buffer.

#define	ZXC_CACHE_LINE_SIZE 64
	Assumed CPU cache line size for alignment.

#define	ZXC_ALIGNMENT_MASK ((size_t)ZXC_CACHE_LINE_SIZE - 1)
	Bitmask for cache-line alignment checks.

#define	ZXC_ALIGN_CL(x) (((x) + ZXC_ALIGNMENT_MASK) & ~(size_t)ZXC_ALIGNMENT_MASK)
	Round `x` up to the next cache-line boundary.

#define	ZXC_BITMAP_WORDS(n_bits) (((n_bits) + 63) / 64)
	Number of `uint64_t` words needed to hold a bitmap of `n_bits`.

#define	ZXC_FILE_FLAG_HAS_CHECKSUM 0x80U
	Bit flag in the Flags byte indicating checksum presence (bit 7).

#define	ZXC_FILE_FLAG_HAS_DICTIONARY 0x40U
	Bit flag in the Flags byte indicating a dictionary is required (bit 6).

#define	ZXC_FILE_FLAG_HAS_SEEK_TABLE 0x20U
	Bit flag in the Flags byte: a SEK block sits between the EOF block and the footer (bit 5).

#define	ZXC_FILE_CHECKSUM_ALGO_MASK 0x0FU
	Mask for the checksum algorithm id (bits 0-3).

#define	ZXC_DICT_VERSION 2
	Current dictionary file format version.

#define	ZXC_DICT_KGRAM_LEN ZXC_LZ_MIN_MATCH_LEN
	K-gram length scanned by the dictionary trainer.

#define	ZXC_DICT_HASH_BITS 16
	Address bits for the dictionary trainer's k-gram frequency table.

#define	ZXC_DICT_MAX_SEGMENTS (1U << 16)
	Maximum number of candidate segments the dictionary trainer keeps.

#define	ZXC_DICT_SAMPLE_TARGET (1U << 19)
	Target number of sampled k-gram positions for the trainer's frequency estimate.

#define	ZXC_DICT_HASH_SIZE (1U << ZXC_DICT_HASH_BITS)
	Number of buckets in the dictionary trainer's frequency table.

#define	ZXC_DICT_HUF_TRAIN_BLOCK 4096U
	Training block size for the shared-table literal statistics.

#define	ZXC_DICT_HUF_SAMPLE_BUDGET (8U << 20)
	Cap on the corpus bytes compressed by the literal-table trainer: the histogram converges early, so past it slices are strided evenly instead.

#define	ZXC_BLOCK_HEADER_SIZE 8
	Block header size: Type(1)+Flags(1)+Reserved(1)+Checksum(1)+CompSize(4).

#define	ZXC_BLOCK_CHECKSUM_SIZE 4
	Size of the per-block checksum field in bytes.

#define	ZXC_GLO_HEADER_BINARY_SIZE 12
	Binary size of a GLO block sub-header.

#define	ZXC_GHI_HEADER_BINARY_SIZE 12
	Binary size of a GHI block sub-header.

#define	ZXC_GLO_DESC_MAX_SIZE (2 * sizeof(uint32_t))
	Widest GLO section descriptors: the literal and token section sizes.

#define	ZXC_BLOCK_FORMAT_OVERHEAD 68
	Worst-case format overhead inside a single block beyond the outer 8-byte block header and the optional 4-byte checksum.

#define	ZXC_CHECKSUM_RAPIDHASH 0
	Checksum algorithm id for RapidHash (default, sole implementation).

Seekable Format Constants
Seek table block appended between EOF block and footer. Optional: a `ZXC_BLOCK_SEK` block of groups, each a u64 anchor (its first block's offset) then one u32 on-disk size per block. Readers derive the block count from the footer and read groups on access; the header's size field holds the table size modulo 2^32.
static uint64_t	zxc_seek_group_count (const uint64_t nblocks)
	Groups holding `nblocks` blocks; the last one may be partial.

static uint32_t	zxc_seek_group_len (const uint64_t nblocks, const uint64_t g)
	Blocks in group `g` of `nblocks:` ZXC_SEEK_GROUP, fewer for the last.

static uint64_t	zxc_seek_table_bytes (const uint64_t nblocks)
	Byte size of the groups for `nblocks` blocks, in 64 bits.

static uint32_t	zxc_seek_size_field (const uint64_t table_bytes)
	SEK header size field: `table_bytes` with its high half folded onto the low one.

#define	ZXC_SEEK_GROUP 64U
	Blocks per group.

#define	ZXC_SEEK_ANCHOR_SIZE 8U
	Group anchor: offset of its first block, u64.

#define	ZXC_SEEK_SIZE_ENTRY 4U
	One block's on-disk size, u32.

#define	ZXC_SEEK_GROUP_BYTES (ZXC_SEEK_ANCHOR_SIZE + ZXC_SEEK_GROUP * ZXC_SEEK_SIZE_ENTRY)
	Full group: anchor + ZXC_SEEK_GROUP sizes.

LZ77 Constants
Hash table geometry, sliding window, and match parameters. The hash table uses a split layout with 15-bit addressing (32 768 buckets): `hash_table[]`: uint32_t, stores `(epoch << offset_bits) \| position` (128 KB). `hash_tags[]`: uint8_t, stores an 8-bit tag for fast rejection (32 KB). Total: 160 KB. The tag table fits in L1 cache, enabling a "filter-first" access pattern that avoids cold loads into hash_table on the ~60-75% of lookups where the tag mismatches. The 64 KB sliding window allows `chain_table` to use `uint16_t`.
static uint32_t	zxc_read_varint (const uint8_t *ptr, const uint8_t end)
	Reads a Prefix Varint encoded integer.

#define	ZXC_LZ_HASH_BITS 15
	Address bits for the LZ77 hash table (2^15 = 32 768 buckets).

#define	ZXC_LZ_HASH_SIZE (1U << ZXC_LZ_HASH_BITS)
	Maximum number of entries in the hash table.

#define	ZXC_LZ_WINDOW_SIZE (1U << 16)
	Sliding window size (64 KB).

#define	ZXC_LZ_WINDOW_MASK (ZXC_LZ_WINDOW_SIZE - 1U)
	Mask for ring-buffer indexing into chain_table (power-of-two window).

#define	ZXC_LZ_MIN_MATCH_LEN 5
	Minimum match length for an LZ77 match.

#define	ZXC_MAX_VARINT_VALUE ((uint32_t)(ZXC_BLOCK_SIZE_MAX - 1U))
	Maximum legitimate value a varint can decode to.

#define	ZXC_GLO_MAX_INLINE_OUT_PER_SEQ ((ZXC_TOKEN_LL_MASK - 1U) + ZXC_GLO_MAX_INLINE_ML) /* 33 */
	Maximum decoded output of one sequence with inline ll/ml, used by the 4x bounds checks to reserve the rest of a batch.

#define	ZXC_GLO_INLINE_ML_CODE (ZXC_TOKEN_ML_MASK - 1U) /* 14 */
	Longest match length code (length minus ZXC_LZ_MIN_MATCH_LEN) a GLO token carries inline; the code above it escapes to a varint.

#define	ZXC_GLO_MAX_INLINE_ML (ZXC_GLO_INLINE_ML_CODE + ZXC_LZ_MIN_MATCH_LEN) /* 19 */
	Longest match a GLO sequence carries without a varint extension.

#define	ZXC_GHI_MAX_INLINE_OUT_PER_SEQ ((ZXC_SEQ_LL_MASK - 1U) + (ZXC_SEQ_ML_MASK - 1U) + ZXC_LZ_MIN_MATCH_LEN) /* 513 */

#define	ZXC_LZ_OFFSET_BIAS 1
	Base bias added to encoded offsets (stored = actual - bias).

#define	ZXC_LZ_MAX_DIST (ZXC_LZ_WINDOW_SIZE - 1)
	Maximum allowed offset distance.

#define	ZXC_LZ_MINDIST 32
	Match distance floor the encoder holds to at levels 1 to 5, sized to the decoder's widest match-copy arm so the overlap kernel stays off the decode path.

#define	ZXC_LZ_MINDIST_PROBE_PER_KB 1024
	Probe sampling: one position per KB, clamped.

#define	ZXC_LZ_MINDIST_PROBE_MIN 16

#define	ZXC_LZ_MINDIST_PROBE_MAX 64

#define	ZXC_LZ_MINDIST_MAX_SHORT_PCT 20
	Short-distance hit rate, in percent, above which a block keeps its short match distances.

#define	ZXC_LZ_SEARCH_MARGIN (sizeof(uint64_t))
	Bytes at the block end where match search stops (left as literals).

Space-speed section selection
Section encodings are selected at EVERY level by pricing each candidate with a Lagrangian cost `J = compressed_size + decode_tax` and taking the minimum (Kraken-style `J = R + lambdaD` with a linear per-byte decode-time model). The tax charges the DECODE time a candidate adds over the RAW copy path, expressed in bytes: `tax = (n_decoded_bytes PREM) >> 8`. Only the premium is per-level: Below DENSITY, the premiums reproduce the historical fixed margins EXACTLY (8 = 3.125% = the old `>> 5` margins), keeping the sub-DENSITY levels (1-5) output byte-stable. At DENSITY and above the physical premiums apply: `PREM_HUF = 4` (1.56% – the entropy decoder costs ~0.5 ns/B over a raw copy, so ~1 byte of size buys ~30 ns of decode; validated on silesia: ~0.8 pt of ratio for ~3% decode vs the legacy margin) and `PREM_RLE = 1` (0.39%: RLE decodes at near copy speed, only a token tax to break ties toward RAW).
static int	zxc_ss_prem_rle_q8 (const int level)
	Per-level RLE-vs-RAW decode premium (Q8) for the space-speed selector.

static int	zxc_ss_prem_huf_q8 (const int level)
	Per-level Huffman/PivCo-vs-RAW decode premium (Q8) for the space-speed selector.

#define	ZXC_SS_TAX(n, prem_q8) (((size_t)(n) * (size_t)(prem_q8)) >> 8)
	Decode tax of a candidate: `n` decoded bytes at premium `prem` (Q8).

Heap Allocator Abstraction
Macros around the libc allocators so non-libc targets (Linux kernel, embedded freestanding builds, custom arenas) can override them via `-D` flags before including any zxc header, or by vendoring this file. Note Aligned allocations go through ZXC_ALIGNED_MALLOC / ZXC_ALIGNED_FREE (see below), not these.
#define	ZXC_MALLOC(size) malloc(size)
	Heap allocator.

#define	ZXC_CALLOC(nmemb, size) calloc(nmemb, size)
	Zero-initialised heap allocator.

#define	ZXC_REALLOC(ptr, size) realloc(ptr, size)
	In-place / move heap reallocator.

#define	ZXC_FREE(ptr) free(ptr)
	Heap deallocator.

Atomic Qualifier
Provides a portable atomic / volatile qualifier. `ZXC_ATOMIC` expands to `_Atomic`, or to `volatile` where the compiler leaves out the optional C11 atomics (`__STDC_NO_ATOMICS__`, as MSVC does).
#define	ZXC_ATOMIC _Atomic

#define	ZXC_USE_C11_ATOMICS 1

Compiler Abstractions
Portable wrappers for branch hints, prefetch, memory ops, alignment, and forced inlining.
#define	LIKELY(x) (x)

#define	UNLIKELY(x) (x)

#define	RESTRICT

#define	ZXC_PREFETCH_READ(ptr)

#define	ZXC_MEMCPY(dst, src, n) memcpy(dst, src, n)

#define	ZXC_MEMSET(dst, val, n) memset(dst, val, n)

#define	ZXC_ALWAYS_INLINE inline
	Forces a function to be inlined (fallback for non-GCC/Clang/MSVC compilers).

#define	ZXC_NOINLINE
	Prevents inlining (best-effort no-op fallback for unknown compilers).

#define	ZXC_COLD

#define	ZXC_ALIGN(x) _Alignas(x)
	Specifies memory alignment using C11 _Alignas.

GLO Token Constants
4-bit literal length / 4-bit match length / 16-bit offset.
#define	ZXC_TOKEN_LIT_BITS 4
	Bits for Literal Length in a GLO token.

#define	ZXC_TOKEN_ML_BITS 4
	Bits for Match Length in a GLO token.

#define	ZXC_TOKEN_LL_MASK ((1U << ZXC_TOKEN_LIT_BITS) - 1)
	Mask to extract Literal Length from a GLO token.

#define	ZXC_TOKEN_ML_MASK ((1U << ZXC_TOKEN_ML_BITS) - 1)
	Mask to extract Match Length from a GLO token.

GHI Sequence Constants
8-bit literal length / 8-bit match length / 16-bit offset.
#define	ZXC_SEQ_LL_BITS 8
	Bits for Literal Length in a GHI sequence.

#define	ZXC_SEQ_ML_BITS 8
	Bits for Match Length in a GHI sequence.

#define	ZXC_SEQ_OFF_BITS 16
	Bits for Offset in a GHI sequence.

#define	ZXC_SEQ_LL_MASK ((1U << ZXC_SEQ_LL_BITS) - 1)
	Mask to extract Literal Length from a GHI sequence.

#define	ZXC_SEQ_ML_MASK ((1U << ZXC_SEQ_ML_BITS) - 1)
	Mask to extract Match Length from a GHI sequence.

#define	ZXC_SEQ_OFF_MASK ((1U << ZXC_SEQ_OFF_BITS) - 1)
	Mask to extract Offset from a GHI sequence.

Literal Stream Encoding
#define	ZXC_LIT_RLE_FLAG 0x80U
	Flag bit indicating an RLE run in the literal stream (0x80).

#define	ZXC_LIT_LEN_MASK (ZXC_LIT_RLE_FLAG - 1)
	Mask to extract the run/literal length (lower 7 bits).

Optimal Parser Tuning (level >= 6)
Static prices and complexity guards used by the level-6 optimal LZ77 parser DP.
#define	ZXC_OPT_MATCH_COST_BASE ((uint32_t)(3U * CHAR_BIT))
	Static price (bits) of a match token before varint extras: 1 byte token + 2 byte offset.

#define	ZXC_OPT_LONG_MATCH_SKIP ((size_t)256)
	Threshold above which `find_best_match` is skipped at intra-match positions, keeping the parser O(N) on highly repetitive data.

#define	ZXC_OPT_LIT_SAMPLE_MIN 1024
	Minimum literal count for the sample-based Huffman cost estimator used by the optimal parser.

Hash multipliers
Odd constants that mix bits in the LZ match hash, the header checksums (Sec 7.1) and the archive digest (Sec 7.3). The header-hash and digest values are fixed by the on-disk format; changing them is a version bump.
#define	ZXC_HASH_GOLDEN64 0x9E3779B97F4A7C15ULL
	Golden-ratio prime: header hashes and the digest spread.

#define	ZXC_HASH_XORSHIFT64 0x2545F4914F6CDD1DULL
	Vigna's xorshift* multiplier: the 5-byte LZ hash and the digest fold.

#define	ZXC_HASH_MULT32 0x2D35182DU
	Marsaglia 32-bit multiplier: the 4-byte LZ and dictionary hash.

#define	ZXC_HASH_MULT64 0xD2D84A61D2D84A61ULL
	Second multiplier of the 16-byte header hash (zxc_hash16).

Huffman Codec Constants
Length-limited canonical Huffman codec for GLO literal sections (level >= 6) and level-7 token sections, in the PivCo layout. On-disk section payload layout (FORMAT.md section 5.2.1): `ZXC_HUF_TABLE_SIZE` bytes: `ZXC_HUF_NUM_SYMBOLS` code lengths packed two per byte (4 bits each). The same packed table is used as the per-block lengths header (enc_lit=2) and as the shared table carried by a .zxd dictionary (enc_lit=3, header omitted) – hence the public constant. Node runs: for every emitting node of the canonical code tree in BFS order, its branch bits (or packed D-bit residuals for flat subtree roots), LSB-first, each run padded to a byte boundary. All run sizes are derived (root count + popcounts), never stored.
#define	ZXC_HUF_MAX_CODE_LEN_ULTRA 11
	Maximum Huffman code length, in bits: the ceiling the decoder's on-wire validation accepts (and the level-7 encoder cap).

#define	ZXC_HUF_MAX_CODE_LEN_DENSITY 8
	Encoder code-length cap for levels up to ZXC_LEVEL_DENSITY (below ZXC_LEVEL_ULTRA): shallow 8-bit trees decode fastest (fewer merge levels, denser flat subtrees) – this cap is the de-facto speed governor of level 6.

#define	ZXC_HUF_NUM_SYMBOLS 256
	Alphabet size: one entry per possible byte value.

#define	ZXC_PIVCO_MAX_NODES (2 * ZXC_HUF_NUM_SYMBOLS - 1)
	Upper bound on PivCo tree nodes (full binary tree over the alphabet).

#define	ZXC_PIVCO_NODE_SLOTS (ZXC_PIVCO_MAX_NODES + 1)
	Node-indexed array size: every node, plus a slot for the lone-symbol root's missing child.

#define	ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX 6
	Deepest flat subtree zxc_pivco_unpack_flat unpacks with a SIMD kernel (its D == 2..6 cases); deeper flat roots take the scalar bit-reader.

#define	ZXC_PIVCO_COVERED 0xFFU
	`flat_d` of a node inside a flat root: no run, no children.

#define	ZXC_RLE_MARGIN_SHIFT 5
	RLE margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_rle_q8 (256 >> shift reproduces the historical RLE-vs-RAW margin exactly).

#define	ZXC_HUF_MARGIN_SHIFT 5
	Huffman margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_huf_q8 (the frozen ZXC_HUF_MIN_LITERALS floor was also historically derived from it).

Encoder-side joint flat/length nudge (PivCo decode-speed shaping)
Package-merge minimizes section bits alone, but the PivCo decoder's cost also depends on the SHAPE of the code-length histogram: the reconstruction pass loop runs `max_depth + 1` times, and every maximal complete subtree (all leaves exactly D levels below its root) collapses D merge levels into a single unpack. zxc_huf_nudge_code_lengths reshapes freshly built lengths toward power-of-two class counts and shallower caps, adopting a candidate only when its modeled decode win clears the guard below at a bounded ratio cost. Wire-compatible by construction: adjusted lengths stay canonical, Kraft-exact and within the level cap. Idea from pivco-huffman issue #20 (dougallj).
#define	ZXC_HUF_NUDGE_LAMBDA_Q8 26
	Exchange rate (Q8 bits per modeled level-touch) in the candidate cost `J = 256bits + lambdatouches`; 26 ~= 0.10 bit per touch.

#define	ZXC_HUF_NUDGE_BITS_PERMIL 1015
	Adoption guard, ratio side (permil): adopt only while ‘bits’ * 1000 <= bits0 * ZXC_HUF_NUDGE_BITS_PERMIL` (<= +1.5%).

#define	ZXC_HUF_NUDGE_MERGE_Q8 230
	Adoption guard, speed side (Q8): adopt only while ‘touches’ * 256 <= touches0 * ZXC_HUF_NUDGE_MERGE_Q8` (<= ~0.90x).

#define	ZXC_HUF_NUDGE_DEEP_FLAT_PENALTY 24
	Extra level-touches charged per occurrence under a flat root deeper than ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX (scalar bit-reader unpack path).

#define	ZXC_HUF_NUDGE_LEVEL_COST 64
	Fixed per-pass overhead (occurrence-equivalents) charged per merge level, modeling the pass-loop and node-dispatch cost so shallower trees also win on small sections.

Detailed Description

Platform abstractions, constants, and utility functions (private).

Macro Definition Documentation

◆ LIKELY

#define LIKELY ( x ) (x)

Definition at line 235 of file zxc_internal.h.

◆ RESTRICT

#define RESTRICT

Definition at line 237 of file zxc_internal.h.

◆ UNLIKELY

#define UNLIKELY ( x ) (x)

Definition at line 236 of file zxc_internal.h.

◆ ZXC_ALIGN

#define ZXC_ALIGN ( x ) _Alignas(x)

Specifies memory alignment using C11 _Alignas.

Parameters

x	Alignment boundary in bytes (must be a power of 2).

Definition at line 257 of file zxc_internal.h.

◆ ZXC_ALIGN_CL

#define ZXC_ALIGN_CL ( x ) (((x) + ZXC_ALIGNMENT_MASK) & ~(size_t)ZXC_ALIGNMENT_MASK)

Round x up to the next cache-line boundary.

Definition at line 363 of file zxc_internal.h.

◆ ZXC_ALIGNED_FREE

#define ZXC_ALIGNED_FREE ( ptr ) zxc_aligned_free(ptr)

Counterpart deallocator for ZXC_ALIGNED_MALLOC.

Definition at line 137 of file zxc_deps.h.

◆ ZXC_ALIGNED_MALLOC

#define ZXC_ALIGNED_MALLOC	(	size,
		alignment
	)	zxc_aligned_malloc(size, alignment)

Cache-line-aligned allocator.

Definition at line 134 of file zxc_deps.h.

◆ ZXC_ALIGNMENT_MASK

#define ZXC_ALIGNMENT_MASK ((size_t)ZXC_CACHE_LINE_SIZE - 1)

Bitmask for cache-line alignment checks.

Definition at line 361 of file zxc_internal.h.

◆ ZXC_ALWAYS_INLINE

#define ZXC_ALWAYS_INLINE inline

Forces a function to be inlined (fallback for non-GCC/Clang/MSVC compilers).

Definition at line 245 of file zxc_internal.h.

◆ ZXC_ATOMIC

#define ZXC_ATOMIC _Atomic

Definition at line 63 of file zxc_internal.h.

◆ ZXC_BITMAP_WORDS

#define ZXC_BITMAP_WORDS ( n_bits ) (((n_bits) + 63) / 64)

Number of uint64_t words needed to hold a bitmap of n_bits.

Equivalent to ceil(n_bits / 64).

Definition at line 372 of file zxc_internal.h.

◆ ZXC_BLOCK_CHECKSUM_SIZE

#define ZXC_BLOCK_CHECKSUM_SIZE 4

Size of the per-block checksum field in bytes.

Definition at line 416 of file zxc_internal.h.

◆ ZXC_BLOCK_FORMAT_OVERHEAD

#define ZXC_BLOCK_FORMAT_OVERHEAD 68

Worst-case format overhead inside a single block beyond the outer 8-byte block header and the optional 4-byte checksum.

Sub-header (12 B) + widest GLO section descriptors (ZXC_GLO_DESC_MAX_SIZE, 8 B) + widest slack padding (ZXC_BLOCK_LIT_SLACK) = 52 B, plus the customary 16 B of margin for future format evolution. Used by zxc_compress_block_bound() and zxc_compress_bound().

Definition at line 432 of file zxc_internal.h.

◆ ZXC_BLOCK_HEADER_SIZE

#define ZXC_BLOCK_HEADER_SIZE 8

Block header size: Type(1)+Flags(1)+Reserved(1)+Checksum(1)+CompSize(4).

Definition at line 414 of file zxc_internal.h.

◆ ZXC_BLOCK_LIT_SLACK

#define ZXC_BLOCK_LIT_SLACK 32

Readable bytes a GLO/GHI payload guarantees after its literal section.

A wire guarantee, not a buffer allowance - hence separate from ZXC_PAD_SIZE even though the values match. RAW literals point into the caller's buffer and zxc_decode_copy_literals overshoots by up to 31 B, so it needs readable bytes behind it.

The following sections usually supply them for free (tokens + offsets clear 32 B from 16 sequences on); the encoder pads only the shortfall, inside the extras section. Extras are read on demand, so an over-long end pointer is harmless - no wire field, nothing to validate about the padding.

Definition at line 345 of file zxc_internal.h.

◆ ZXC_CACHE_LINE_SIZE

#define ZXC_CACHE_LINE_SIZE 64

Assumed CPU cache line size for alignment.

Definition at line 359 of file zxc_internal.h.

◆ ZXC_CALLOC

#define ZXC_CALLOC	(	nmemb,
		size
	)	calloc(nmemb, size)

Zero-initialised heap allocator.

Default: libc calloc.

Definition at line 74 of file zxc_deps.h.

◆ ZXC_CHECKSUM_RAPIDHASH

#define ZXC_CHECKSUM_RAPIDHASH 0

Checksum algorithm id for RapidHash (default, sole implementation).

Definition at line 438 of file zxc_internal.h.

◆ ZXC_COLD

#define ZXC_COLD

Definition at line 251 of file zxc_internal.h.

◆ ZXC_DECOMPRESS_TAIL_PAD

#define ZXC_DECOMPRESS_TAIL_PAD (ZXC_PAD_SIZE * 66)

Tail padding required on the decompression destination buffer.

The decoder's fast path uses speculative wild-copy writes and gates fast-loop entry on d_end - ZXC_DECOMPRESS_TAIL_PAD. Sizing dst_capacity to uncompressed_size + ZXC_DECOMPRESS_TAIL_PAD guarantees the fast path is reachable and that tail bounds checks never spuriously reject the last literals of a valid block.

See also: zxc_decompress_block_bound()

Definition at line 357 of file zxc_internal.h.

◆ ZXC_DICT_HASH_BITS

#define ZXC_DICT_HASH_BITS 16

Address bits for the dictionary trainer's k-gram frequency table.

Definition at line 398 of file zxc_internal.h.

◆ ZXC_DICT_HASH_SIZE

#define ZXC_DICT_HASH_SIZE (1U << ZXC_DICT_HASH_BITS)

Number of buckets in the dictionary trainer's frequency table.

Definition at line 406 of file zxc_internal.h.

◆ ZXC_DICT_HUF_SAMPLE_BUDGET

#define ZXC_DICT_HUF_SAMPLE_BUDGET (8U << 20)

Cap on the corpus bytes compressed by the literal-table trainer: the histogram converges early, so past it slices are strided evenly instead.

Definition at line 411 of file zxc_internal.h.

◆ ZXC_DICT_HUF_TRAIN_BLOCK

#define ZXC_DICT_HUF_TRAIN_BLOCK 4096U

Training block size for the shared-table literal statistics.

Definition at line 408 of file zxc_internal.h.

◆ ZXC_DICT_KGRAM_LEN

#define ZXC_DICT_KGRAM_LEN ZXC_LZ_MIN_MATCH_LEN

K-gram length scanned by the dictionary trainer.

Aligned on the LZ minimum match length so trained patterns are matchable at encode time.

Definition at line 396 of file zxc_internal.h.

◆ ZXC_DICT_MAX_SEGMENTS

#define ZXC_DICT_MAX_SEGMENTS (1U << 16)

Maximum number of candidate segments the dictionary trainer keeps.

Definition at line 400 of file zxc_internal.h.

◆ ZXC_DICT_SAMPLE_TARGET

#define ZXC_DICT_SAMPLE_TARGET (1U << 19)

Target number of sampled k-gram positions for the trainer's frequency estimate.

Bounds the count so 16-bit counters stay unsaturated on large corpora; the trainer strides the corpus to hit roughly this many positions.

Definition at line 404 of file zxc_internal.h.

◆ ZXC_DICT_VERSION

#define ZXC_DICT_VERSION 2

Current dictionary file format version.

A 128-byte packed Huffman code-lengths table (shared literal table) always follows the dictionary content. Version 2 re-signs the header with the multiplicative hash of FORMAT.md section 7.1, so version 1 fails on the version byte instead of on an unmatchable checksum.

Definition at line 393 of file zxc_internal.h.

◆ ZXC_FILE_CHECKSUM_ALGO_MASK

#define ZXC_FILE_CHECKSUM_ALGO_MASK 0x0FU

Mask for the checksum algorithm id (bits 0-3).

Definition at line 382 of file zxc_internal.h.

◆ ZXC_FILE_FLAG_HAS_CHECKSUM

#define ZXC_FILE_FLAG_HAS_CHECKSUM 0x80U

Bit flag in the Flags byte indicating checksum presence (bit 7).

Definition at line 375 of file zxc_internal.h.

◆ ZXC_FILE_FLAG_HAS_DICTIONARY

#define ZXC_FILE_FLAG_HAS_DICTIONARY 0x40U

Bit flag in the Flags byte indicating a dictionary is required (bit 6).

Definition at line 377 of file zxc_internal.h.

◆ ZXC_FILE_FLAG_HAS_SEEK_TABLE

#define ZXC_FILE_FLAG_HAS_SEEK_TABLE 0x20U

Bit flag in the Flags byte: a SEK block sits between the EOF block and the footer (bit 5).

Definition at line 380 of file zxc_internal.h.

◆ ZXC_FILE_FORMAT_VERSION

#define ZXC_FILE_FORMAT_VERSION 9

Current on-disk file format version.

The decoder accepts only this version; Older versions are rejected with ZXC_ERROR_BAD_VERSION.

Definition at line 328 of file zxc_internal.h.

◆ ZXC_FREE

#define ZXC_FREE ( ptr ) free(ptr)

Heap deallocator.

Default: libc free.

Definition at line 86 of file zxc_deps.h.

◆ ZXC_GHI_HEADER_BINARY_SIZE

#define ZXC_GHI_HEADER_BINARY_SIZE 12

Binary size of a GHI block sub-header.

Definition at line 420 of file zxc_internal.h.

◆ ZXC_GHI_MAX_INLINE_OUT_PER_SEQ

#define ZXC_GHI_MAX_INLINE_OUT_PER_SEQ ((ZXC_SEQ_LL_MASK - 1U) + (ZXC_SEQ_ML_MASK - 1U) + ZXC_LZ_MIN_MATCH_LEN) /* 513 */

Definition at line 640 of file zxc_internal.h.

◆ ZXC_GLO_DESC_MAX_SIZE

#define ZXC_GLO_DESC_MAX_SIZE (2 * sizeof(uint32_t))

Widest GLO section descriptors: the literal and token section sizes.

Definition at line 422 of file zxc_internal.h.

◆ ZXC_GLO_HEADER_BINARY_SIZE

#define ZXC_GLO_HEADER_BINARY_SIZE 12

Binary size of a GLO block sub-header.

Definition at line 418 of file zxc_internal.h.

◆ ZXC_GLO_INLINE_ML_CODE

#define ZXC_GLO_INLINE_ML_CODE (ZXC_TOKEN_ML_MASK - 1U) /* 14 */

Longest match length code (length minus ZXC_LZ_MIN_MATCH_LEN) a GLO token carries inline; the code above it escapes to a varint.

Definition at line 633 of file zxc_internal.h.

◆ ZXC_GLO_MAX_INLINE_ML

#define ZXC_GLO_MAX_INLINE_ML (ZXC_GLO_INLINE_ML_CODE + ZXC_LZ_MIN_MATCH_LEN) /* 19 */

Longest match a GLO sequence carries without a varint extension.

Below ZXC_PAD_SIZE, so the inline path needs no length ladder: one 32-byte store covers it. The escape path always yields more, so comparing against this recovers "was the ml nibble inline".

Definition at line 639 of file zxc_internal.h.

◆ ZXC_GLO_MAX_INLINE_OUT_PER_SEQ

#define ZXC_GLO_MAX_INLINE_OUT_PER_SEQ ((ZXC_TOKEN_LL_MASK - 1U) + ZXC_GLO_MAX_INLINE_ML) /* 33 */

Maximum decoded output of one sequence with inline ll/ml, used by the 4x bounds checks to reserve the rest of a batch.

Keep it small - the loop margins scale with it. Widening it to 543 once cost 2 percent of decode on silesia.

Definition at line 630 of file zxc_internal.h.

◆ ZXC_HASH_GOLDEN64

#define ZXC_HASH_GOLDEN64 0x9E3779B97F4A7C15ULL

Golden-ratio prime: header hashes and the digest spread.

Definition at line 709 of file zxc_internal.h.

◆ ZXC_HASH_MULT32

#define ZXC_HASH_MULT32 0x2D35182DU

Marsaglia 32-bit multiplier: the 4-byte LZ and dictionary hash.

Definition at line 713 of file zxc_internal.h.

◆ ZXC_HASH_MULT64

#define ZXC_HASH_MULT64 0xD2D84A61D2D84A61ULL

Second multiplier of the 16-byte header hash (zxc_hash16).

Definition at line 715 of file zxc_internal.h.

◆ ZXC_HASH_XORSHIFT64

#define ZXC_HASH_XORSHIFT64 0x2545F4914F6CDD1DULL

Vigna's xorshift* multiplier: the 5-byte LZ hash and the digest fold.

Definition at line 711 of file zxc_internal.h.

◆ ZXC_HUF_MARGIN_SHIFT

#define ZXC_HUF_MARGIN_SHIFT 5

Huffman margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_huf_q8 (the frozen ZXC_HUF_MIN_LITERALS floor was also historically derived from it).

Definition at line 808 of file zxc_internal.h.

◆ ZXC_HUF_MAX_CODE_LEN_DENSITY

#define ZXC_HUF_MAX_CODE_LEN_DENSITY 8

Encoder code-length cap for levels up to ZXC_LEVEL_DENSITY (below ZXC_LEVEL_ULTRA): shallow 8-bit trees decode fastest (fewer merge levels, denser flat subtrees) – this cap is the de-facto speed governor of level 6.

Definition at line 743 of file zxc_internal.h.

◆ ZXC_HUF_MAX_CODE_LEN_ULTRA

#define ZXC_HUF_MAX_CODE_LEN_ULTRA 11

Maximum Huffman code length, in bits: the ceiling the decoder's on-wire validation accepts (and the level-7 encoder cap).

Bounds the tree depth, hence the merge-level count and every stack array sized off the code length. The encoder caps codes per level via zxc_huf_enc_max_code_len.

Definition at line 738 of file zxc_internal.h.

◆ ZXC_HUF_MIN_LITERALS

#define ZXC_HUF_MIN_LITERALS 139

Absolute floor (in literals) below which a Huffman candidate is never evaluated.

Frozen byte-stability threshold. The value was originally derived from v6 wire geometry (128-byte lengths table + 6-byte sub-stream sizes) under the pre-Lagrangian huf_total < baseline * (M-1)/M call-site rule; neither input exists in v7 (sub-stream sizes are derived, selection uses J = size + lambda * tax), but raising or lowering the floor changes which blocks pick Huffman and therefore the emitted archive bytes, so it stays frozen at the historical value rather than being re-derived.

Definition at line 911 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_BITS_PERMIL

#define ZXC_HUF_NUDGE_BITS_PERMIL 1015

Adoption guard, ratio side (permil): adopt only while ‘bits’ * 1000 <= bits0 * ZXC_HUF_NUDGE_BITS_PERMIL` (<= +1.5%).

Definition at line 828 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_DEEP_FLAT_PENALTY

#define ZXC_HUF_NUDGE_DEEP_FLAT_PENALTY 24

Extra level-touches charged per occurrence under a flat root deeper than ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX (scalar bit-reader unpack path).

24 keeps low-mass deep-flat tails adoptable while making all-the-mass deep flats impossible to justify.

Definition at line 836 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_LAMBDA_Q8

#define ZXC_HUF_NUDGE_LAMBDA_Q8 26

Exchange rate (Q8 bits per modeled level-touch) in the candidate cost J = 256*bits + lambda*touches; 26 ~= 0.10 bit per touch.

Definition at line 825 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_LEVEL_COST

#define ZXC_HUF_NUDGE_LEVEL_COST 64

Fixed per-pass overhead (occurrence-equivalents) charged per merge level, modeling the pass-loop and node-dispatch cost so shallower trees also win on small sections.

Definition at line 840 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_MERGE_Q8

#define ZXC_HUF_NUDGE_MERGE_Q8 230

Adoption guard, speed side (Q8): adopt only while ‘touches’ * 256 <= touches0 * ZXC_HUF_NUDGE_MERGE_Q8` (<= ~0.90x).

Definition at line 831 of file zxc_internal.h.

◆ ZXC_HUF_NUM_SYMBOLS

#define ZXC_HUF_NUM_SYMBOLS 256

Alphabet size: one entry per possible byte value.

Definition at line 745 of file zxc_internal.h.

◆ ZXC_LIT_LEN_MASK

#define ZXC_LIT_LEN_MASK (ZXC_LIT_RLE_FLAG - 1)

Mask to extract the run/literal length (lower 7 bits).

Definition at line 528 of file zxc_internal.h.

◆ ZXC_LIT_RLE_FLAG

#define ZXC_LIT_RLE_FLAG 0x80U

Flag bit indicating an RLE run in the literal stream (0x80).

Definition at line 526 of file zxc_internal.h.

◆ ZXC_LITTLE_ENDIAN

#define ZXC_LITTLE_ENDIAN

Definition at line 280 of file zxc_internal.h.

◆ ZXC_LZ_HASH_BITS

#define ZXC_LZ_HASH_BITS 15

Address bits for the LZ77 hash table (2^15 = 32 768 buckets).

Definition at line 543 of file zxc_internal.h.

◆ ZXC_LZ_HASH_SIZE

#define ZXC_LZ_HASH_SIZE (1U << ZXC_LZ_HASH_BITS)

Maximum number of entries in the hash table.

Definition at line 545 of file zxc_internal.h.

◆ ZXC_LZ_MAX_DIST

#define ZXC_LZ_MAX_DIST (ZXC_LZ_WINDOW_SIZE - 1)

Maximum allowed offset distance.

Definition at line 645 of file zxc_internal.h.

◆ ZXC_LZ_MIN_MATCH_LEN

#define ZXC_LZ_MIN_MATCH_LEN 5

Minimum match length for an LZ77 match.

Definition at line 551 of file zxc_internal.h.

◆ ZXC_LZ_MINDIST

#define ZXC_LZ_MINDIST 32

Match distance floor the encoder holds to at levels 1 to 5, sized to the decoder's widest match-copy arm so the overlap kernel stays off the decode path.

Applied per block, and only where ZXC_LZ_MINDIST_MAX_SHORT_PCT clears it; levels 6 and 7 keep every distance. Encoder policy: no format bit moves, so any decoder of the same format version reads the result. 1 disables.

Definition at line 660 of file zxc_internal.h.

◆ ZXC_LZ_MINDIST_MAX_SHORT_PCT

#define ZXC_LZ_MINDIST_MAX_SHORT_PCT 20

Short-distance hit rate, in percent, above which a block keeps its short match distances.

Measured: natural text 2-5 %, XML around 25 %, JSON 50-60 %, periodic data 100 %. Decode gains follow the same order, so the cut sits just above text and below everything that measured neutral or worse.

Definition at line 677 of file zxc_internal.h.

◆ ZXC_LZ_MINDIST_PROBE_MAX

#define ZXC_LZ_MINDIST_PROBE_MAX 64

Definition at line 669 of file zxc_internal.h.

◆ ZXC_LZ_MINDIST_PROBE_MIN

#define ZXC_LZ_MINDIST_PROBE_MIN 16

Definition at line 668 of file zxc_internal.h.

◆ ZXC_LZ_MINDIST_PROBE_PER_KB

#define ZXC_LZ_MINDIST_PROBE_PER_KB 1024

Probe sampling: one position per KB, clamped.

Proportional on purpose: a fixed count costs the same on a 4 KB block as on a 512 KB one, which measured as a third of the compression time on small, highly compressible inputs.

Definition at line 667 of file zxc_internal.h.

◆ ZXC_LZ_OFFSET_BIAS

#define ZXC_LZ_OFFSET_BIAS 1

Base bias added to encoded offsets (stored = actual - bias).

Definition at line 643 of file zxc_internal.h.

◆ ZXC_LZ_SEARCH_MARGIN

#define ZXC_LZ_SEARCH_MARGIN (sizeof(uint64_t))

Bytes at the block end where match search stops (left as literals).

Equals the 8-byte word the finder reads at each probe, so ip+8<=iend.

Definition at line 680 of file zxc_internal.h.

◆ ZXC_LZ_WINDOW_MASK

#define ZXC_LZ_WINDOW_MASK (ZXC_LZ_WINDOW_SIZE - 1U)

Mask for ring-buffer indexing into chain_table (power-of-two window).

Definition at line 549 of file zxc_internal.h.

◆ ZXC_LZ_WINDOW_SIZE

#define ZXC_LZ_WINDOW_SIZE (1U << 16)

Sliding window size (64 KB).

Definition at line 547 of file zxc_internal.h.

◆ ZXC_MALLOC

#define ZXC_MALLOC ( size ) malloc(size)

Heap allocator.

Default: libc malloc.

Definition at line 68 of file zxc_deps.h.

◆ ZXC_MAX_VARINT_VALUE

#define ZXC_MAX_VARINT_VALUE ((uint32_t)(ZXC_BLOCK_SIZE_MAX - 1U))

Maximum legitimate value a varint can decode to.

A varint value represents (ll - MASK) or (ml - MASK) and is therefore always strictly less than ZXC_BLOCK_SIZE_MAX (enforced by the Block API entry points). The cap is set to (ZXC_BLOCK_SIZE_MAX - 1), which fits cleanly in a 3-byte varint (21 bits): the decoder rejects any 4- or 5-byte encoding, and the encoder refuses to emit values above this bound. Together they bound the varint surface to exactly the format-defined block size limit.

Definition at line 560 of file zxc_internal.h.

◆ ZXC_MEMCPY

#define ZXC_MEMCPY	(	dst,
		src,
		n
	)	memcpy(dst, src, n)

Definition at line 239 of file zxc_internal.h.

◆ ZXC_MEMSET

#define ZXC_MEMSET	(	dst,
		val,
		n
	)	memset(dst, val, n)

Definition at line 240 of file zxc_internal.h.

◆ ZXC_NOINLINE

#define ZXC_NOINLINE

Prevents inlining (best-effort no-op fallback for unknown compilers).

Definition at line 250 of file zxc_internal.h.

◆ ZXC_OPT_LIT_SAMPLE_MIN

#define ZXC_OPT_LIT_SAMPLE_MIN 1024

Minimum literal count for the sample-based Huffman cost estimator used by the optimal parser.

Below this, the strided sample is too small for the resulting code-lengths to be statistically reliable, so the estimator falls back to RAW cost (8 bits/byte).

Definition at line 699 of file zxc_internal.h.

◆ ZXC_OPT_LONG_MATCH_SKIP

#define ZXC_OPT_LONG_MATCH_SKIP ((size_t)256)

Threshold above which find_best_match is skipped at intra-match positions, keeping the parser O(N) on highly repetitive data.

Definition at line 692 of file zxc_internal.h.

◆ ZXC_OPT_MATCH_COST_BASE

#define ZXC_OPT_MATCH_COST_BASE ((uint32_t)(3U * CHAR_BIT))

Static price (bits) of a match token before varint extras: 1 byte token + 2 byte offset.

Definition at line 689 of file zxc_internal.h.

◆ ZXC_PAD_SIZE

#define ZXC_PAD_SIZE 32

Safety padding appended to buffers to tolerate overruns.

Definition at line 331 of file zxc_internal.h.

◆ ZXC_PIVCO_COVERED

#define ZXC_PIVCO_COVERED 0xFFU

flat_d of a node inside a flat root: no run, no children.

Definition at line 762 of file zxc_internal.h.

◆ ZXC_PIVCO_MAX_NODES

#define ZXC_PIVCO_MAX_NODES (2 * ZXC_HUF_NUM_SYMBOLS - 1)

Upper bound on PivCo tree nodes (full binary tree over the alphabet).

Definition at line 752 of file zxc_internal.h.

◆ ZXC_PIVCO_NODE_SLOTS

#define ZXC_PIVCO_NODE_SLOTS (ZXC_PIVCO_MAX_NODES + 1)

Node-indexed array size: every node, plus a slot for the lone-symbol root's missing child.

Definition at line 755 of file zxc_internal.h.

◆ ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX

#define ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX 6

Deepest flat subtree zxc_pivco_unpack_flat unpacks with a SIMD kernel (its D == 2..6 cases); deeper flat roots take the scalar bit-reader.

A structural fact of that unpacker, not tunable.

Definition at line 759 of file zxc_internal.h.

◆ ZXC_POPCOUNT32

#define ZXC_POPCOUNT32 ( v ) zxc_popcount32(v)

Definition at line 169 of file zxc_deps.h.

◆ ZXC_POPCOUNT64

#define ZXC_POPCOUNT64 ( v ) zxc_popcount64(v)

Definition at line 170 of file zxc_deps.h.

◆ ZXC_PREFETCH_READ

#define ZXC_PREFETCH_READ ( ptr )

Definition at line 238 of file zxc_internal.h.

◆ ZXC_REALLOC

#define ZXC_REALLOC	(	ptr,
		size
	)	realloc(ptr, size)

In-place / move heap reallocator.

Default: libc realloc.

Definition at line 80 of file zxc_deps.h.

◆ ZXC_RLE_MARGIN_SHIFT

#define ZXC_RLE_MARGIN_SHIFT 5

RLE margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_rle_q8 (256 >> shift reproduces the historical RLE-vs-RAW margin exactly).

Definition at line 804 of file zxc_internal.h.

◆ ZXC_SEEK_ANCHOR_SIZE

#define ZXC_SEEK_ANCHOR_SIZE 8U

Group anchor: offset of its first block, u64.

Definition at line 451 of file zxc_internal.h.

◆ ZXC_SEEK_GROUP

#define ZXC_SEEK_GROUP 64U

Blocks per group.

A format constant: changing it is a version bump.

Definition at line 449 of file zxc_internal.h.

◆ ZXC_SEEK_GROUP_BYTES

#define ZXC_SEEK_GROUP_BYTES (ZXC_SEEK_ANCHOR_SIZE + ZXC_SEEK_GROUP * ZXC_SEEK_SIZE_ENTRY)

Full group: anchor + ZXC_SEEK_GROUP sizes.

Definition at line 455 of file zxc_internal.h.

◆ ZXC_SEEK_SIZE_ENTRY

#define ZXC_SEEK_SIZE_ENTRY 4U

One block's on-disk size, u32.

Definition at line 453 of file zxc_internal.h.

◆ ZXC_SEQ_LL_BITS

#define ZXC_SEQ_LL_BITS 8

Bits for Literal Length in a GHI sequence.

Definition at line 508 of file zxc_internal.h.

◆ ZXC_SEQ_LL_MASK

#define ZXC_SEQ_LL_MASK ((1U << ZXC_SEQ_LL_BITS) - 1)

Mask to extract Literal Length from a GHI sequence.

Definition at line 514 of file zxc_internal.h.

◆ ZXC_SEQ_ML_BITS

#define ZXC_SEQ_ML_BITS 8

Bits for Match Length in a GHI sequence.

Definition at line 510 of file zxc_internal.h.

◆ ZXC_SEQ_ML_MASK

#define ZXC_SEQ_ML_MASK ((1U << ZXC_SEQ_ML_BITS) - 1)

Mask to extract Match Length from a GHI sequence.

Definition at line 516 of file zxc_internal.h.

◆ ZXC_SEQ_OFF_BITS

#define ZXC_SEQ_OFF_BITS 16

Bits for Offset in a GHI sequence.

Definition at line 512 of file zxc_internal.h.

◆ ZXC_SEQ_OFF_MASK

#define ZXC_SEQ_OFF_MASK ((1U << ZXC_SEQ_OFF_BITS) - 1)

Mask to extract Offset from a GHI sequence.

Definition at line 518 of file zxc_internal.h.

◆ ZXC_SS_TAX

#define ZXC_SS_TAX	(	n,
		prem_q8
	)	(((size_t)(n) * (size_t)(prem_q8)) >> 8)

Decode tax of a candidate: n decoded bytes at premium prem (Q8).

Definition at line 862 of file zxc_internal.h.

◆ ZXC_TOKEN_LIT_BITS

#define ZXC_TOKEN_LIT_BITS 4

Bits for Literal Length in a GLO token.

Definition at line 493 of file zxc_internal.h.

◆ ZXC_TOKEN_LL_MASK

#define ZXC_TOKEN_LL_MASK ((1U << ZXC_TOKEN_LIT_BITS) - 1)

Mask to extract Literal Length from a GLO token.

Definition at line 497 of file zxc_internal.h.

◆ ZXC_TOKEN_ML_BITS

#define ZXC_TOKEN_ML_BITS 4

Bits for Match Length in a GLO token.

Definition at line 495 of file zxc_internal.h.

◆ ZXC_TOKEN_ML_MASK

#define ZXC_TOKEN_ML_MASK ((1U << ZXC_TOKEN_ML_BITS) - 1)

Mask to extract Match Length from a GLO token.

Definition at line 499 of file zxc_internal.h.

◆ ZXC_USE_C11_ATOMICS

#define ZXC_USE_C11_ATOMICS 1

Definition at line 64 of file zxc_internal.h.

Function Documentation

◆ zxc_aligned_free()

static void zxc_aligned_free ( void * ptr )

inlinestatic

Counterpart of zxc_aligned_malloc; NULL is a no-op.

Definition at line 124 of file zxc_deps.h.

◆ zxc_aligned_malloc()

static void * zxc_aligned_malloc	(	const size_t	size,
		const size_t	alignment
	)

inlinestatic

Default cache-line-aligned allocator; release with zxc_aligned_free.

Definition at line 113 of file zxc_deps.h.

◆ zxc_magic_prefix_ok()

static int zxc_magic_prefix_ok	(	const uint8_t *	p,
		const size_t	n
	)

inlinestatic

Whether the first n bytes (up to 4) at p agree with the magic word, so a frame may start there: the check a reader makes as bytes arrive.

Definition at line 318 of file zxc_internal.h.

References ZXC_MAGIC_WORD.

Referenced by ds_handle_need_file_header(), and zxc_container_next().

◆ zxc_popcount32()

static int zxc_popcount32 ( const uint32_t v )

inlinestatic

Portable SWAR popcount (MSVC).

Definition at line 160 of file zxc_deps.h.

◆ zxc_popcount64()

static int zxc_popcount64 ( const uint64_t v )

inlinestatic

Definition at line 166 of file zxc_deps.h.

◆ zxc_read_varint()

static uint32_t zxc_read_varint	(	const uint8_t **	ptr,
		const uint8_t *	end
	)

inlinestatic

Reads a Prefix Varint encoded integer.

Unary prefix bits in the first byte give the total length, at most 3 bytes since that covers every length the format admits:

Format:

1 byte (0xxxxxxx): 7-bit payload (val < 2^7 = 128)
2 bytes (10xxxxxx): 14-bit payload (val < 2^14 = 16384)
3 bytes (110xxxxx): 21-bit payload (val < 2^21 = 2097152)

Parameters

[in,out]	ptr	Pointer to a pointer to the current position in the stream.
[in]	end	Pointer to the end of the readable stream (for bounds checking).

Returns: The decoded 32-bit integer, or 0 if reading would overflow bounds (safe default).

Definition at line 586 of file zxc_internal.h.

Referenced by zxc_glo_split_block(), and zxc_varint_keep().

◆ zxc_seek_group_count()

static uint64_t zxc_seek_group_count ( const uint64_t nblocks )

inlinestatic

Groups holding nblocks blocks; the last one may be partial.

Definition at line 458 of file zxc_internal.h.

References ZXC_SEEK_GROUP.

Referenced by zxc_seek_load_spans(), and zxc_seek_table_bytes().

◆ zxc_seek_group_len()

static uint32_t zxc_seek_group_len	(	const uint64_t	nblocks,
		const uint64_t	g
	)

inlinestatic

Blocks in group g of nblocks: ZXC_SEEK_GROUP, fewer for the last.

Definition at line 463 of file zxc_internal.h.

References ZXC_SEEK_GROUP.

Referenced by zxc_seek_load_spans(), zxc_stream_finish_compress(), and zxc_write_seek_table().

◆ zxc_seek_size_field()

static uint32_t zxc_seek_size_field ( const uint64_t table_bytes )

inlinestatic

SEK header size field: table_bytes with its high half folded onto the low one.

Exact below 4 GiB; above, all 64 bits count.

Definition at line 475 of file zxc_internal.h.

Referenced by zxc_seek_table_header().

◆ zxc_seek_table_bytes()

static uint64_t zxc_seek_table_bytes ( const uint64_t nblocks )

inlinestatic

Byte size of the groups for nblocks blocks, in 64 bits.

Definition at line 469 of file zxc_internal.h.

References ZXC_SEEK_ANCHOR_SIZE, zxc_seek_group_count(), and ZXC_SEEK_SIZE_ENTRY.

Referenced by zxc_check_seek_header(), zxc_compress_bound(), zxc_inplace_margin(), zxc_seek_parse_frame(), zxc_seek_table_header(), and zxc_seek_table_size().

◆ zxc_ss_prem_huf_q8()

static int zxc_ss_prem_huf_q8 ( const int level )

inlinestatic

Per-level Huffman/PivCo-vs-RAW decode premium (Q8) for the space-speed selector.

Feeds ZXC_SS_TAX, which charges a Huffman literal (or token) candidate n * premium >> 8 decode-tax bytes over the RAW copy path, the level's lambda folded with the entropy decoder's cost. Below ZXC_LEVEL_DENSITY the premium is 256 >> ZXC_HUF_MARGIN_SHIFT (8 = 3.125%), matching the historical Huffman margin against a RAW baseline. At ZXC_LEVEL_DENSITY and above the physical premium 4 (1.56%) applies, trading more decode time for ratio (the entropy decoder costs ~0.5 ns/B over a raw copy; validated on silesia).

Parameters

[in] level Compression level.

Returns: Decode premium in Q8 (Huffman decode-tax bytes per 256 decoded bytes).

Definition at line 896 of file zxc_internal.h.

References ZXC_HUF_MARGIN_SHIFT, and ZXC_LEVEL_DENSITY.

Referenced by zxc_encode_block_glo().

◆ zxc_ss_prem_rle_q8()

static int zxc_ss_prem_rle_q8 ( const int level )

inlinestatic

Per-level RLE-vs-RAW decode premium (Q8) for the space-speed selector.

Feeds ZXC_SS_TAX, which charges an RLE candidate n * premium >> 8 decode-tax bytes over the RAW copy path. Below ZXC_LEVEL_DENSITY the premium is 256 >> ZXC_RLE_MARGIN_SHIFT (8 = 3.125%), reproducing the historical RLE-vs-RAW margin exactly so those levels keep byte-stable selection. At ZXC_LEVEL_DENSITY and above the physical premium 1 (0.39%) applies: RLE decodes at near copy speed, so it needs only a token tax to break ties toward RAW.

Parameters

[in] level Compression level.

Returns: Decode premium in Q8 (RLE decode-tax bytes per 256 decoded bytes).

Definition at line 877 of file zxc_internal.h.

References ZXC_LEVEL_DENSITY, and ZXC_RLE_MARGIN_SHIFT.

Referenced by zxc_encode_block_glo().

Data Structures

Macros

Aligned Allocator Abstraction

Population Count

File Format Constants

Seekable Format Constants

LZ77 Constants

Space-speed section selection

Heap Allocator Abstraction

Atomic Qualifier

Compiler Abstractions

GLO Token Constants

GHI Sequence Constants

Literal Stream Encoding

Optimal Parser Tuning (level >= 6)

Hash multipliers

Huffman Codec Constants

Encoder-side joint flat/length nudge (PivCo decode-speed shaping)

Detailed Description

Macro Definition Documentation

◆ LIKELY

◆ RESTRICT

◆ UNLIKELY

◆ ZXC_ALIGN

◆ ZXC_ALIGN_CL

◆ ZXC_ALIGNED_FREE

◆ ZXC_ALIGNED_MALLOC

◆ ZXC_ALIGNMENT_MASK

◆ ZXC_ALWAYS_INLINE

◆ ZXC_ATOMIC

◆ ZXC_BITMAP_WORDS

◆ ZXC_BLOCK_CHECKSUM_SIZE

◆ ZXC_BLOCK_FORMAT_OVERHEAD

◆ ZXC_BLOCK_HEADER_SIZE

◆ ZXC_BLOCK_LIT_SLACK

◆ ZXC_CACHE_LINE_SIZE

◆ ZXC_CALLOC

◆ ZXC_CHECKSUM_RAPIDHASH

◆ ZXC_COLD

◆ ZXC_DECOMPRESS_TAIL_PAD

◆ ZXC_DICT_HASH_BITS

◆ ZXC_DICT_HASH_SIZE

◆ ZXC_DICT_HUF_SAMPLE_BUDGET

◆ ZXC_DICT_HUF_TRAIN_BLOCK

◆ ZXC_DICT_KGRAM_LEN

◆ ZXC_DICT_MAX_SEGMENTS

◆ ZXC_DICT_SAMPLE_TARGET

◆ ZXC_DICT_VERSION

◆ ZXC_FILE_CHECKSUM_ALGO_MASK

◆ ZXC_FILE_FLAG_HAS_CHECKSUM

◆ ZXC_FILE_FLAG_HAS_DICTIONARY

◆ ZXC_FILE_FLAG_HAS_SEEK_TABLE

◆ ZXC_FILE_FORMAT_VERSION

◆ ZXC_FREE

◆ ZXC_GHI_HEADER_BINARY_SIZE

◆ ZXC_GHI_MAX_INLINE_OUT_PER_SEQ

◆ ZXC_GLO_DESC_MAX_SIZE

◆ ZXC_GLO_HEADER_BINARY_SIZE

◆ ZXC_GLO_INLINE_ML_CODE

◆ ZXC_GLO_MAX_INLINE_ML

◆ ZXC_GLO_MAX_INLINE_OUT_PER_SEQ

◆ ZXC_HASH_GOLDEN64

◆ ZXC_HASH_MULT32

◆ ZXC_HASH_MULT64

◆ ZXC_HASH_XORSHIFT64

◆ ZXC_HUF_MARGIN_SHIFT

◆ ZXC_HUF_MAX_CODE_LEN_DENSITY

◆ ZXC_HUF_MAX_CODE_LEN_ULTRA

◆ ZXC_HUF_MIN_LITERALS

◆ ZXC_HUF_NUDGE_BITS_PERMIL

◆ ZXC_HUF_NUDGE_DEEP_FLAT_PENALTY

◆ ZXC_HUF_NUDGE_LAMBDA_Q8

◆ ZXC_HUF_NUDGE_LEVEL_COST

◆ ZXC_HUF_NUDGE_MERGE_Q8

◆ ZXC_HUF_NUM_SYMBOLS

◆ ZXC_LIT_LEN_MASK

◆ ZXC_LIT_RLE_FLAG

◆ ZXC_LITTLE_ENDIAN

◆ ZXC_LZ_HASH_BITS

◆ ZXC_LZ_HASH_SIZE