Struct OnceCell

source

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

Expand description

A cell which can be written to only once.

This allows initialization using an async closure that borrows from its environment.

use std::rc::Rc;
use std::sync::Arc;
use async_once_cell::OnceCell;

let non_send_value = Rc::new(4);
let shared = Arc::new(OnceCell::new());

let value : &i32 = shared.get_or_init(async {
    *non_send_value
}).await;
assert_eq!(value, &4);

// A second init is not called
let second = shared.get_or_init(async {
    unreachable!()
}).await;
assert_eq!(second, &4);

Implementations§

source §

impl<T> OnceCell<T>

source

pub const fn new() -> Self

Creates a new empty cell.

source

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

Creates a new cell with the given contents.

source

pub async fn get_or_init(&self, init: impl Future<Output = T>) -> &T

Gets the contents of the cell, initializing it with init if the cell was empty.

Many tasks may call get_or_init concurrently with different initializing futures, but it is guaranteed that only one future will be executed as long as the resulting future is polled to completion.

If init panics, the panic is propagated to the caller, and the cell remains uninitialized.

If the Future returned by this function is dropped prior to completion, the cell remains uninitialized, and another init function will be started (if any are available).

Attempting to reentrantly initialize the cell from init will generally cause a deadlock; the reentrant call will immediately yield and wait for the pending initialization. If the actual initialization can complete despite this (for example, by polling multiple futures and discarding incomplete ones instead of polling them to completion), then the cell will successfully be initialized.

source

pub async fn get_or_try_init<E>( &self, init: impl Future<Output = Result<T, E>>, ) -> Result<&T, E>

Gets the contents of the cell, initializing it with init if the cell was empty. If the cell was empty and init failed, an error is returned.

Many tasks may call get_or_init and/or get_or_try_init concurrently with different initializing futures, but it is guaranteed that only one of the futures will be executed as long as the resulting future is polled to completion.

If init panics or returns an error, the panic or error is propagated to the caller, and the cell remains uninitialized. In this case, another init function from a concurrent caller will be selected to execute, if one is available.

If the Future returned by this function is dropped prior to completion, the cell remains uninitialized, and another init function will be started (if any are available).

Attempting to reentrantly initialize the cell from init will generally cause a deadlock; the reentrant call will immediately yield and wait for the pending initialization. If the actual initialization can complete despite this (for example, by polling multiple futures and discarding incomplete ones instead of polling them to completion), then the cell will successfully be initialized.

source