Struct OnceCell

Source

pub struct OnceCell<T> { /* private fields */ }

Expand description

A cell that is written at most once.

set publishes a value with one compare-and-swap and never waits. It fails with SetError::InitializingError while an asynchronous initializer holds the turn.
get_or_init_racy lets every caller that finds the cell empty build a value; one compare-and-swap publishes one of them and the others are dropped.
get_or_init and get_or_try_init run one initializer at a time; the others wait for it as futures. An initializer that fails or is dropped passes the turn to the next waiter.

use nuclei::sync::{OnceCell, SetError};

static NAME: OnceCell<String> = OnceCell::const_new();
assert!(NAME.set("first".to_owned()).is_ok());
assert_eq!(
    NAME.set("second".to_owned()),
    Err(SetError::AlreadyInitializedError("second".to_owned()))
);
assert_eq!(NAME.get_or_init_racy(|| "unused".to_owned()), "first");

Implementations§

Source §

impl<T> OnceCell<T>

Source

pub const fn new() -> Self

An empty cell.

Source

pub const fn const_new() -> Self

An empty cell, usable in a static.

Source

pub fn new_with(value: Option<T>) -> Self

A cell that holds value if there is one, and is empty otherwise.

Source

pub const fn const_new_with(value: T) -> Self

A cell that already holds value, usable in a static.

Source

pub fn initialized(&self) -> bool

Whether the cell holds a value.

Source

pub fn get(&self) -> Option<&T>

The value, once published.

Source

pub fn get_mut(&mut self) -> Option<&mut T>

The value, borrowed mutably.

Source

pub fn into_inner(self) -> Option<T>

Consumes the cell and returns its value, if it has one.

Source

pub fn take(&mut self) -> Option<T>

Takes the value out of the cell, leaving it empty and ready to be set again. None if the cell is empty.

Source

pub fn set(&self, value: T) -> Result<(), SetError<T>>

Publishes value unless the cell already holds one or a task is initializing it, in which case value comes back in the error. One compare-and-swap publishes; never waits. A successful publish also releases any task waiting in get_or_init.

§Errors

SetError::AlreadyInitializedError when the cell holds a value, SetError::InitializingError when an initializer holds the turn.

Source

pub fn get_or_init_racy(&self, init: impl FnOnce() -> T) -> &T

The value, building one with init if the cell is empty. Callers that race all build; one value is published and the rest are dropped. Never waits. A racing builder does not take the turn, so it also wins over an initializer that is running: that one’s value is dropped when it finishes.

Source

pub async fn get_or_init<F, Fut>(&self, f: F) -> &T
where F: FnOnce() -> Fut, Fut: Future<Output = T>,

The value, running f to build it if the cell is empty. One initializer runs at a time; the rest wait. f is called only by the task that holds the turn, and not at all if the cell is full by then.

If the future f returns is dropped or panics, the attempt is cancelled and the next waiter makes its own.

This waits for ever if f tries to initialize the cell recursively.

Source

pub async fn get_or_try_init<E, F, Fut>(&self, f: F) -> Result<&T, E>
where F: FnOnce() -> Fut, Fut: Future<Output = Result<T, E>>,

The value, running f to build it if the cell is empty. One initializer runs at a time; when it fails, its error is returned and the next waiter tries its own.

If the future f returns is dropped or panics, the attempt is cancelled and the next waiter makes its own.

This waits for ever if f tries to initialize the cell recursively.