io-classes-1.5.0.0: Type classes for concurrency with STM, ST and timing
Safe HaskellSafe-Inferred
LanguageHaskell2010

Control.Monad.Class.MonadSTM

Description

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

Synopsis

Documentation

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

The STM primitives parametrised by a monad m.

Associated Types

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

The STM monad.

Methods

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

Atomically run an STM computation.

See atomically.

retry :: STM m a Source #

See retry.

orElse :: STM m a -> STM m a -> STM m a Source #

See orElse.

check :: Bool -> STM m () Source #

See check.

Instances

Instances details
MonadSTM IO Source # 
Instance details

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

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

type TVar IO :: Type -> Type Source #

type TMVar IO :: Type -> Type Source #

type TQueue IO :: Type -> Type Source #

type TBQueue IO :: Type -> Type Source #

type TArray IO :: Type -> Type -> Type Source #

type TSem IO Source #

type TChan IO :: Type -> Type Source #

Methods

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

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

readTVar :: TVar IO a -> STM IO a Source #

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

retry :: STM IO a Source #

orElse :: STM IO a -> STM IO a -> STM IO a Source #

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

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

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

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

check :: Bool -> STM IO () Source #

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

newEmptyTMVar :: STM IO (TMVar IO a) Source #

takeTMVar :: TMVar IO a -> STM IO a Source #

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

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

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

readTMVar :: TMVar IO a -> STM IO a Source #

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

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

writeTMVar :: TMVar IO a -> a -> STM IO () Source #

isEmptyTMVar :: TMVar IO a -> STM IO Bool Source #

newTQueue :: STM IO (TQueue IO a) Source #

readTQueue :: TQueue IO a -> STM IO a Source #

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

peekTQueue :: TQueue IO a -> STM IO a Source #

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

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

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

isEmptyTQueue :: TQueue IO a -> STM IO Bool Source #

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

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

readTBQueue :: TBQueue IO a -> STM IO a Source #

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

peekTBQueue :: TBQueue IO a -> STM IO a Source #

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

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

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

lengthTBQueue :: TBQueue IO a -> STM IO Natural Source #

isEmptyTBQueue :: TBQueue IO a -> STM IO Bool Source #

isFullTBQueue :: TBQueue IO a -> STM IO Bool Source #

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

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

waitTSem :: TSem IO -> STM IO () Source #

signalTSem :: TSem IO -> STM IO () Source #

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

newTChan :: STM IO (TChan IO a) Source #

newBroadcastTChan :: STM IO (TChan IO a) Source #

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

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

readTChan :: TChan IO a -> STM IO a Source #

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

peekTChan :: TChan IO a -> STM IO a Source #

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

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

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

isEmptyTChan :: TChan IO a -> STM IO Bool Source #

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

readTVarIO :: TVar IO a -> IO a Source #

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

newEmptyTMVarIO :: IO (TMVar IO a) Source #

newTQueueIO :: IO (TQueue IO a) Source #

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

newTChanIO :: IO (TChan IO a) Source #

newBroadcastTChanIO :: IO (TChan IO a) Source #

MonadSTM m => MonadSTM (ReaderT r m) Source #

The underlying stm monad is also transformed.

Instance details

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

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

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

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

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

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

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

type TSem (ReaderT r m) Source #

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

Methods

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

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

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

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

retry :: STM (ReaderT r m) a Source #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

writeTMVar :: TMVar (ReaderT r m) a -> a -> STM (ReaderT r m) () Source #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Source #

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

Instances details
MonadLabelledSTM IO Source #

noop instance

Instance details

Defined in Control.Monad.Class.MonadSTM.Internal

class MonadInspectSTM m => MonadTraceSTM m where Source #

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 Source #

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 () Source #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Instances

Instances details
MonadTraceSTM IO Source #

noop instance

Instance details

Defined in Control.Monad.Class.MonadSTM.Internal

Methods

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

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

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

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

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

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

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

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

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

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

data TraceValue where Source #

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

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 Source #

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 Source #

Methods

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

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) Source #

Return the value of a MonadSTM as an InspectMonad computation.

Instances

Instances details
MonadInspectSTM IO Source # 
Instance details

Defined in Control.Monad.Class.MonadSTM.Internal

Associated Types

type InspectMonad IO :: Type -> Type Source #

Methods

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

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