Struct WaitCell

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

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§

Source§

impl<T> WaitCell<T>

Source

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.

Source

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

Constructs an initialized WaitCell value.

Attempts to dereference this value will not block.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

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

Source

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.

Source

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.
Source

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.

Source

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.

Source

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

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

Source

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.

Source

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.

Source

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.

Source

pub fn set_uninit(&mut self)

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

Source§

impl<T: Default> WaitCell<T>

Source

pub fn with_default() -> Self

Constructs a default-initialized WaitCell value.

Attempts to dereference this value will not block.

Trait Implementations§

Source§

impl<T> Debug for WaitCell<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<T> Default for WaitCell<T>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<T> Drop for WaitCell<T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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

Source§

fn from(value: T) -> Self

Converts to this type from the input type.
Source§

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

Auto Trait Implementations§

§

impl<T> !Freeze for WaitCell<T>

§

impl<T> !RefUnwindSafe for WaitCell<T>

§

impl<T> Send for WaitCell<T>
where T: Send,

§

impl<T> Unpin for WaitCell<T>
where T: Unpin,

§

impl<T> UnwindSafe for WaitCell<T>
where T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<!> for T

Source§

fn from(t: !) -> T

Converts to this type from the input type.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.