Struct TOnce 

pub struct TOnce<P, T> { /* private fields */ }

A thread-safe cell which can be written to only once using a parameterized initializer.

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<P, T> TOnce<P, T>

pub const fn new(param: P) -> Self

Creates a new, uninitialized TOnce cell with the given parameter.

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

Creates a new TOnce cell that is already initialized with the given value, bypassing the parameter.

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, ignoring the parameter.

• 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, discards the parameter, 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, discards the parameter, 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, discards the parameter, 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 TOnce 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 TOnce cell is undefined behavior. The caller must ensure the cell is initialized and that they have exclusive access.

pub fn take(&mut self, param: P) -> Result<T, P>

Takes the value out of the cell, leaving it uninitialized with the given parameter.

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, ignoring the parameter. Blocks if another thread is initializing.

• If uninitialized, discards the parameter, 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, discards the parameter, 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(P) -> T,

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

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

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

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

where F: FnOnce(P) -> T,

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

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, calls f(param), 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(&P) -> Result<T, E>,

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

• If initialized, returns Ok(&value).
• If uninitialized, calls f(param):
  • 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(param) execution happens.

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

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

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

• If initialized, returns Ok(&mut value).
• If uninitialized, calls f(param):
  • 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(&P) -> Fut, Fut: Future<Output = T>,

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

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

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

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

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

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

• If initialized, returns a mutable reference to the existing value.
• If uninitialized, awaits f(param), 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(&P) -> Fut, Fut: Future<Output = Result<T, E>>,

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

• If initialized, returns Ok(&value).
• If uninitialized, awaits f(param):
  • 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(param) 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(&P) -> Fut, Fut: Future<Output = Result<T, E>>,

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

• If initialized, returns Ok(&mut value).
• If uninitialized, awaits f(param):
  • 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<P: Clone, T: Clone> Clone for TOnce<P, T>

fn clone(&self) -> Self

Clones the TOnce 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 with a cloned parameter.

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

Performs copy-assignment from source.

impl<P, T: Debug> Debug for TOnce<P, T>

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

Formats the value using the given formatter.

impl<P: Default, T> Default for TOnce<P, T>

fn default() -> Self

Creates a new, uninitialized TOnce cell with default parameter.

impl<P, T: Display> Display for TOnce<P, T>

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

Formats the value using the given formatter.

impl<P, T> Drop for TOnce<P, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<P, T> From<Option<T>> for TOnce<P, T>

where P: Default,

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

Creates an initialized TOnce from Some(value) or an uninitialized one from None with a default parameter.

impl<P, T> From<Result<T, P>> for TOnce<P, T>

fn from(value: Result<T, P>) -> Self

Creates an initialized TOnce from Ok(value) or an uninitialized one from Err(param) with the parameter.

impl<T> From<T> for TOnce<(), T>

fn from(value: T) -> Self

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

impl<P, T: PartialEq> PartialEq for TOnce<P, T>

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

Checks if two TOnce 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<P, T: Eq> Eq for TOnce<P, T>

impl<P: Send, T: Send> Send for TOnce<P, T>

impl<P: Sync + Send, T: Send> Sync for TOnce<P, T>