Struct stm_core::Transaction

pub struct Transaction { /* fields omitted */ }

Transaction tracks all the read and written variables.

It is used for checking vars, to ensure atomicity.

Methods

impl Transaction

pub fn with<T, F>(f: F) -> T where
    F: Fn(&mut Transaction) -> StmResult<T>, 

Run a function with a transaction.

It is equivalent to atomically.

pub fn with_control<T, F, C>(control: C, f: F) -> Option<T> where
    F: Fn(&mut Transaction) -> StmResult<T>,
    C: FnMut(StmError) -> TransactionControl, 

Run a function with a transaction.

with_control takes another control function, that can steer the control flow and possible terminate early.

control can react to counters, timeouts or external inputs.

It allows the user to fall back to another strategy, like a global lock in the case of too much contention.

Please not, that the transaction may still infinitely wait for changes when retry is called and control does not abort. If you need a timeout, another thread should signal this through a TVar.

pub fn read<T: Send + Sync + Any + Clone>(
    &mut self,
    var: &TVar<T>
) -> StmResult<T>

Read a variable and return the value.

The returned value is not always consistent with the current value of the var, but may be an outdated or or not yet commited value.

The used code should be capable of handling inconsistent states without running into infinite loops. Just the commit of wrong values is prevented by STM.

pub fn write<T: Any + Send + Sync + Clone>(
    &mut self,
    var: &TVar<T>,
    value: T
) -> StmResult<()>

Write a variable.

The write is not immediately visible to other threads, but atomically commited at the end of the computation.

pub fn or<T, F1, F2>(&mut self, first: F1, second: F2) -> StmResult<T> where
    F1: Fn(&mut Transaction) -> StmResult<T>,
    F2: Fn(&mut Transaction) -> StmResult<T>, 

Combine two calculations. When one blocks with retry, run the other, but don't commit the changes in the first.

If both block, Transaction::or still waits for TVars in both functions. Use Transaction::or instead of handling errors directly with the Result::or. The later does not handle all the blocking correctly.

Trait Implementations