Struct ExclusiveCell

pub struct ExclusiveCell<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) -> Self

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: ?Sized> ExclusiveCell<T>

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 + ?Sized> Debug for ExclusiveCell<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for ExclusiveCell<T>

fn default() -> Self

Returns the “default value” for a type.

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

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: ?Sized + Send> Send for ExclusiveCell<T>

impl<T: ?Sized + Send> Sync for ExclusiveCell<T>