Struct MatchGeneratorDriver 

pub struct MatchGeneratorDriver { /* private fields */ }

This is the default implementation of the Matcher trait. It allocates and reuses the buffers when possible.

Trait Implementations

impl Matcher for MatchGeneratorDriver

fn block_samples_match_dict(&self, block: &[u8]) -> bool

Dict-relevance gate for the raw-fast-path. Reached only when a dictionary is active (the caller short-circuits on dict_active), so this answers “could the dict compress this otherwise-incompressible-looking block?”. The Simple (Fast) backend samples its dict table precisely ([FastKernelMatcher::block_samples_match_dict]); the other backends (Dfast / Row / HashChain / BT) have their own dict structures and no cheap probe here, so they answer CONSERVATIVELY true: without a probe they cannot tell whether the dict compresses an incompressible-LOOKING block, and answering false would let the raw-fast-path emit such a block raw and miss an embedded dict segment. dictionary_segment_in_incompressible_input_is_matched pins this for Dfast/Row/BT — the 512-byte dict run inside high-entropy filler is matched only because these backends stay on the scan. So they keep the blanket scan the old !dict_active gate gave them; only the Simple/Fast backend trades it for the precise probe.

fn heap_size(&self) -> usize

Heap bytes this driver owns: the active backend’s tables/history, the recycled input-buffer pool, and the primed-dictionary snapshot (a cloned backend kept for CDict-equivalent reuse). The inline struct itself is accounted by the owner’s size_of.

fn supports_dictionary_priming(&self) -> bool

Returns whether this matcher can consume dictionary priming state and produce dictionary-dependent sequences. Defaults to false for custom matchers.

fn set_source_size_hint(&mut self, size: u64)

Provide a hint about the total uncompressed size for the next frame.

fn set_dictionary_size_hint(&mut self, size: usize)

Hint the byte size of the dictionary that will be primed into the next frame. The built-in runtime matcher uses it to size the binary-tree / hash-chain match-finder tables from the dictionary’s cParams tier rather than the source window (upstream zstd CDict economics), while keeping the eviction window source-sized. Default no-op for custom matchers and test stubs; consumed at the next reset.

fn clear_param_overrides(&mut self)

Drop any per-frame fine-grained parameter overrides installed via the public parameter API, reverting to plain level-based geometry at the next reset. Called by FrameCompressor::set_compression_level so switching back to a bare level after a customized frame does not keep the old overrides sticky. Default no-op for custom matchers.

fn reset(&mut self, level: CompressionLevel)

Reset this matcher so it can be used for the next new frame

fn dictionary_is_resident(&self) -> bool

Whether the most recent reset re-borrowed a resident attach-mode dictionary (kept the dict bytes + cached index in place). When true the caller MUST skip Self::prime_with_dictionary and only reapply the offset history via Self::reapply_resident_dictionary.

fn reapply_resident_dictionary(&mut self, offset_hist: [u32; 3])

Reapply the dictionary’s offset history to a re-borrowed frame — the cheap tail of priming, without the dict commit / re-index. Default no-op.

fn prime_with_dictionary(&mut self, dict_content: &[u8], offset_hist: [u32; 3])

Prime matcher state with dictionary history before compressing the next frame. Default implementation is a no-op for custom matchers that do not support this.

fn restore_primed_dictionary(&mut self, level: CompressionLevel) -> bool

CDict-equivalent fast path for repeated frames sharing one dictionary. Restore the matcher state captured by Self::capture_primed_dictionary at the SAME level (a table copy) instead of re-running Self::prime_with_dictionary (which re-hashes every dictionary position). Returns true when a matching snapshot was restored; false (the default) means the caller must prime then capture.

fn capture_primed_dictionary(&mut self, level: CompressionLevel)

Snapshot the post-prime matcher state for the given level so later frames can Self::restore_primed_dictionary it. Default no-op.

fn invalidate_primed_dictionary(&mut self)

Drop any captured prime snapshot (dictionary or level changed). Default no-op.

fn seed_dictionary_entropy( &mut self, huff: Option<&HuffmanTable>, ll: Option<&FSETable>, ml: Option<&FSETable>, of: Option<&FSETable>, )

Seed matcher cost model with dictionary entropy tables before the next frame. Default implementation is a no-op for custom matchers.

fn window_size(&self) -> u64

The size of the window the decoder will need to execute all sequences produced by this matcher.

fn get_next_space(&mut self) -> Vec<u8>

Get a space where we can put data to be matched on. Will be encoded as one block. The maximum allowed size is 128 kB.

fn get_last_space(&mut self) -> &[u8]

Get a reference to the last committed space

fn commit_space(&mut self, space: Vec<u8>)

Commit a space to the matcher so it can be matched against

fn start_matching(&mut self, handle_sequence: impl for<'a> FnMut(Sequence<'a>))

Process the data in the last committed space for future matching AND generate matches for the data

fn skip_matching(&mut self)

Just process the data in the last committed space for future matching.

fn skip_matching_with_hint(&mut self, incompressible_hint: Option<bool>)

Hint-aware skip path used internally to thread a precomputed block incompressibility verdict to matcher backends.