Module std::cell

Cells for sharing between threads: OnceCell, set once and then read from any thread without a lock, and CachePadded, which keeps a value on cache lines of its own so threads writing neighbouring values do not slow each other down (false sharing).

Source: std/cell.weir; committed interface: std/cell.iface. Index

struct OnceCell

pub struct OnceCell<T>: destruct unsafe portable(T) {
    /* private fields */
} drop with Free in home

A cell set at most once, then read from any thread without locking: lazy, thread-safe initialisation of a shared value.

One setter wins (OnceCell::try_set); readers see None from OnceCell::get until the value is published, and the value from then on. It is destroyed with the cell.

impl<T, r> OnceCell<T> in r

method new

pub fn new() -> OnceCell<T> in r with Alloc in r

An empty cell; allocates the value's slot, hence with Alloc.

Committed interface (std/cell.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method try_set

pub fn try_set(&self, v: T) -> Result<Unit, T>

Sets the cell to v, or hands v back as Err(v) when it is set (or being set) already. Never blocks: a losing setter returns at once.

Committed interface (std/cell.iface):

stores T in regions r

method set

pub fn set(&self, v: T) with Panic {panic: terminal}

Sets the cell to v; panics (with Panic) if it is set (or being set) already. Use OnceCell::try_set to get v back instead.

Committed interface (std/cell.iface):

bound Panic: Panic { panic: terminal } any
scheduling point: Panic not quiet
holds what may not move at a scheduling point: Panic not quiet
stores T in regions r

method get

pub fn get(&self) -> Option<&{self} T>

The value, once a setter has published it; None before (and while a setter is still writing it).

Committed interface (std/cell.iface): the signature alone.

impl<T> OnceCell<T>

method is_set

pub fn is_set(&self) -> Bool

Whether a setter has published the value: OnceCell::get answers Some from then on.

Committed interface (std/cell.iface): the signature alone.

enum CachePadded

pub enum CachePadded<T: linear>: forget copy align(128) {
    Padded(T),
}

A value on cache lines of its own: aligned to 128 bytes and sized to a multiple of 128, so no other value shares its line (or the adjacent line some CPUs prefetch with it).

Wrap a value that one thread writes often while others touch its neighbours, such as a per-thread counter in an array. A T of up to 120 bytes takes one 128-byte block. It is copied and destroyed as T is.

Variants:

impl<T: linear> CachePadded<T>

method new

pub fn new(v: T) -> CachePadded<T>

Wraps v.

Committed interface (std/cell.iface): the signature alone.

method get

pub fn get(&self) -> &T

Borrows the value.

Committed interface (std/cell.iface): the signature alone.

method get_mut

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

Borrows the value mutably.

Committed interface (std/cell.iface):

writes through self: everything

method into_inner

pub fn into_inner(self) -> T

Unwraps the value.

Committed interface (std/cell.iface): the signature alone.