Struct waitcell::WaitCell

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

A cell type containing a value which may not yet be available.

A WaitCell generally begins in an uninitialized state. While in this state, attempts to reference the value block until some other thread provides a value. While shared, a value can only be set at most once.

If you require the value to be set multiple times while shared, consider using RwLock instead. WaitCell is more performant than RwLock, however, as expensive atomic writes are not required to track readers and writers.

In asynchronous contexts, a type implementing Future should be used instead.

Example

See the crate-level documentation.

Implementations

impl<T> WaitCell<T>

pub const fn new() -> Self

Constructs an uninitialized WaitCell value.

Attempts to dereference this value will block until an initialization function such as init is invoked.

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

Constructs an initialized WaitCell value.

Attempts to dereference this value will not block.

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

Initializes the value, allowing dereferencing to proceed.

Panics

If the value is already initialized or is currently undergoing initialization. To conditionally initialize the value, consider using try_init.

pub fn try_init<F: FnOnce() -> T>(&self, func: F) -> bool

Conditionally initializes the value, allowing dereferencing to proceed.

Returns

• true – The value was initialized using func.
• false – The value is already initialized or is currently initializing. func was not invoked.

Panics

If func panics, the WaitCell remains uninitialized. Concurrent initialization attempts may fail.

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

Conditionally initializes the value or waits for the value to become available if it is not already so.

Panics

If func panics, the WaitCell remains uninitialized. Concurrent initialization attempts may fail.

Notes

func is only invoked in the case where the value is not currently initialized or undergoing initialization.

This function blocks if the value is currently undergoing initialization.

pub fn get(&self) -> &T

Waits for the value to become initialized and returns a reference to it.

Notes

This function will block until the value is initialized by another thread.

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

Returns a reference to the initialized value, or None if it is not yet initialized.

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

Sets the initialized value, returning a mutable reference to it.

The previous value, if any, is dropped.

pub fn unset(&mut self) -> bool

Drops the initialized value, if any. The value may be re-initialized again later.

Returns

• true - A value was present and was dropped.
• false - A value was not present.

pub fn is_set(&mut self) -> bool

Returns true if the value is currently initialized and false otherwise.

Notes

This method is only available when the WaitCell is exclusively borrowed. If the WaitCell is shared, consider using wait_cell.try_get().is_some() instead.

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

Returns a mutable reference to the initialized value, or None if the value is not initialized.

pub fn into_inner(self) -> Option<T>

Returns the initialized value, or None if the value is not initialized.

pub fn as_ptr(&self) -> *const T

Provides direct immutable access to the value.

Safety

The value may or may not be initialized and may or may not have concurrent immutable references. If a concurrent mutable reference exists, it was created unsafely.

pub fn as_mut_ptr(&mut self) -> *mut T

Provides direct mutable access to the value.

Safety

The value may or may not be initialized, but it is guaranteed to have no concurrent references except those created unsafely.

pub unsafe fn set_init(&mut self)

Directly sets the state of the value as initialized.

Safety

If the value is later accessed, it must actually have been initialized.

pub fn set_uninit(&mut self)

Directly clears the initialization state of the value, as if by core::mem::forget.

impl<T: Default> WaitCell<T>

pub fn with_default() -> Self

Constructs a default-initialized WaitCell value.

Attempts to dereference this value will not block.

Trait Implementations

impl<T> Debug for WaitCell<T>

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

Formats the value using the given formatter.

impl<T> Default for WaitCell<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for WaitCell<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<T> for WaitCell<T>

fn from(value: T) -> Self

Performs the conversion.

impl<T: Sync> Sync for WaitCell<T>