Struct Cache

pub struct Cache { /* private fields */ }

Available on crate feature meta only.

Represents mutable scratch space used by regex engines during a search.

Most of the regex engines in this crate require some kind of mutable state in order to execute a search. This mutable state is explicitly separated from the core regex object (such as a thompson::NFA) so that the read-only regex object can be shared across multiple threads simultaneously without any synchronization. Conversely, a Cache must either be duplicated if using the same Regex from multiple threads, or else there must be some kind of synchronization that guarantees exclusive access while it’s in use by one thread.

A Regex attempts to do this synchronization for you by using a thread pool internally. Its size scales roughly with the number of simultaneous regex searches.

For cases where one does not want to rely on a Regex’s internal thread pool, lower level routines such as Regex::search_with are provided that permit callers to pass a Cache into the search routine explicitly.

General advice is that the thread pool is often more than good enough. However, it may be possible to observe the effects of its latency, especially when searching many small haystacks from many threads simultaneously.

Caches can be created from their corresponding Regex via Regex::create_cache. A cache can only be used with either the Regex that created it, or the Regex that was most recently used to reset it with Cache::reset. Using a cache with any other Regex may result in panics or incorrect results.

Example

use regex_automata::{meta::Regex, Input, Match};

let re = Regex::new(r"(?-u)m\w+\s+m\w+")?;
let mut cache = re.create_cache();
let input = Input::new("crazy janey and her mission man");
assert_eq!(
    Some(Match::must(0, 20..31)),
    re.search_with(&mut cache, &input),
);

Implementations

impl Cache

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

Creates a new Cache for use with this regex.

The cache returned should only be used for searches for the given Regex. If you want to reuse the cache for another Regex, then you must call Cache::reset with that Regex.

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

Reset this cache such that it can be used for searching with the given Regex (and only that Regex).

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

Example

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

use regex_automata::{meta::Regex, Match, Input};

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

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

// 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 Regex 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.search_with(&mut cache, &Input::new("☃")),
);

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>().

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.