Control.Monad.Class.MonadSTM

This module corresponds to Control.Monad.STM in "stm" package

Documentation

class (Monad m, Monad (STM m)) => MonadSTM m where

The STM primitives parametrised by a monad m.

Minimal complete definition

atomically, newTVar, readTVar, writeTVar, retry, orElse, newTMVar, newEmptyTMVar, takeTMVar, tryTakeTMVar, putTMVar, tryPutTMVar, readTMVar, tryReadTMVar, swapTMVar, isEmptyTMVar, newTQueue, readTQueue, tryReadTQueue, peekTQueue, tryPeekTQueue, flushTQueue, writeTQueue, isEmptyTQueue, unGetTQueue, newTBQueue, readTBQueue, tryReadTBQueue, peekTBQueue, tryPeekTBQueue, flushTBQueue, writeTBQueue, lengthTBQueue, isEmptyTBQueue, isFullTBQueue, unGetTBQueue, newTSem, waitTSem, signalTSem, signalTSemN, newTChan, newBroadcastTChan, dupTChan, cloneTChan, readTChan, tryReadTChan, peekTChan, tryPeekTChan, writeTChan, unGetTChan, isEmptyTChan

Associated Types

type STM m = (stm :: Type -> Type) | stm -> m

The STM monad.

Methods

atomically :: HasCallStack => STM m a -> m a

Atomically run an STM computation.

See atomically.

retry :: STM m a

See retry.

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

See orElse.

check :: Bool -> STM m ()

See check.

Instances

MonadSTM IO

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

type STM IO = (stm :: Type -> Type)

type TVar IO :: Type -> Type

type TMVar IO :: Type -> Type

type TQueue IO :: Type -> Type

type TBQueue IO :: Type -> Type

type TArray IO :: Type -> Type -> Type

type TSem IO

type TChan IO :: Type -> Type

Methods

atomically :: HasCallStack => STM IO a -> IO a

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

readTVar :: TVar IO a -> STM IO a

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

retry :: STM IO a

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

modifyTVar :: TVar IO a -> (a -> a) -> STM IO ()

modifyTVar' :: TVar IO a -> (a -> a) -> STM IO ()

stateTVar :: TVar IO s -> (s -> (a, s)) -> STM IO a

swapTVar :: TVar IO a -> a -> STM IO a

check :: Bool -> STM IO ()

newTMVar :: a -> STM IO (TMVar IO a)

newEmptyTMVar :: STM IO (TMVar IO a)

takeTMVar :: TMVar IO a -> STM IO a

tryTakeTMVar :: TMVar IO a -> STM IO (Maybe a)

putTMVar :: TMVar IO a -> a -> STM IO ()

tryPutTMVar :: TMVar IO a -> a -> STM IO Bool

readTMVar :: TMVar IO a -> STM IO a

tryReadTMVar :: TMVar IO a -> STM IO (Maybe a)

swapTMVar :: TMVar IO a -> a -> STM IO a

isEmptyTMVar :: TMVar IO a -> STM IO Bool

newTQueue :: STM IO (TQueue IO a)

readTQueue :: TQueue IO a -> STM IO a

tryReadTQueue :: TQueue IO a -> STM IO (Maybe a)

peekTQueue :: TQueue IO a -> STM IO a

tryPeekTQueue :: TQueue IO a -> STM IO (Maybe a)

flushTQueue :: TQueue IO a -> STM IO [a]

writeTQueue :: TQueue IO a -> a -> STM IO ()

isEmptyTQueue :: TQueue IO a -> STM IO Bool

unGetTQueue :: TQueue IO a -> a -> STM IO ()

newTBQueue :: Natural -> STM IO (TBQueue IO a)

readTBQueue :: TBQueue IO a -> STM IO a

tryReadTBQueue :: TBQueue IO a -> STM IO (Maybe a)

peekTBQueue :: TBQueue IO a -> STM IO a

tryPeekTBQueue :: TBQueue IO a -> STM IO (Maybe a)

flushTBQueue :: TBQueue IO a -> STM IO [a]

writeTBQueue :: TBQueue IO a -> a -> STM IO ()

lengthTBQueue :: TBQueue IO a -> STM IO Natural

isEmptyTBQueue :: TBQueue IO a -> STM IO Bool

isFullTBQueue :: TBQueue IO a -> STM IO Bool

unGetTBQueue :: TBQueue IO a -> a -> STM IO ()

newTSem :: Integer -> STM IO (TSem IO)

waitTSem :: TSem IO -> STM IO ()

signalTSem :: TSem IO -> STM IO ()

signalTSemN :: Natural -> TSem IO -> STM IO ()

