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§
source§impl<T> OnceCell<T>
impl<T> OnceCell<T>
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.
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);
}
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_with(value: T) -> Self
pub 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);
}
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
pub async fn get_or_init<F, Fut>(&self, f: F) -> &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>
pub async fn get_or_try_init<E, F, Fut>(&self, f: F) -> 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§
source§impl<T: PartialEq> PartialEq for OnceCell<T>
impl<T: PartialEq> PartialEq for OnceCell<T>
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> !Freeze for OnceCell<T>
impl<T> !RefUnwindSafe for OnceCell<T>
impl<T> Unpin for OnceCell<T>where
T: Unpin,
impl<T> !UnwindSafe for OnceCell<T>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)