pub struct OnceCell<T> { /* private fields */ }
Available on crate feature sync only.
Expand description

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

Creates a new empty OnceCell instance.

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

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

Available on crate feature parking_lot only.

Creates a new empty OnceCell instance.

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

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);
}

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

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

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.

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.

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.

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.

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

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

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Executes the destructor for this type. Read more

Converts to this type from the input type.

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

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Converts to this type from the input type.

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more