newTChan :: STM IO (TChan IO a)

newBroadcastTChan :: STM IO (TChan IO a)

dupTChan :: TChan IO a -> STM IO (TChan IO a)

cloneTChan :: TChan IO a -> STM IO (TChan IO a)

readTChan :: TChan IO a -> STM IO a

tryReadTChan :: TChan IO a -> STM IO (Maybe a)

peekTChan :: TChan IO a -> STM IO a

tryPeekTChan :: TChan IO a -> STM IO (Maybe a)

writeTChan :: TChan IO a -> a -> STM IO ()

unGetTChan :: TChan IO a -> a -> STM IO ()

isEmptyTChan :: TChan IO a -> STM IO Bool

newTVarIO :: a -> IO (TVar IO a)

readTVarIO :: TVar IO a -> IO a

newTMVarIO :: a -> IO (TMVar IO a)

newEmptyTMVarIO :: IO (TMVar IO a)

newTQueueIO :: IO (TQueue IO a)

newTBQueueIO :: Natural -> IO (TBQueue IO a)

newTChanIO :: IO (TChan IO a)

newBroadcastTChanIO :: IO (TChan IO a)

MonadSTM m => MonadSTM (ReaderT r m)

The underlying stm monad is also transformed.

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

type STM (ReaderT r m) = (stm :: Type -> Type)

type TVar (ReaderT r m) :: Type -> Type

type TMVar (ReaderT r m) :: Type -> Type

type TQueue (ReaderT r m) :: Type -> Type

type TBQueue (ReaderT r m) :: Type -> Type

type TArray (ReaderT r m) :: Type -> Type -> Type

type TSem (ReaderT r m)

type TChan (ReaderT r m) :: Type -> Type

Methods

atomically :: HasCallStack => STM (ReaderT r m) a -> ReaderT r m a

newTVar :: a -> STM (ReaderT r m) (TVar (ReaderT r m) a)

readTVar :: TVar (ReaderT r m) a -> STM (ReaderT r m) a

writeTVar :: TVar (ReaderT r m) a -> a -> STM (ReaderT r m) ()

retry :: STM (ReaderT r m) a

orElse :: STM (ReaderT r m) a -> STM (ReaderT r m) a -> STM (ReaderT r m) a

modifyTVar :: TVar (ReaderT r m) a -> (a -> a) -> STM (ReaderT r m) ()

modifyTVar' :: TVar (ReaderT r m) a -> (a -> a) -> STM (ReaderT r m) ()

stateTVar :: TVar (ReaderT r m) s -> (s -> (a, s)) -> STM (ReaderT r m) a

swapTVar :: TVar (ReaderT r m) a -> a -> STM (ReaderT r m) a

check :: Bool -> STM (ReaderT r m) ()

newTMVar :: a -> STM (ReaderT r m) (TMVar (ReaderT r m) a)

newEmptyTMVar :: STM (ReaderT r m) (TMVar (ReaderT r m) a)

takeTMVar :: TMVar (ReaderT r m) a -> STM (ReaderT r m) a

tryTakeTMVar :: TMVar (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

putTMVar :: TMVar (ReaderT r m) a -> a -> STM (ReaderT r m) ()

tryPutTMVar :: TMVar (ReaderT r m) a -> a -> STM (ReaderT r m) Bool

readTMVar :: TMVar (ReaderT r m) a -> STM (ReaderT r m) a

tryReadTMVar :: TMVar (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

swapTMVar :: TMVar (ReaderT r m) a -> a -> STM (ReaderT r m) a

isEmptyTMVar :: TMVar (ReaderT r m) a -> STM (ReaderT r m) Bool

newTQueue :: STM (ReaderT r m) (TQueue (ReaderT r m) a)

readTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) a

tryReadTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

peekTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) a

tryPeekTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

flushTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) [a]

writeTQueue :: TQueue (ReaderT r m) a -> a -> STM (ReaderT r m) ()

isEmptyTQueue :: TQueue (ReaderT r m) a -> STM (ReaderT r m) Bool

unGetTQueue :: TQueue (ReaderT r m) a -> a -> STM (ReaderT r m) ()

newTBQueue :: Natural -> STM (ReaderT r m) (TBQueue (ReaderT r m) a)

readTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) a

tryReadTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

peekTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) a

tryPeekTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

flushTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) [a]

writeTBQueue :: TBQueue (ReaderT r m) a -> a -> STM (ReaderT r m) ()

lengthTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) Natural

isEmptyTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) Bool

isFullTBQueue :: TBQueue (ReaderT r m) a -> STM (ReaderT r m) Bool

unGetTBQueue :: TBQueue (ReaderT r m) a -> a -> STM (ReaderT r m) ()

