Struct ExclusiveCell

pub struct ExclusiveCell<T>
where
    T: ?Sized,
{ /* private fields */ }

A synchronization primitive which can be accessed only once.

This type is a thread-safe cell, and can be used in statics. ExclusiveCell provides a mutable reference to the contents without RAII guards, but only on the first try.

Relation with other types

ExclusiveCell is complementary to OnceCell with regards to Mutex and RwLock:

C	Mutex	RwLock	OnceCell	ExclusiveCell
&C provides	MutexGuard	RwLock{Read,Write}Guard	&T	&mut

A OnceCell can be emulated using a RwLock by only ever calling try_read and leaking the RwLockReadGuard. Similarily, ExclusiveCell can be emulated using a RwLock by only ever calling try_write and leaking the RwLockWriteGuard.

In contrast to OnceCell but similarly to Mutex and RwLock, the contents of a ExclusiveCell have to be initialized at creation.

Similarities with cortex_m::singleton

ExclusiveCell can be used similarily to cortex_m::singleton to create a mutable reference to a statically allocated value. In contrast to cortex_m::singleton, ExclusiveCell is thread safe and does not require using macros.

Examples

use exclusive_cell::ExclusiveCell;

static EXCLUSIVE_CELL: ExclusiveCell<usize> = ExclusiveCell::new(5);

let number = EXCLUSIVE_CELL.take().unwrap();
assert_eq!(number, &mut 5);

assert!(EXCLUSIVE_CELL.take().is_none());

Implementations

impl<T> ExclusiveCell<T>

pub const fn new(val: T) -> ExclusiveCell<T>

Creates a new ExclusiveCell containing the given value.

Examples

use exclusive_cell::ExclusiveCell;

let exclusive_cell = ExclusiveCell::new(5);

pub fn into_inner(self) -> T

Unwraps the value.

Examples

use exclusive_cell::ExclusiveCell;

let exclusive_cell = ExclusiveCell::new(5);
let number = exclusive_cell.into_inner();

assert_eq!(number, 5);

impl<T> ExclusiveCell<T>

where T: ?Sized,

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

Takes the mutable reference to the wrapped value.

Only the first call returns Some. All subsequent calls return None.

Examples

use exclusive_cell::ExclusiveCell;

let exclusive_cell = ExclusiveCell::new(5);

let number = exclusive_cell.take().unwrap();
assert_eq!(number, &mut 5);

assert!(exclusive_cell.take().is_none());

pub fn is_taken(&self) -> bool

Returns true if the mutable reference has been taken.

Examples

use exclusive_cell::ExclusiveCell;

let exclusive_cell = ExclusiveCell::new(5);
assert!(!exclusive_cell.is_taken());

let number = exclusive_cell.take().unwrap();
assert!(exclusive_cell.is_taken());

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

Returns a mutable reference to the underlying data.

Since this method borrows ExclusiveCell mutably, it is statically guaranteed that no borrows to the underlying data exists.

Examples

use exclusive_cell::ExclusiveCell;

let mut exclusive_cell = ExclusiveCell::new(5);

let number = exclusive_cell.get_mut();
assert_eq!(number, &mut 5);

assert!(!exclusive_cell.is_taken());

Trait Implementations

impl<T> Debug for ExclusiveCell<T>

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<T> Default for ExclusiveCell<T>

where T: Default,

fn default() -> ExclusiveCell<T>

Returns the “default value” for a type.

impl<T> From<T> for ExclusiveCell<T>

fn from(value: T) -> ExclusiveCell<T>

Converts to this type from the input type.

impl<T> Send for ExclusiveCell<T>

where T: Send + ?Sized,

impl<T> Sync for ExclusiveCell<T>

where T: Send + ?Sized,