Struct tokio::sync::OnceCell

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

A thread-safe cell which can be written to only once.

Provides the functionality to either set the value, in case OnceCell is uninitialized, or get the already initialized value by using an async function via OnceCell::get_or_init.

Examples

use tokio::sync::OnceCell;

async fn some_computation() -> u32 {
    1 + 1
}

static ONCE: OnceCell<u32> = OnceCell::const_new();

#[tokio::main]
async fn main() {
    let result1 = ONCE.get_or_init(some_computation).await;
    assert_eq!(*result1, 2);
}

Implementations

impl<T> OnceCell<T>

pub fn new() -> Self

Creates a new uninitialized OnceCell instance.

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

Creates a new initialized OnceCell instance if value is Some, otherwise has the same functionality as OnceCell::new.

pub fn initialized(&self) -> bool

Whether the value of the OnceCell is set or not.

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

Tries to get a reference to the value of the OnceCell.

Returns None if the value of the OnceCell hasn’t previously been initialized.

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

Tries to return a mutable reference to the value of the cell.

Returns None if the cell hasn’t previously been initialized.

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

Sets the value of the OnceCell to the argument value.

If the value of the OnceCell was already set prior to this call then SetError::AlreadyInitializedError is returned. If another thread is initializing the cell while this method is called, SetError::InitializingError is returned. In order to wait for an ongoing initialization to finish, call OnceCell::get_or_init instead.

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

Tries to initialize the value of the OnceCell using the async function f. If the value of the OnceCell was already initialized prior to this call, a reference to that initialized value is returned. If some other thread initiated the initialization prior to this call and the initialization hasn’t completed, this call waits until the initialization is finished.

This will deadlock if f tries to initialize the cell itself.

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

Tries to initialize the value of the OnceCell using the async function f. If the value of the OnceCell was already initialized prior to this call, a reference to that initialized value is returned. If some other thread initiated the initialization prior to this call and the initialization hasn’t completed, this call waits until the initialization is finished. If the function argument f returns an error, get_or_try_init returns that error, otherwise the result of f will be stored in the cell.

This will deadlock if f tries to initialize the cell itself.

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

Moves the value out of the cell, destroying the cell in the process.

Returns None if the cell is uninitialized.

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

Takes ownership of the current value, leaving the cell uninitialized.

Returns None if the cell is uninitialized.

Trait Implementations

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

fn clone(&self) -> OnceCell<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T> Default for OnceCell<T>

fn default() -> OnceCell<T>

Returns the “default value” for a type.

impl<T> Drop for OnceCell<T>

fn drop(&mut self)

Executes the destructor for this type.

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

fn from(value: T) -> Self

Performs the conversion.

impl<T: PartialEq> PartialEq<OnceCell<T>> for OnceCell<T>

fn eq(&self, other: &OnceCell<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: Eq> Eq for OnceCell<T>

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

impl<T: Sync + Send> Sync for OnceCell<T>