Struct `Cache`

struct Cache { ... }

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),
);

# Ok::<(), Box<dyn std::error::Error>>(())

Implementations

`impl Cache`

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.

fn reset(self: &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.

# if cfg!(miri) { return Ok(()); } // miri takes too long
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("☃")),
);

# Ok::<(), Box<dyn std::error::Error>>(())

fn memory_usage(self: &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>().

`impl Clone for Cache`

fn clone(self: &Self) -> Cache

`impl Debug for Cache`

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

`impl Freeze for Cache`

`impl RefUnwindSafe for Cache`

`impl Send for Cache`

`impl Sync for Cache`

`impl Unpin for Cache`

`impl UnsafeUnpin for Cache`

`impl UnwindSafe for Cache`

`impl<T> Any for Cache`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Cache`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Cache`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Cache`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Cache`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Cache`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for Cache`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Cache`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Cache`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>