Struct mitochondria::OnceCell

pub struct OnceCell<T>(_);

A mutable memory location that can be set only once.

This is useful to lazily build some value or to cache an expensive computation without the overhead of RefCell.

Usage

use mitochondria::OnceCell;

let c = OnceCell::new();

assert_eq!(c.as_ref(), None);

let value = c.init_once(|| "ribosome");

assert_eq!(value, &"ribosome");
assert_eq!(c.as_ref(), Some(&"ribosome"));

let value_again = c.init_once(|| "nucleolus");

assert_eq!(value_again, &"ribosome");

Reentrancy

To ensure that the cell is initialized only once in all its lifetime, if try_init_once or init_once are called reentranly from the f argument they take, the result of that reentrant call will be used and the return value of their caller f will be ignored.

use mitochondria::OnceCell;

let x = OnceCell::new();
let value = x.init_once(|| {
    x.init_once(|| "ribosome");
    "nucleolus"
});

assert_eq!(value, &"ribosome");
assert_eq!(x.as_ref(), Some(&"ribosome"));

let y = OnceCell::new();
let value = y.try_init_once::<(), _>(|| {
    let _ = y.try_init_once::<(), _>(|| Ok("ribosome"));
    Ok("nucleolus")
});

assert_eq!(value, Ok(&"ribosome"));
assert_eq!(y.as_ref(), Some(&"ribosome"));

let z = OnceCell::new();
let value = z.try_init_once::<(), _>(|| {
    z.init_once(|| "ribosome");
    Err(())
});
assert_eq!(value, Ok(&"ribosome"));
assert_eq!(z.as_ref(), Some(&"ribosome"));

Methods

impl<T> OnceCell<T>

fn new() -> Self

Creates a new OnceCell.

Examples

use mitochondria::OnceCell;

let c = OnceCell::<String>::new();

fn new_with_value(value: T) -> Self

Creates a new OnceCell initialised with value.

Examples

use mitochondria::OnceCell;

let c = OnceCell::new_with_value(Some("Hello vesicle!".to_owned()));

fn try_init_once<E, F>(&self, f: F) -> Result<&T, E> where F: FnOnce() -> Result<T, E>

Calls a function to try to initialize this cell.

If the cell was already-initialized, the function is not called. Otherwise, if the function returns Ok(value), the cell is initialized with value.

This method returns Err(error) if f was called and returned an error, or Ok(&value) otherwise.

Examples

use mitochondria::OnceCell;

let c = OnceCell::new();

assert_eq!(c.try_init_once(|| Err(())), Err(()));

let greeting = c.try_init_once::<(), _>(|| {
    Ok("Hello ribosome!".to_owned())
}).unwrap();

use mitochondria::OnceCell;

let c = OnceCell::new_with_value("Hello reticulum!".to_owned());

// Calls to `try_init_once` on initialized cells are ignored.
assert_eq!(
    c.try_init_once::<(), _>(|| Ok("Goodbye!".to_owned())).unwrap(),
    "Hello reticulum!");

fn as_ref(&self) -> Option<&T>

Returns None if the cell is not initialised, or else returns a reference to the value wrapped in Some.

Examples

use mitochondria::OnceCell;

let c = OnceCell::new();

assert!(c.as_ref().is_none());

let greeting = c.init_once(|| "Hello nucleus!".to_owned());
assert_eq!(c.as_ref(), Some(greeting));

fn as_mut(&mut self) -> Option<&mut T>

Returns None if the cell is not initialised, or else returns a mutable reference to the value wrapped in Some.

This call borrows OnceCell mutably (at compile-time) which guarantees that we possess the only reference.

Examples

use mitochondria::OnceCell;

let mut c = OnceCell::new();

assert!(c.as_mut().is_none());

c.init_once(|| "Nucleo".to_owned());
*c.as_mut().unwrap() += "lus!";
assert_eq!(c.as_ref().unwrap(), "Nucleolus!");

impl<T> OnceCell<T>

fn init_once<F>(&self, f: F) -> &T where F: FnOnce() -> T

Calls a function to initialize this cell and borrows its value.

If the cell was already-initialized, the function is not called and the returned value is the one that was already there.

Examples

use mitochondria::OnceCell;

let c = OnceCell::new();

let greeting: &str = c.init_once(|| "Hello ribosome!".to_owned());

use mitochondria::OnceCell;

let c = OnceCell::new_with_value("Hello reticulum!".to_owned());

// Calls to `init_once` on initialized cells are ignored.
assert_eq!(
    c.init_once(|| "Goodbye!".to_owned()),
    "Hello reticulum!");

Trait Implementations

impl<T> Send for OnceCell<T> where T: Send

impl<T: Clone> Clone for OnceCell<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for OnceCell<T>

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

Formats the value using the given formatter.

impl<T> Default for OnceCell<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> From<T> for OnceCell<T>

fn from(value: T) -> Self

Performs the conversion.