Skip to main content

Matcher

structured_zstd::encoding

Trait Matcher 

Source 
pub trait Matcher {
    // Required methods
    fn get_next_space(&mut self) -> Vec<u8> ⓘ;
    fn get_last_space(&mut self) -> &[u8] ⓘ;
    fn commit_space(&mut self, space: Vec<u8>);
    fn skip_matching(&mut self);
    fn start_matching(
        &mut self,
        handle_sequence: impl for<'a> FnMut(Sequence<'a>),
    );
    fn reset(&mut self, level: CompressionLevel);
    fn window_size(&self) -> u64;

    // Provided methods
    fn skip_matching_with_hint(&mut self, _incompressible_hint: Option<bool>) { ... }
    fn set_source_size_hint(&mut self, _size: u64) { ... }
    fn prime_with_dictionary(
        &mut self,
        _dict_content: &[u8],
        _offset_hist: [u32; 3],
    ) { ... }
    fn supports_dictionary_priming(&self) -> bool { ... }
}
Expand description

Trait used by the encoder that users can use to extend the matching facilities with their own algorithm making their own tradeoffs between runtime, memory usage and compression ratio

This trait operates on buffers that represent the chunks of data the matching algorithm wants to work on. Each one of these buffers is referred to as a space. One or more of these buffers represent the window the decoder will need to decode the data again.

This library asks the Matcher for a new buffer using get_next_space to allow reusing of allocated buffers when they are no longer part of the window of data that is being used for matching.

The library fills the buffer with data that is to be compressed and commits them back to the matcher using commit_space.

Then it will either call start_matching or, if the space is deemed not worth compressing, skip_matching is called.

This is repeated until no more data is left to be compressed.

Required Methods§

Source

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.

Source

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

Get a reference to the last committed space

Source

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

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

Source

fn skip_matching(&mut self)

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

Source

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

Source

fn reset(&mut self, level: CompressionLevel)

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

Source

fn window_size(&self) -> u64

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

Must return a positive (non-zero) value; returning 0 causes StreamingEncoder to reject the first write with an invalid-input error (InvalidInput with std, Other with no_std).

Must remain stable for the lifetime of a frame. It may change only after reset() is called for the next frame (for example because the compression level changed).

Provided Methods§

Source

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.

Default implementation preserves backwards compatibility for external custom matchers by delegating to skip_matching.

Source

fn set_source_size_hint(&mut self, _size: u64)

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

Implementations may use this to select smaller hash tables and windows for small inputs, matching the C zstd source-size-class behavior. Called before reset when the caller knows the input size (e.g. from pledged content size or file metadata).

The default implementation is a no-op for custom matchers and test stubs. The built-in runtime matcher (MatchGeneratorDriver) overrides this hook and applies the hint during level resolution.

Source

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.

Source

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.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§