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 fill_in_place( &mut self, capacity: usize, fill: &mut dyn FnMut(&mut Vec<u8>) -> (usize, bool), ) -> Option<(usize, bool)>

Read the next block STRAIGHT into the backend’s history buffer, so the owned block loop does not stage it in a scratch Vec and copy it in.

Returns None when the active backend has no in-place ingest, in which case the caller keeps the staged-copy path. Dfast, Row and HashChain implement it; Simple stages the block in a pending slot that the kernel consumes, so its bytes do not reach history until match time and the two-phase shape does not apply to it as written.

On Some, the bytes are in the buffer but not yet part of the window: the caller picks the block boundary from Self::uncommitted_input and then calls Self::commit_filled.

fn uncommitted_input(&self) -> &[u8]

Bytes read by Self::fill_in_place that no block has claimed yet.

fn commit_filled(&mut self, len: usize)

Claim len bytes of Self::uncommitted_input as the next block.

Runs the same eviction accounting as Self::commit_space: a dictionary inflates max_window_size so the primed bytes stay reachable, and once eviction carries them out of the window that inflation has to be retired. Skipping it leaves the backend admitting matches older than the window the frame header reports, which encodes an offset no decoder can resolve.

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, sizes: DictionarySizes)

Hint the sizes of the dictionary that will be primed into the next frame. The built-in runtime matcher resolves the frame’s cParams from the dictionary’s CDict tier (upstream ZSTD_createCDict, keyed by the serialized size) and sizes its dictionary tables from the content. 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 reserve_for_frame(&mut self, bytes: usize)

Size the ingest buffer for a frame of bytes up front, so filling it block by block doesn’t walk a doubling chain of reallocations. Clamped internally to the buffer’s eviction ceiling, so an over-long or absent hint can never reserve more than a bounded window. No-op unless fill_in_place is implemented.

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.