Control.Monad.STM.Class

This module provides an abstraction over STM, which can be used with MonadConc.

This module only defines the STM class; you probably want to import Control.Concurrent.Classy.STM (which exports Control.Monad.STM.Class).

Deviations: An instance of MonadSTM is not required to be an Alternative, MonadPlus, and MonadFix, unlike STM. The always and alwaysSucceeds functions are not provided; if you need these file an issue and I'll look into it.

Documentation

class MonadCatch stm => MonadSTM stm where

MonadSTM is an abstraction over STM.

This class does not provide any way to run transactions, rather each MonadConc has an associated MonadSTM from which it can atomically run a transaction.

Minimal complete definition

retry, orElse, (newTVar | newTVarN), readTVar, writeTVar

Associated Types

type TVar stm :: * -> *

The mutable reference type. These behave like TVars, in that they always contain a value and updates are non-blocking and synchronised.

Methods

retry :: stm a

Retry execution of this transaction because it has seen values in TVars that it shouldn't have. This will result in the thread running the transaction being blocked until any TVars referenced in it have been mutated.

orElse :: stm a -> stm a -> stm a

Run the first transaction and, if it retrys, run the second instead. If the monad is an instance of 'Alternative'/'MonadPlus', orElse should be the '(|)'/'mplus' function.

newTVar :: a -> stm (TVar stm a)

Create a new TVar containing the given value.

newTVar = newTVarN ""

newTVarN :: String -> a -> stm (TVar stm a)

Create a new TVar containing the given value, but it is given a name which may be used to present more useful debugging information.

If an empty name is given, a counter starting from 0 is used. If names conflict, successive TVars with the same name are given a numeric suffix, counting up from 1.

newTVarN _ = newTVar

readTVar :: TVar stm a -> stm a

Return the current value stored in a TVar.

writeTVar :: TVar stm a -> a -> stm ()

Write the supplied value into the TVar.

Instances

MonadSTM STM

Associated Types

type TVar (STM :: * -> *) :: * -> *

Methods

retry :: STM a

orElse :: STM a -> STM a -> STM a

newTVar :: a -> STM (TVar STM a)

newTVarN :: String -> a -> STM (TVar STM a)

readTVar :: TVar STM a -> STM a

writeTVar :: TVar STM a -> a -> STM ()

MonadSTM stm => MonadSTM (StateT s stm)

Associated Types

type TVar (StateT s stm :: * -> *) :: * -> *

Methods

retry :: StateT s stm a

orElse :: StateT s stm a -> StateT s stm a -> StateT s stm a

newTVar :: a -> StateT s stm (TVar (StateT s stm) a)

newTVarN :: String -> a -> StateT s stm (TVar (StateT s stm) a)

readTVar :: TVar (StateT s stm) a -> StateT s stm a

writeTVar :: TVar (StateT s stm) a -> a -> StateT s stm ()

MonadSTM stm => MonadSTM (StateT s stm)

Associated Types

type TVar (StateT s stm :: * -> *) :: * -> *

Methods

retry :: StateT s stm a

orElse :: StateT s stm a -> StateT s stm a -> StateT s stm a

newTVar :: a -> StateT s stm (TVar (StateT s stm) a)

newTVarN :: String -> a -> StateT s stm (TVar (StateT s stm) a)

readTVar :: TVar (StateT s stm) a -> StateT s stm a

writeTVar :: TVar (StateT s stm) a -> a -> StateT s stm ()

(MonadSTM stm, Monoid w) => MonadSTM (WriterT w stm)

Associated Types

type TVar (WriterT w stm :: * -> *) :: * -> *

Methods

retry :: WriterT w stm a

orElse :: WriterT w stm a -> WriterT w stm a -> WriterT w stm a

newTVar :: a -> WriterT w stm (TVar (WriterT w stm) a)

newTVarN :: String -> a -> WriterT w stm (TVar (WriterT w stm) a)

readTVar :: TVar (WriterT w stm) a -> WriterT w stm a

