Struct waitcell::WaitCell

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

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 dereference 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>

#[must_use]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.

#[must_use]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.

#[must_use]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.

#[must_use]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.

#[must_use]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.

#[must_use]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.

#[must_use]pub fn into_inner(self) -> Option<T>

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

impl<T: Default> WaitCell<T>

#[must_use]pub fn with_default() -> Self

Constructs a default-initialized WaitCell value.

Attempts to dereference this value will not block.

Trait Implementations

impl<T> AsRef<T> for WaitCell<T>

pub fn as_ref(&self) -> &T

Performs the conversion.

impl<T> Debug for WaitCell<T>

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

Formats the value using the given formatter.

impl<T> Default for WaitCell<T>

pub fn default() -> Self

Returns the "default value" for a type.

impl<T> Deref for WaitCell<T>

type Target = T

The resulting type after dereferencing.

pub fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> Drop for WaitCell<T>

pub fn drop(&mut self)

Executes the destructor for this type.

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

pub fn from(value: T) -> Self

Performs the conversion.

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