newTSem :: Integer -> STM (ReaderT r m) (TSem (ReaderT r m))

waitTSem :: TSem (ReaderT r m) -> STM (ReaderT r m) ()

signalTSem :: TSem (ReaderT r m) -> STM (ReaderT r m) ()

signalTSemN :: Natural -> TSem (ReaderT r m) -> STM (ReaderT r m) ()

newTChan :: STM (ReaderT r m) (TChan (ReaderT r m) a)

newBroadcastTChan :: STM (ReaderT r m) (TChan (ReaderT r m) a)

dupTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) (TChan (ReaderT r m) a)

cloneTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) (TChan (ReaderT r m) a)

readTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) a

tryReadTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

peekTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) a

tryPeekTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) (Maybe a)

writeTChan :: TChan (ReaderT r m) a -> a -> STM (ReaderT r m) ()

unGetTChan :: TChan (ReaderT r m) a -> a -> STM (ReaderT r m) ()

isEmptyTChan :: TChan (ReaderT r m) a -> STM (ReaderT r m) Bool

newTVarIO :: a -> ReaderT r m (TVar (ReaderT r m) a)

readTVarIO :: TVar (ReaderT r m) a -> ReaderT r m a

newTMVarIO :: a -> ReaderT r m (TMVar (ReaderT r m) a)

newEmptyTMVarIO :: ReaderT r m (TMVar (ReaderT r m) a)

newTQueueIO :: ReaderT r m (TQueue (ReaderT r m) a)

newTBQueueIO :: Natural -> ReaderT r m (TBQueue (ReaderT r m) a)

newTChanIO :: ReaderT r m (TChan (ReaderT r m) a)

newBroadcastTChanIO :: ReaderT r m (TChan (ReaderT r m) a)

throwSTM :: (MonadSTM m, MonadThrow (STM m), Exception e) => e -> STM m a

throwIO specialised to stm monad.

non standard extensions

The non standard extensions include MonadLabelledSTM and MonadTraceSTM / MonadInspectSTM. For IO these are all no-op, however they greatly enhance IOSim capabilities. They are not only useful for debugging concurrency issues, but also to write testable properties.

class MonadSTM m => MonadLabelledSTM m

Labelled TVars & friends.

The IO instances is no-op, the IOSim instance enhances simulation trace. This is very useful when analysing low lever concurrency issues (e.g. deadlocks, livelocks etc).

Minimal complete definition

labelTVar

Instances

MonadLabelledSTM IO

noop instance

Defined in Control.Monad.Class.MonadSTM.Internal

Methods

labelTVar :: TVar IO a -> String -> STM IO ()

labelTMVar :: TMVar IO a -> String -> STM IO ()

labelTQueue :: TQueue IO a -> String -> STM IO ()

labelTBQueue :: TBQueue IO a -> String -> STM IO ()

labelTArray :: (Ix i, Show i) => TArray IO i e -> String -> STM IO ()

labelTSem :: TSem IO -> String -> STM IO ()

labelTChan :: TChan IO a -> String -> STM IO ()

labelTVarIO :: TVar IO a -> String -> IO ()

labelTMVarIO :: TMVar IO a -> String -> IO ()

labelTQueueIO :: TQueue IO a -> String -> IO ()

labelTBQueueIO :: TBQueue IO a -> String -> IO ()

labelTArrayIO :: (Ix i, Show i) => TArray IO i e -> String -> IO ()

labelTSemIO :: TSem IO -> String -> IO ()

labelTChanIO :: TChan IO a -> String -> IO ()

class MonadInspectSTM m => MonadTraceSTM m where

MonadTraceSTM allows to trace values of stm variables when stm transaction is committed. This allows to verify invariants when a variable is committed.

Minimal complete definition

traceTVar, traceTQueue, traceTBQueue

Methods

traceTVar

Arguments

:: proxy m

-> TVar m a

-> (Maybe a -> a -> InspectMonad m TraceValue)

callback which receives initial value or Nothing (if it is a newly created TVar), and the committed value.

-> STM m ()

Construct a trace output out of previous & new value of a TVar. The callback is called whenever an stm transaction which modifies the TVar is committed.

This is supported by IOSim (and IOSimPOR); IO has a trivial instance.

The simplest example is:

traceTVar (Proxy @m) tvar (\_ -> TraceString . show)

Note that the interpretation of TraceValue depends on the monad m itself (see TraceValue).

traceTMVar :: proxy m -> TMVar m a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad m TraceValue) -> STM m ()

default traceTMVar :: TMVar m a ~ TMVarDefault m a => proxy m -> TMVar m a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad m TraceValue) -> STM m ()

