Struct tearor::TearCell

#[repr(transparent)]pub struct TearCell<T>(_);

TearCell is a minimally thread-safe cell type for anything that can meet the requirements of Pod.

By "minimally thread-safe", I mean that it's completely possible for TearCell to corrupt whatever you store in it, but that strictly speaking all reads and writes are atomic, and thus you have no undefined behavior. That said, writes and reads from the TearCell itself are not atomic.

It's intended for cases where T does not fit into an atomic type, you don't want to use a Mutex, and you happen to know that in practice data races aren't a concern. (For example, if synchronization is provided externally but in a way you can't prove, or you just don't really care).

Implementation details

Note: These are not part of TearCell's stability guarantee.

TearCell<T> wraps an UnsafeCell<T> and implements reads and writes by interpreting it as either a &[AtomicU$N], where $N is the largest implemented integer size available that meets T's size and alignment requirements.

For loads, we zero-init a target T, interpret it as a &mut [u$N], and perform relaxed loads from our atomics, and write the result into the buffer.

For stores, we interpret the provided value as a &[u$N], and perform a relaxed store into our atomic buffer for each value we read from it.

Implementations

impl<T> TearCell<T>

pub const fn new(v: T) -> Self

Create a new TearCell, wrapping v.

This should probably only be done if T: Pod, as it's almost entirely useless without it. However, putting a where T: Pod bound currently would mean TearCell::new can no longer be a const fn, which makes it drastically less useful.

pub fn into_inner(self) -> T

Unwraps the stored value.

impl<T: Pod> TearCell<T>

pub fn store(&self, value: T)

Store value into the cell. No guarantees of ordering or atomicity is provided for this write, only that it will not cause undefined behavior.

See also store_ref if T is large enough that you'd rather not copy it on the stack when you can avoid it.

pub fn load(&self) -> T

Read the value out of this cell. No guarantees of ordering or atomicity is provided for this write, only that it will not cause undefined behavior.

Specifically, the T returned may not be one ever written. See docs for more info.

pub fn store_ref(&self, value: &T)

Equivalent to store but takes the value by reference. No guarantees of ordering or atomicity is provided for this write, only that it will not cause undefined behavior.

Trait Implementations

impl<T: Pod + Send> Send for TearCell<T>

impl<T: Pod + Send> Sync for TearCell<T>