writeTVar :: TVar (WriterT w stm) a -> a -> WriterT w stm ()

(MonadSTM stm, Monoid w) => MonadSTM (WriterT w stm)

Associated Types

type TVar (WriterT w stm :: * -> *) :: * -> *

Methods

retry :: WriterT w stm a

orElse :: WriterT w stm a -> WriterT w stm a -> WriterT w stm a

newTVar :: a -> WriterT w stm (TVar (WriterT w stm) a)

newTVarN :: String -> a -> WriterT w stm (TVar (WriterT w stm) a)

readTVar :: TVar (WriterT w stm) a -> WriterT w stm a

writeTVar :: TVar (WriterT w stm) a -> a -> WriterT w stm ()

MonadSTM stm => MonadSTM (IdentityT * stm)

Associated Types

type TVar (IdentityT * stm :: * -> *) :: * -> *

Methods

retry :: IdentityT * stm a

orElse :: IdentityT * stm a -> IdentityT * stm a -> IdentityT * stm a

newTVar :: a -> IdentityT * stm (TVar (IdentityT * stm) a)

newTVarN :: String -> a -> IdentityT * stm (TVar (IdentityT * stm) a)

readTVar :: TVar (IdentityT * stm) a -> IdentityT * stm a

writeTVar :: TVar (IdentityT * stm) a -> a -> IdentityT * stm ()

MonadSTM stm => MonadSTM (ReaderT * r stm)

Associated Types

type TVar (ReaderT * r stm :: * -> *) :: * -> *

Methods

retry :: ReaderT * r stm a

orElse :: ReaderT * r stm a -> ReaderT * r stm a -> ReaderT * r stm a

newTVar :: a -> ReaderT * r stm (TVar (ReaderT * r stm) a)

newTVarN :: String -> a -> ReaderT * r stm (TVar (ReaderT * r stm) a)

readTVar :: TVar (ReaderT * r stm) a -> ReaderT * r stm a

writeTVar :: TVar (ReaderT * r stm) a -> a -> ReaderT * r stm ()

(MonadSTM stm, Monoid w) => MonadSTM (RWST r w s stm)

Associated Types

type TVar (RWST r w s stm :: * -> *) :: * -> *

Methods

retry :: RWST r w s stm a

orElse :: RWST r w s stm a -> RWST r w s stm a -> RWST r w s stm a

newTVar :: a -> RWST r w s stm (TVar (RWST r w s stm) a)

newTVarN :: String -> a -> RWST r w s stm (TVar (RWST r w s stm) a)

readTVar :: TVar (RWST r w s stm) a -> RWST r w s stm a

writeTVar :: TVar (RWST r w s stm) a -> a -> RWST r w s stm ()

(MonadSTM stm, Monoid w) => MonadSTM (RWST r w s stm)

Associated Types

type TVar (RWST r w s stm :: * -> *) :: * -> *

Methods

retry :: RWST r w s stm a

orElse :: RWST r w s stm a -> RWST r w s stm a -> RWST r w s stm a

newTVar :: a -> RWST r w s stm (TVar (RWST r w s stm) a)

newTVarN :: String -> a -> RWST r w s stm (TVar (RWST r w s stm) a)

readTVar :: TVar (RWST r w s stm) a -> RWST r w s stm a

writeTVar :: TVar (RWST r w s stm) a -> a -> RWST r w s stm ()

check :: MonadSTM stm => Bool -> stm ()

Check whether a condition is true and, if not, call retry.

throwSTM :: (MonadSTM stm, Exception e) => e -> stm a

Throw an exception. This aborts the transaction and propagates the exception.

catchSTM :: (MonadSTM stm, Exception e) => stm a -> (e -> stm a) -> stm a

Handling exceptions from throwSTM.

Utilities for instance writers

liftedOrElse :: (MonadTransControl t, MonadSTM stm) => (forall x. StT t x -> x) -> t stm a -> t stm a -> t stm a

Given a function to remove the transformer-specific state, lift an orElse invocation.