Struct regex_automata::meta::Cache

source ·
pub struct Cache { /* private fields */ }
Expand description

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 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§

source§

impl Cache

source

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.

source

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("☃")),
);
source

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§

source§

impl Clone for Cache

source§

fn clone(&self) -> Cache

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Cache

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl Freeze for Cache

§

impl RefUnwindSafe for Cache

§

impl Send for Cache

§

impl Sync for Cache

§

impl Unpin for Cache

§

impl UnwindSafe for Cache

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.