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 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
impl Cache
sourcepub fn new(re: &Regex) -> 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
.
sourcepub fn reset(&mut self, re: &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("☃")),
);
sourcepub fn memory_usage(&self) -> usize
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§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)