traceTQueue :: proxy m -> TQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> STM m ()

traceTBQueue :: proxy m -> TBQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> STM m ()

traceTSem :: proxy m -> TSem m -> (Maybe Integer -> Integer -> InspectMonad m TraceValue) -> STM m ()

default traceTSem :: TSem m ~ TSemDefault m => proxy m -> TSem m -> (Maybe Integer -> Integer -> InspectMonad m TraceValue) -> STM m ()

traceTVarIO :: TVar m a -> (Maybe a -> a -> InspectMonad m TraceValue) -> m ()

default traceTVarIO :: TVar m a -> (Maybe a -> a -> InspectMonad m TraceValue) -> m ()

traceTMVarIO :: TMVar m a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad m TraceValue) -> m ()

default traceTMVarIO :: TMVar m a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad m TraceValue) -> m ()

traceTQueueIO :: TQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> m ()

default traceTQueueIO :: TQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> m ()

traceTBQueueIO :: TBQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> m ()

default traceTBQueueIO :: TBQueue m a -> (Maybe [a] -> [a] -> InspectMonad m TraceValue) -> m ()

traceTSemIO :: TSem m -> (Maybe Integer -> Integer -> InspectMonad m TraceValue) -> m ()

default traceTSemIO :: TSem m -> (Maybe Integer -> Integer -> InspectMonad m TraceValue) -> m ()

Instances

MonadTraceSTM IO

noop instance

Defined in Control.Monad.Class.MonadSTM.Internal

Methods

traceTVar :: proxy IO -> TVar IO a -> (Maybe a -> a -> InspectMonad IO TraceValue) -> STM IO ()

traceTMVar :: proxy IO -> TMVar IO a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad IO TraceValue) -> STM IO ()

traceTQueue :: proxy IO -> TQueue IO a -> (Maybe [a] -> [a] -> InspectMonad IO TraceValue) -> STM IO ()

traceTBQueue :: proxy IO -> TBQueue IO a -> (Maybe [a] -> [a] -> InspectMonad IO TraceValue) -> STM IO ()

traceTSem :: proxy IO -> TSem IO -> (Maybe Integer -> Integer -> InspectMonad IO TraceValue) -> STM IO ()

traceTVarIO :: TVar IO a -> (Maybe a -> a -> InspectMonad IO TraceValue) -> IO ()

traceTMVarIO :: TMVar IO a -> (Maybe (Maybe a) -> Maybe a -> InspectMonad IO TraceValue) -> IO ()

traceTQueueIO :: TQueue IO a -> (Maybe [a] -> [a] -> InspectMonad IO TraceValue) -> IO ()

traceTBQueueIO :: TBQueue IO a -> (Maybe [a] -> [a] -> InspectMonad IO TraceValue) -> IO ()

traceTSemIO :: TSem IO -> (Maybe Integer -> Integer -> InspectMonad IO TraceValue) -> IO ()

data TraceValue where

A GADT which instructs how to trace the value. The traceDynamic will use dynamic tracing, e.g. "Control.Monad.IOSim.traceM"; while traceString will be traced with EventSay. The IOSims dynamic tracing allows to recover the value from the simulation trace (see "Control.Monad.IOSim.selectTraceEventsDynamic").

Constructors

TraceValue

Fields

• :: forall tr. Typeable tr
• => { traceDynamic :: Maybe tr
•    , traceString :: Maybe String
•    } -> TraceValue

Bundled Patterns

pattern TraceDynamic :: () => forall tr. Typeable tr => tr -> TraceValue

Use only a dynamic tracer.

pattern TraceString :: String -> TraceValue

Use only string tracing.

pattern DontTrace :: TraceValue

Do not trace the value.

class (MonadSTM m, Monad (InspectMonad m)) => MonadInspectSTM m where

This type class is indented for 'io-sim', where one might want to access a TVar in the underlying ST monad.

Associated Types

type InspectMonad m :: Type -> Type

Methods

inspectTVar :: proxy m -> TVar m a -> InspectMonad m a

Return the value of a TVar as an InspectMonad computation.

inspectTVar is useful if the value of a TVar observed by traceTVar contains other TVars.

inspectTMVar :: proxy m -> TMVar m a -> InspectMonad m (Maybe a)

Return the value of a MonadSTM as an InspectMonad computation.

Instances

MonadInspectSTM IO

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

type InspectMonad IO :: Type -> Type

Methods

inspectTVar :: proxy IO -> TVar IO a -> InspectMonad IO a

inspectTMVar :: proxy IO -> TMVar IO a -> InspectMonad IO (Maybe a)