Struct crossbeam_stm::Stm

pub struct Stm<T: 'static + Send + Sync> { /* fields omitted */ }

A Software Transactional Memory pointer.

Loads should always be constant-time, even in the face of both load and update contention.

Updates might take a long time, and the closure passed to it might run multiple times. This is because if the "old" value is updated before the closure finishes, the closure might overwrite up-to-date data and must be run again with said new data passed in. Additionally, memory reclamation of old STM values is performed at this point.

Sets take much longer than loads as well, but they should be approximately constant-time as they don't need to be re-run if a different thread sets the STM before it can finish.

Methods

impl<T: 'static + Send + Sync> Stm<T>

pub fn new(data: T) -> Stm<T>

Create a new STM pointer pointing to data.

Example

let stm = Stm::new(vec![1,2,3,4]);

pub fn update<F>(&self, f: F) where     F: Fn(&T) -> T,

Update the STM.

This is done by passing the current STM value to a closure and setting the STM to the closure's return value, provided no other threads have changed the STM in the meantime.

If you don't care about any other threads setting the STM during processing, use the set() method.

Example

let stm = Stm::new(vec![1,2,3,4]);
stm.update(|old| {
    let mut new = old.clone();
    new.push(5);
    new
})

pub fn update_fallible<F, E>(&self, f: F) -> Result<(), E> where     F: Fn(&T) -> Result<T, E>,

Update the STM in a fallible fashion.

pub fn update_no_reclaim<F>(&self, f: F) where     F: Fn(&T) -> T,

Update the STM without reclaiming any memory. Note that without calling reclaim() at some future point, this can cause a memory leak.

pub fn update_fallible_no_reclaim<F, E>(&self, f: F) -> Result<(), E> where     F: Fn(&T) -> Result<T, E>,

Update the STM in a fallible fashion without reclaiming any memory. Note that without calling reclaim() at some future point, this can cause a memory leak.

pub fn set(&self, data: T)

Update the STM, ignoring the current value.

Example

let stm = Stm::new(vec![1,2,3,4]);
stm.set(vec![9,8,7,6]);

pub fn set_no_reclaim(&self, data: T)

Update the STM, ignoring the current value and not reclaiming any memory. Note that without calling reclaim() at some future point, this can cause a memory leak.

pub fn reclaim(&self)

Reclaim memory after calling update_no_reclaim(), update_fallible_no_reclaim() or set_no_reclaim().

pub fn load(&self) -> StmGuard<T>

Load the current value from the STM.

This returns an STM guard, rather than returning the internal value directly. In order to access the value explicitly, it must be dereferenced.

Example

let stm = Stm::new(vec![1,2,3,4]);
let stm_guard = stm.load();
assert_eq!(*stm_guard, vec![1,2,3,4]);

Warning

This method returns a guard that will pin the current thread, but won't directly hold on to a particular value. This means that even though load() has been called, it's not a guarantee that the data won't change between dereferences. As an example,

let stm = Stm::new(vec![1,2,3,4]);
let guard = stm.load();
assert_eq!(*guard, vec![1,2,3,4]);
stm.set(vec![9,8,7,6]);
assert_eq!(*guard, vec![9,8,7,6]);

Trait Implementations

impl<T: 'static + Send + Sync + Debug> Debug for Stm<T>

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

Formats the value using the given formatter.

impl<T: 'static + Send + Sync + Display> Display for Stm<T>

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

Formats the value using the given formatter.

impl<T: 'static + Send + Sync> Drop for Stm<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: 'static + Send + Sync> Clone for Stm<T>

fn clone(&self) -> Stm<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.