Struct Lazy

pub struct Lazy<T, F = fn() -> T>(/* private fields */);

A lazily initialized value that implements Deref for T.

A Lazy takes an initialization function and permits callers from any thread to access the result of that initialization function in a safe manner. In effect, this permits one-time initialization of global resources in a (possibly) multi-threaded program.

This type and its functionality are available even when neither the alloc nor the std features are enabled. In exchange, a Lazy does not guarantee that the given create function is called at most once. It might be called multiple times. Moreover, a call to Lazy::get (either explicitly or implicitly via Lazy’s Deref impl) may block until a T is available.

This is very similar to lazy_static or once_cell, except it doesn’t guarantee that the initialization function will be run once and it works in no-alloc no-std environments. With that said, if you need stronger guarantees or a more flexible API, then it is recommended to use either lazy_static or once_cell.

Warning: may use a spin lock

When this crate is compiled without the alloc feature, then this type may used a spin lock internally. This can have subtle effects that may be undesirable. See Spinlocks Considered Harmful for a more thorough treatment of this topic.

Example

This type is useful for creating regexes once, and then using them from multiple threads simultaneously without worrying about synchronization.

use regex_automata::{dfa::regex::Regex, util::lazy::Lazy, Match};

static RE: Lazy<Regex> = Lazy::new(|| Regex::new("foo[0-9]+bar").unwrap());

let expected = Some(Match::must(0, 3..14));
assert_eq!(expected, RE.find(b"zzzfoo12345barzzz"));

Implementations

impl<T, F> Lazy<T, F>

pub const fn new(create: F) -> Lazy<T, F>

Create a new Lazy value that is initialized via the given function.

The T type is automatically inferred from the return type of the create function given.

impl<T, F: Fn() -> T> Lazy<T, F>

pub fn get(this: &Lazy<T, F>) -> &T

Return a reference to the lazily initialized value.

This routine may block if another thread is initializing a T.

Note that given a x which has type Lazy, this must be called via Lazy::get(x) and not x.get(). This routine is defined this way because Lazy impls Deref with a target of T.

Panics

This panics if the create function inside this lazy value panics. If the panic occurred in another thread, then this routine may also panic (but is not guaranteed to do so).

Trait Implementations

impl<T: Debug, F: Fn() -> T> Debug for Lazy<T, F>

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

Formats the value using the given formatter.

impl<T, F: Fn() -> T> Deref for Lazy<T, F>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.