Struct `OnceCell`

struct OnceCell<T> { ... }

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

A OnceCell is typically used for global variables that need to be initialized once on first use, but need no further changes. The OnceCell in Tokio allows the initialization procedure to be asynchronous.

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 result = ONCE.get_or_init(some_computation).await;
    assert_eq!(*result, 2);
}

It is often useful to write a wrapper method for accessing the value.

use tokio::sync::OnceCell;

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

async fn get_global_integer() -> &'static u32 {
    ONCE.get_or_init(|| async {
        1 + 1
    }).await
}

#[tokio::main]
async fn main() {
    let result = get_global_integer().await;
    assert_eq!(*result, 2);
}

Implementations

`impl<T> OnceCell<T>`

fn new() -> Self

Creates a new empty OnceCell instance.

const fn const_new() -> Self

Creates a new empty OnceCell instance.

Equivalent to OnceCell::new, except that it can be used in static variables.

When using the tracing unstable feature, a OnceCell created with const_new will not be instrumented. As such, it will not be visible in tokio-console. Instead, OnceCell::new should be used to create an instrumented object if that is needed.

Example

use tokio::sync::OnceCell;

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

async fn get_global_integer() -> &'static u32 {
    ONCE.get_or_init(|| async {
        1 + 1
    }).await
}

#[tokio::main]
async fn main() {
    let result = get_global_integer().await;
    assert_eq!(*result, 2);
}

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

Creates a new OnceCell that contains the provided value, if any.

If the Option is None, this is equivalent to OnceCell::new.

const fn const_new_with(value: T) -> Self

Creates a new OnceCell that contains the provided value.

Example

When using the tracing unstable feature, a OnceCell created with const_new_with will not be instrumented. As such, it will not be visible in tokio-console. Instead, OnceCell::new_with should be used to create an instrumented object if that is needed.

use tokio::sync::OnceCell;

static ONCE: OnceCell<u32> = OnceCell::const_new_with(1);

async fn get_global_integer() -> &'static u32 {
    ONCE.get_or_init(|| async {
        1 + 1
    }).await
}

#[tokio::main]
async fn main() {
    let result = get_global_integer().await;
    assert_eq!(*result, 1);
}

fn initialized(self: &Self) -> bool

Returns true if the OnceCell currently contains a value, and false otherwise.

fn get(self: &Self) -> Option<&T>

Returns a reference to the value currently stored in the OnceCell, or None if the OnceCell is empty.

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

Returns a mutable reference to the value currently stored in the OnceCell, or None if the OnceCell is empty.

Since this call borrows the OnceCell mutably, it is safe to mutate the value inside the OnceCell — the mutable borrow statically guarantees no other references exist.

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

Sets the value of the OnceCell to the given value if the OnceCell is empty.

If the OnceCell already has a value, this call will fail with an SetError::AlreadyInitializedError.

If the OnceCell is empty, but some other task is currently trying to set the value, this call will fail with SetError::InitializingError.

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

Gets the value currently in the OnceCell, or initialize it with the given asynchronous operation.

If some other task is currently working on initializing the OnceCell, this call will wait for that other task to finish, then return the value that the other task produced.

If the provided operation is cancelled or panics, the initialization attempt is cancelled. If there are other tasks waiting for the value to be initialized, one of them will start another attempt at initializing the value.

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

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

Gets the value currently in the OnceCell, or initialize it with the given asynchronous operation.

If some other task is currently working on initializing the OnceCell, this call will wait for that other task to finish, then return the value that the other task produced.

If the provided operation returns an error, is cancelled or panics, the initialization attempt is cancelled. If there are other tasks waiting for the value to be initialized, one of them will start another attempt at initializing the value.

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

fn into_inner(self: Self) -> Option<T>

Takes the value from the cell, destroying the cell in the process. Returns None if the cell is empty.

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

Takes ownership of the current value, leaving the cell empty. Returns None if the cell is empty.

`impl<T> Any for OnceCell<T>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for OnceCell<T>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for OnceCell<T>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for OnceCell<T>`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> Default for OnceCell<T>`

fn default() -> OnceCell<T>

`impl<T> Drop for OnceCell<T>`

fn drop(self: &mut Self)

`impl<T> Freeze for OnceCell<T>`

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

fn from(value: T) -> Self

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

fn from(t: T) -> T: Returns the argument unchanged.

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

fn from(t: never) -> T

`impl<T> RefUnwindSafe for OnceCell<T>`

`impl<T> ToOwned for OnceCell<T>`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T> Unpin for OnceCell<T>`

`impl<T> UnsafeUnpin for OnceCell<T>`

`impl<T> UnwindSafe for OnceCell<T>`

`impl<T, U> Into for OnceCell<T>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for OnceCell<T>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for OnceCell<T>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

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

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

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

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

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

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

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

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

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