pub struct OnceLock<T> { /* private fields */ }
Expand description
A synchronization primitive which can nominally be written to only once.
This type is a thread-safe OnceCell
, and can be used in statics.
In many simple cases, you can use LazyLock<T, F>
instead to get the benefits of this type
with less effort: LazyLock<T, F>
“looks like” &T
because it initializes with F
on deref!
Where OnceLock shines is when LazyLock is too simple to support a given case, as LazyLock
doesn’t allow additional inputs to its function after you call LazyLock::new(|| ...)
.
§Examples
Writing to a OnceLock
from a separate thread:
use std::sync::OnceLock;
static CELL: OnceLock<usize> = OnceLock::new();
// `OnceLock` has not been written to yet.
assert!(CELL.get().is_none());
// Spawn a thread and write to `OnceLock`.
std::thread::spawn(|| {
let value = CELL.get_or_init(|| 12345);
assert_eq!(value, &12345);
})
.join()
.unwrap();
// `OnceLock` now contains the value.
assert_eq!(
CELL.get(),
Some(&12345),
);
You can use OnceLock
to implement a type that requires “append-only” logic:
use std::sync::{OnceLock, atomic::{AtomicU32, Ordering}};
use std::thread;
struct OnceList<T> {
data: OnceLock<T>,
next: OnceLock<Box<OnceList<T>>>,
}
impl<T> OnceList<T> {
const fn new() -> OnceList<T> {
OnceList { data: OnceLock::new(), next: OnceLock::new() }
}
fn push(&self, value: T) {
// FIXME: this impl is concise, but is also slow for long lists or many threads.
// as an exercise, consider how you might improve on it while preserving the behavior
if let Err(value) = self.data.set(value) {
let next = self.next.get_or_init(|| Box::new(OnceList::new()));
next.push(value)
};
}
fn contains(&self, example: &T) -> bool
where
T: PartialEq,
{
self.data.get().map(|item| item == example).filter(|v| *v).unwrap_or_else(|| {
self.next.get().map(|next| next.contains(example)).unwrap_or(false)
})
}
}
// Let's exercise this new Sync append-only list by doing a little counting
static LIST: OnceList<u32> = OnceList::new();
static COUNTER: AtomicU32 = AtomicU32::new(0);
const LEN: u32 = 1000;
thread::scope(|s| {
for _ in 0..thread::available_parallelism().unwrap().get() {
s.spawn(|| {
while let i @ 0..LEN = COUNTER.fetch_add(1, Ordering::Relaxed) {
LIST.push(i);
}
});
}
});
for i in 0..LEN {
assert!(LIST.contains(&i));
}
Implementations§
source§impl<T> OnceLock<T>
impl<T> OnceLock<T>
1.70.0 · sourcepub fn get(&self) -> Option<&T>
pub fn get(&self) -> Option<&T>
Gets the reference to the underlying value.
Returns None
if the cell is empty, or being initialized. This
method never blocks.
1.70.0 · sourcepub fn get_mut(&mut self) -> Option<&mut T>
pub fn get_mut(&mut self) -> Option<&mut T>
Gets the mutable reference to the underlying value.
Returns None
if the cell is empty. This method never blocks.
sourcepub fn wait(&self) -> &T
🔬This is a nightly-only experimental API. (once_wait
#127527)
pub fn wait(&self) -> &T
once_wait
#127527)Blocks the current thread until the cell is initialized.
§Example
Waiting for a computation on another thread to finish:
1.70.0 · sourcepub fn set(&self, value: T) -> Result<(), T>
pub fn set(&self, value: T) -> Result<(), T>
Sets the contents of this cell to value
.
May block if another thread is currently attempting to initialize the cell. The cell is guaranteed to contain a value when set returns, though not necessarily the one provided.
Returns Ok(())
if the cell’s value was set by this call.
§Examples
sourcepub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
🔬This is a nightly-only experimental API. (once_cell_try_insert
#116693)
pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
once_cell_try_insert
#116693)Sets the contents of this cell to value
if the cell was empty, then
returns a reference to it.
May block if another thread is currently attempting to initialize the cell. The cell is guaranteed to contain a value when set returns, though not necessarily the one provided.
Returns Ok(&value)
if the cell was empty and Err(¤t_value, value)
if it was full.
§Examples
#![feature(once_cell_try_insert)]
use std::sync::OnceLock;
static CELL: OnceLock<i32> = OnceLock::new();
fn main() {
assert!(CELL.get().is_none());
std::thread::spawn(|| {
assert_eq!(CELL.try_insert(92), Ok(&92));
}).join().unwrap();
assert_eq!(CELL.try_insert(62), Err((&92, 62)));
assert_eq!(CELL.get(), Some(&92));
}
1.70.0 · sourcepub fn get_or_init<F>(&self, f: F) -> &Twhere
F: FnOnce() -> T,
pub fn get_or_init<F>(&self, f: F) -> &Twhere
F: FnOnce() -> T,
Gets the contents of the cell, initializing it with f
if the cell
was empty.
Many threads may call get_or_init
concurrently with different
initializing functions, but it is guaranteed that only one function
will be executed.
§Panics
If f
panics, the panic is propagated to the caller, and the cell
remains uninitialized.
It is an error to reentrantly initialize the cell from f
. The
exact outcome is unspecified. Current implementation deadlocks, but
this may be changed to a panic in the future.
§Examples
sourcepub fn get_mut_or_init<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
🔬This is a nightly-only experimental API. (once_cell_get_mut
#121641)
pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
once_cell_get_mut
#121641)sourcepub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
🔬This is a nightly-only experimental API. (once_cell_try
#109737)
pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
once_cell_try
#109737)Gets the contents of the cell, initializing it with f
if
the cell was empty. If the cell was empty and f
failed, an
error is returned.
§Panics
If f
panics, the panic is propagated to the caller, and
the cell remains uninitialized.
It is an error to reentrantly initialize the cell from f
.
The exact outcome is unspecified. Current implementation
deadlocks, but this may be changed to a panic in the future.
§Examples
sourcepub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
🔬This is a nightly-only experimental API. (once_cell_get_mut
#121641)
pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
once_cell_get_mut
#121641)Gets the mutable reference of the contents of the cell, initializing
it with f
if the cell was empty. If the cell was empty and f
failed,
an error is returned.
This method never blocks.
§Panics
If f
panics, the panic is propagated to the caller, and
the cell remains uninitialized.
§Examples
#![feature(once_cell_get_mut)]
use std::sync::OnceLock;
let mut cell: OnceLock<u32> = OnceLock::new();
// Failed initializers do not change the value
assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
assert!(cell.get().is_none());
let value = cell.get_mut_or_try_init(|| "1234".parse());
assert_eq!(value, Ok(&mut 1234));
*value.unwrap() += 2;
assert_eq!(cell.get(), Some(&1236))
1.70.0 · sourcepub fn into_inner(self) -> Option<T>
pub fn into_inner(self) -> Option<T>
Consumes the OnceLock
, returning the wrapped value. Returns
None
if the cell was empty.