pub struct OnceCell<T> { /* private fields */ }
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
sourceimpl<T> OnceCell<T>
impl<T> OnceCell<T>
sourcepub fn new_with(value: Option<T>) -> Self
pub 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
.
sourcepub const fn const_new() -> Self
pub const fn const_new() -> Self
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);
}
sourcepub fn initialized(&self) -> bool
pub fn initialized(&self) -> bool
Returns true
if the OnceCell
currently contains a value, and false
otherwise.
sourcepub fn get(&self) -> Option<&T>
pub fn get(&self) -> Option<&T>
Returns a reference to the value currently stored in the OnceCell
, or
None
if the OnceCell
is empty.
sourcepub fn get_mut(&mut self) -> Option<&mut T>
pub fn get_mut(&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.
sourcepub fn set(&self, value: T) -> Result<(), SetError<T>>
pub fn set(&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
.
sourcepub async fn get_or_init<F, Fut>(&self, f: F) -> &T where
F: FnOnce() -> Fut,
Fut: Future<Output = T>,
pub async fn get_or_init<F, Fut>(&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.
sourcepub 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>>,
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>>,
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.
sourcepub fn into_inner(self) -> Option<T>
pub fn into_inner(self) -> Option<T>
Takes the value from the cell, destroying the cell in the process.
Returns None
if the cell is empty.
Trait Implementations
impl<T: Eq> Eq for OnceCell<T>
impl<T: Send> Send for OnceCell<T>
impl<T: Sync + Send> Sync for OnceCell<T>
Auto Trait Implementations
impl<T> !RefUnwindSafe for OnceCell<T>
impl<T> Unpin for OnceCell<T> where
T: Unpin,
impl<T> !UnwindSafe for OnceCell<T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more