Struct Once 

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

A thread-safe cell which can be written to only once.

This structure provides safe initialization for values that might be accessed concurrently by multiple threads. It ensures that the initialization logic runs only once, even if multiple threads attempt to initialize the value simultaneously.

It uses atomic operations and parking_lot’s futex-based synchronization for efficient blocking when necessary.

Implementations

impl<T> Once<T>

pub const fn new() -> Self

Creates a new, uninitialized Once cell.

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

Creates a new Once cell that is already initialized with the given value.

pub fn is_done(&self) -> bool

Checks if the cell has been initialized.

This method never blocks.

pub fn get(&self) -> Option<&T>

Returns a reference to the contained value if initialized.

Returns None if the cell is uninitialized or currently being initialized. This method never blocks.

pub fn get_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the contained value if initialized.

Returns None if the cell is uninitialized or currently being initialized. This method requires exclusive access (&mut self) and never blocks.

pub fn try_set(&self, value: T) -> Result<&T, T>

Attempts to initialize the cell with value without blocking.

• If the cell is uninitialized and not locked, initializes it with value and returns Ok(&value).
• If the cell is already initialized, returns Err(value).
• If the cell is currently locked by another thread, returns Err(value).

pub fn replace_mut(&mut self, value: T) -> Option<T>

Replaces the cell’s value, returning the old value if initialized.

• If uninitialized, sets the value to value and returns None.
• If initialized, replaces the existing value with value and returns the old value.

Requires exclusive access (&mut self), so it never blocks.

pub fn get_mut_or_set(&mut self, value: T) -> &mut T

Gets a mutable reference, initializing with value if needed.

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, initializes it with value and returns a mutable reference.

Requires exclusive access (&mut self), so it never blocks.

pub fn get_mut_or_default(&mut self) -> &mut T

where T: Default,

Gets a mutable reference, initializing with Default::default() if needed.

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, initializes it with T::default() and returns a mutable reference.

Requires exclusive access (&mut self), so it never blocks.

pub unsafe fn get_unchecked(&self) -> &T

Returns a reference to the value without checking if it’s initialized.

Safety

Calling this method on an uninitialized Once cell is undefined behavior. The caller must ensure the cell is initialized, e.g., by calling is_done() or get().

pub unsafe fn get_unchecked_mut(&mut self) -> &mut T

Returns a mutable reference to the value without checking if it’s initialized.

Safety

Calling this method on an uninitialized Once cell is undefined behavior. The caller must ensure the cell is initialized and that they have exclusive access.

pub fn take(&mut self) -> Option<T>

Takes the value out of the cell, leaving it uninitialized.

Returns Some(value) if the cell was initialized, None otherwise. Requires exclusive access (&mut self), so it never blocks.

pub fn set(&self, value: T) -> Result<(), T>

Initializes the cell with value. Blocks if another thread is initializing.

• If uninitialized, initializes it with value and returns Ok(()).
• If already initialized, returns Err(value).

Guarantees the cell is initialized upon return, but not necessarily with value if another thread completed initialization first.

pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>

Initializes the cell with value if uninitialized, returning a reference. Blocks if needed.

• If uninitialized, initializes with value and returns Ok(&value).
• If already initialized, returns Err((&current_value, value)).

Guarantees the cell is initialized upon return.

pub fn get_or_init<F>(&self, f: F) -> &T

where F: FnOnce() -> T,

Gets the value, initializing with f() if needed. Blocks if needed.

• If initialized, returns a reference to the existing value.
• If uninitialized, calls f(), stores the result, and returns a reference.

If multiple threads call this concurrently, only one f() execution happens.

pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut T

where F: FnOnce() -> T,

Gets a mutable reference, initializing with f() if needed.

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, calls f(), stores the result, and returns a mutable reference.

Requires exclusive access (&mut self), so it never blocks.

pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>

where F: FnOnce() -> Result<T, E>,

Gets the value, initializing with fallible f() if needed. Blocks if needed.

• If initialized, returns Ok(&value).
• If uninitialized, calls f():
  • On Ok(value), initializes the cell and returns Ok(&value).
  • On Err(e), returns Err(e) and leaves the cell uninitialized.

If multiple threads call this concurrently, only one f() execution happens.

pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>

where F: FnOnce() -> Result<T, E>,

Gets a mutable reference, initializing with fallible f() if needed.

• If initialized, returns Ok(&mut value).
• If uninitialized, calls f():
  • On Ok(value), initializes the cell and returns Ok(&mut value).
  • On Err(e), returns Err(e) and leaves the cell uninitialized.

Requires exclusive access (&mut self), so it never blocks (initialization happens inline).

pub async fn get_or_init_async<F, Fut>(&self, f: F) -> &T

where F: FnOnce() -> Fut, Fut: Future<Output = T>,

Gets the value, initializing asynchronously with f() if needed. Blocks if needed.

• If initialized, returns a reference to the existing value.
• If uninitialized, awaits f(), stores the result, and returns a reference.

If multiple tasks call this concurrently, only one f() execution happens.

pub async fn get_mut_or_init_async<F, Fut>(&mut self, f: F) -> &mut T

where F: FnOnce() -> Fut, Fut: Future<Output = T>,

Gets a mutable reference, initializing asynchronously with f() if needed.

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, awaits f(), stores the result, and returns a mutable reference.

Requires exclusive access (&mut self), so it never blocks (initialization happens inline).

pub async fn get_or_try_init_async<F, Fut, E>(&self, f: F) -> Result<&T, E>

where F: FnOnce() -> Fut, Fut: Future<Output = Result<T, E>>,

Gets the value, initializing asynchronously with fallible f() if needed. Blocks if needed.

• If initialized, returns Ok(&value).
• If uninitialized, awaits f():
  • On Ok(value), initializes the cell and returns Ok(&value).
  • On Err(e), returns Err(e) and leaves the cell uninitialized.

If multiple tasks call this concurrently, only one f() execution happens.

pub async fn get_mut_or_try_init_async<F, Fut, E>( &mut self, f: F, ) -> Result<&mut T, E>

where F: FnOnce() -> Fut, Fut: Future<Output = Result<T, E>>,

Gets a mutable reference, initializing asynchronously with fallible f() if needed.

• If initialized, returns Ok(&mut value).
• If uninitialized, awaits f():
  • On Ok(value), initializes the cell and returns Ok(&mut value).
  • On Err(e), returns Err(e) and leaves the cell uninitialized.

Requires exclusive access (&mut self), so it never blocks (initialization happens inline).

Trait Implementations

impl<T: Clone> Clone for Once<T>

fn clone(&self) -> Self

Clones the Once cell.

If the original cell is initialized, the clone will be initialized with a cloned value. If the original is uninitialized, the clone will also be uninitialized.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Once<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for Once<T>

fn default() -> Self

Creates a new, uninitialized Once cell.

impl<T: Display> Display for Once<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for Once<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<Option<T>> for Once<T>

fn from(value: Option<T>) -> Self

Creates an initialized Once from Some(value) or an uninitialized one from None.

impl<T> From<T> for Once<T>

fn from(value: T) -> Self

Creates a new, initialized Once cell from the given value.

impl<T: PartialEq> PartialEq for Once<T>

fn eq(&self, other: &Self) -> bool

Checks if two Once cells are equal.

They are equal if both are uninitialized, or if both are initialized and their contained values are equal according to PartialEq.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Eq> Eq for Once<T>

impl<T: Send> Send for Once<T>

impl<T: Sync + Send> Sync for Once<T>