Struct regex_automata::nfa::thompson::pikevm::Cache

pub struct Cache {
    stack: Vec<FollowEpsilon>,
    curr: ActiveStates,
    next: ActiveStates,
}

A cache represents mutable state that a PikeVM requires during a search.

For a given PikeVM, its corresponding cache may be created either via PikeVM::create_cache, or via Cache::new. They are equivalent in every way, except the former does not require explicitly importing Cache.

A particular Cache is coupled with the PikeVM from which it was created. It may only be used with that PikeVM. A cache and its allocations may be re-purposed via Cache::reset, in which case, it can only be used with the new PikeVM (and not the old one).

Fields

stack: Vec<FollowEpsilon>

Stack used while computing epsilon closure. This effectively lets us move what is more naturally expressed through recursion to a stack on the heap.

curr: ActiveStates

The current active states being explored for the current byte in the haystack.

next: ActiveStates

The next set of states we’re building that will be explored for the next byte in the haystack.

Implementations

impl Cache

pub fn new(re: &PikeVM) -> Cache

Create a new PikeVM cache.

A potentially more convenient routine to create a cache is PikeVM::create_cache, as it does not require also importing the Cache type.

If you want to reuse the returned Cache with some other PikeVM, then you must call Cache::reset with the desired PikeVM.

pub fn reset(&mut self, re: &PikeVM)

Reset this cache such that it can be used for searching with a different PikeVM.

A cache reset permits reusing memory already allocated in this cache with a different PikeVM.

Example

This shows how to re-purpose a cache for use with a different PikeVM.

use regex_automata::{nfa::thompson::pikevm::PikeVM, Match};

let re1 = PikeVM::new(r"\w")?;
let re2 = PikeVM::new(r"\W")?;

let mut cache = re1.create_cache();
assert_eq!(
    Some(Match::must(0, 0..2)),
    re1.find_iter(&mut cache, "Δ").next(),
);

// Using 'cache' with re2 is not allowed. It may result in panics or
// incorrect results. In order to re-purpose the cache, we must reset
// it with the PikeVM we'd like to use it with.
//
// Similarly, after this reset, using the cache with 're1' is also not
// allowed.
cache.reset(&re2);
assert_eq!(
    Some(Match::must(0, 0..3)),
    re2.find_iter(&mut cache, "☃").next(),
);

pub fn memory_usage(&self) -> usize

Returns the heap memory usage, in bytes, of this cache.

This does not include the stack size used up by this cache. To compute that, use std::mem::size_of::<Cache>().

fn setup_search(&mut self, captures_slot_len: usize)

Clears this cache. This should be called at the start of every search to ensure we start with a clean slate.

This also sets the length of the capturing groups used in the current search. This permits an optimization where by ‘SlotTable::for_state’ only returns the number of slots equivalent to the number of slots given in the ‘Captures’ value. This may be less than the total number of possible slots, e.g., when one only wants to track overall match offsets. This in turn permits less copying of capturing group spans in the PikeVM.

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.