Safe Haskell	None
Language	Haskell2010

Control.Monad.IOSim

Contents

Simulation monad
- Run simulation
Simulation time
Simulation trace
Eventlog
Low-level API
Deprecated interfaces

Synopsis

data IOSim s a
type STMSim = STM
runSim :: forall a. (forall s. IOSim s a) -> Either Failure a
runSimOrThrow :: forall a. (forall s. IOSim s a) -> a
runSimStrictShutdown :: forall a. (forall s. IOSim s a) -> Either Failure a
data Failure
- = FailureException SomeException
- | FailureDeadlock
- | FailureSloppyShutdown [LabeledThread]
runSimTrace :: forall a. (forall s. IOSim s a) -> Trace a
runSimTraceST :: forall s a. IOSim s a -> ST s (Trace a)
liftST :: ST s a -> IOSim s a
traceM :: Typeable a => a -> IOSim s ()
setCurrentTime :: UTCTime -> IOSim s ()
unshareClock :: IOSim s ()
data Trace a
- = Trace !Time !ThreadId !(Maybe ThreadLabel) !TraceEvent (Trace a)
- | TraceMainReturn !Time a ![LabeledThread]
- | TraceMainException !Time SomeException ![LabeledThread]
- | TraceDeadlock !Time ![LabeledThread]
data TraceEvent
- = EventSay String
- | EventLog Dynamic
- | EventThrow SomeException
- | EventThrowTo SomeException ThreadId
- | EventThrowToBlocked
- | EventThrowToWakeup
- | EventThrowToUnmasked ThreadId
- | EventThreadForked ThreadId
- | EventThreadFinished
- | EventThreadUnhandled SomeException
- | EventTxCommitted [TVarId] [TVarId]
- | EventTxAborted
- | EventTxBlocked [TVarId]
- | EventTxWakeup [TVarId]
- | EventTimerCreated TimeoutId TVarId Time
- | EventTimerUpdated TimeoutId Time
- | EventTimerCancelled TimeoutId
- | EventTimerExpired TimeoutId
type ThreadLabel = String
data LabeledThread = LabeledThread {
- labeledThreadId :: ThreadId
- labeledThreadLabel :: Maybe ThreadLabel
}
traceEvents :: Trace a -> [(Time, ThreadId, Maybe ThreadLabel, TraceEvent)]
traceResult :: Bool -> Trace a -> Either Failure a
selectTraceEvents :: (TraceEvent -> Maybe b) -> Trace a -> [b]
selectTraceEventsDynamic :: forall a b. Typeable b => Trace a -> [b]
selectTraceEventsSay :: Trace a -> [String]
printTraceEventsSay :: Trace a -> IO ()
newtype EventlogEvent = EventlogEvent String
newtype EventlogMarker = EventlogMarker String
execReadTVar :: TVar s a -> ST s a
type SimM s = IOSim s
type SimSTM = STM

Simulation monad

data IOSim s a Source #

Instances

Instances details

Monad (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods (>>=) :: IOSim s a -> (a -> IOSim s b) -> IOSim s b # (>>) :: IOSim s a -> IOSim s b -> IOSim s b # return :: a -> IOSim s a #
Functor (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods fmap :: (a -> b) -> IOSim s a -> IOSim s b # (<$) :: a -> IOSim s b -> IOSim s a #
MonadFail (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods fail :: String -> IOSim s a #
Applicative (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods pure :: a -> IOSim s a # (<>) :: IOSim s (a -> b) -> IOSim s a -> IOSim s b # liftA2 :: (a -> b -> c) -> IOSim s a -> IOSim s b -> IOSim s c # (>) :: IOSim s a -> IOSim s b -> IOSim s b # (<*) :: IOSim s a -> IOSim s b -> IOSim s a #
MonadThrow (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods throwM :: Exception e => e -> IOSim s a #
MonadCatch (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods catch :: Exception e => IOSim s a -> (e -> IOSim s a) -> IOSim s a #
MonadMask (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods mask :: ((forall a. IOSim s a -> IOSim s a) -> IOSim s b) -> IOSim s b # uninterruptibleMask :: ((forall a. IOSim s a -> IOSim s a) -> IOSim s b) -> IOSim s b # generalBracket :: IOSim s a -> (a -> ExitCase b -> IOSim s c) -> (a -> IOSim s b) -> IOSim s (b, c) #
MonadAsync (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Associated Types type Async (IOSim s) :: Type -> Type Source # Methods async :: IOSim s a -> IOSim s (Async (IOSim s) a) Source # asyncThreadId :: Proxy (IOSim s) -> Async (IOSim s) a -> ThreadId (IOSim s) Source # withAsync :: IOSim s a -> (Async (IOSim s) a -> IOSim s b) -> IOSim s b Source # wait :: Async (IOSim s) a -> IOSim s a Source # poll :: Async (IOSim s) a -> IOSim s (Maybe (Either SomeException a)) Source # waitCatch :: Async (IOSim s) a -> IOSim s (Either SomeException a) Source # cancel :: Async (IOSim s) a -> IOSim s () Source # cancelWith :: Exception e => Async (IOSim s) a -> e -> IOSim s () Source # uninterruptibleCancel :: Async (IOSim s) a -> IOSim s () Source # waitAny :: [Async (IOSim s) a] -> IOSim s (Async (IOSim s) a, a) Source # waitAnyCatch :: [Async (IOSim s) a] -> IOSim s (Async (IOSim s) a, Either SomeException a) Source # waitAnyCancel :: [Async (IOSim s) a] -> IOSim s (Async (IOSim s) a, a) Source # waitAnyCatchCancel :: [Async (IOSim s) a] -> IOSim s (Async (IOSim s) a, Either SomeException a) Source # waitEither :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s (Either a b) Source # waitEitherCatch :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s (Either (Either SomeException a) (Either SomeException b)) Source # waitEitherCancel :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s (Either a b) Source # waitEitherCatchCancel :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s (Either (Either SomeException a) (Either SomeException b)) Source # waitEither_ :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s () Source # waitBoth :: Async (IOSim s) a -> Async (IOSim s) b -> IOSim s (a, b) Source # race :: IOSim s a -> IOSim s b -> IOSim s (Either a b) Source # race_ :: IOSim s a -> IOSim s b -> IOSim s () Source # concurrently :: IOSim s a -> IOSim s b -> IOSim s (a, b) Source # concurrently_ :: IOSim s a -> IOSim s b -> IOSim s () Source # asyncWithUnmask :: ((forall b. IOSim s b -> IOSim s b) -> IOSim s a) -> IOSim s (Async (IOSim s) a) Source #
MonadDelay (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods threadDelay :: DiffTime -> IOSim s () Source #
MonadTimer (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Associated Types data Timeout (IOSim s) Source # Methods newTimeout :: DiffTime -> IOSim s (Timeout (IOSim s)) Source # readTimeout :: Timeout (IOSim s) -> STM (IOSim s) TimeoutState Source # updateTimeout :: Timeout (IOSim s) -> DiffTime -> IOSim s () Source # cancelTimeout :: Timeout (IOSim s) -> IOSim s () Source # awaitTimeout :: Timeout (IOSim s) -> STM (IOSim s) Bool Source # registerDelay :: DiffTime -> IOSim s (TVar (IOSim s) Bool) Source # timeout :: DiffTime -> IOSim s a -> IOSim s (Maybe a) Source #
MonadMonotonicTime (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods getMonotonicTime :: IOSim s Time Source #
MonadTime (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods getCurrentTime :: IOSim s UTCTime Source #
MonadSTM (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Associated Types type STM (IOSim s) :: Type -> Type Source # Methods atomically :: HasCallStack => STM (IOSim s) a -> IOSim s a Source # newTVarIO :: a -> IOSim s (TVar (IOSim s) a) Source # newTMVarIO :: a -> IOSim s (TMVar (IOSim s) a) Source # newEmptyTMVarIO :: IOSim s (TMVar (IOSim s) a) Source # newTBQueueIO :: Natural -> IOSim s (TBQueue (IOSim s) a) Source #
MonadThrow (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods throwIO :: Exception e => e -> IOSim s a Source # bracket :: IOSim s a -> (a -> IOSim s b) -> (a -> IOSim s c) -> IOSim s c Source # bracket_ :: IOSim s a -> IOSim s b -> IOSim s c -> IOSim s c Source # finally :: IOSim s a -> IOSim s b -> IOSim s a Source #
MonadCatch (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods catch :: Exception e => IOSim s a -> (e -> IOSim s a) -> IOSim s a Source # catchJust :: Exception e => (e -> Maybe b) -> IOSim s a -> (b -> IOSim s a) -> IOSim s a Source # try :: Exception e => IOSim s a -> IOSim s (Either e a) Source # tryJust :: Exception e => (e -> Maybe b) -> IOSim s a -> IOSim s (Either b a) Source # handle :: Exception e => (e -> IOSim s a) -> IOSim s a -> IOSim s a Source # handleJust :: Exception e => (e -> Maybe b) -> (b -> IOSim s a) -> IOSim s a -> IOSim s a Source # onException :: IOSim s a -> IOSim s b -> IOSim s a Source # bracketOnError :: IOSim s a -> (a -> IOSim s b) -> (a -> IOSim s c) -> IOSim s c Source # generalBracket :: IOSim s a -> (a -> ExitCase b -> IOSim s c) -> (a -> IOSim s b) -> IOSim s (b, c) Source #
MonadMask (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods mask :: ((forall a. IOSim s a -> IOSim s a) -> IOSim s b) -> IOSim s b Source # uninterruptibleMask :: ((forall a. IOSim s a -> IOSim s a) -> IOSim s b) -> IOSim s b Source # mask_ :: IOSim s a -> IOSim s a Source # uninterruptibleMask_ :: IOSim s a -> IOSim s a Source #
MonadEvaluate (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods evaluate :: a -> IOSim s a Source #
MonadSay (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods say :: String -> IOSim s () Source #
MonadST (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods withLiftST :: (forall s0. (forall a. ST s0 a -> IOSim s a) -> b) -> b Source #
MonadThread (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Associated Types type ThreadId (IOSim s) Source # Methods myThreadId :: IOSim s (ThreadId (IOSim s)) Source # labelThread :: ThreadId (IOSim s) -> String -> IOSim s () Source #
MonadFork (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods forkIO :: IOSim s () -> IOSim s (ThreadId (IOSim s)) Source # forkIOWithUnmask :: ((forall a. IOSim s a -> IOSim s a) -> IOSim s ()) -> IOSim s (ThreadId (IOSim s)) Source # throwTo :: Exception e => ThreadId (IOSim s) -> e -> IOSim s () Source # killThread :: ThreadId (IOSim s) -> IOSim s () Source #
MonadEventlog (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods traceEventIO :: String -> IOSim s () Source # traceMarkerIO :: String -> IOSim s () Source #
type Async (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal type Async (IOSim s)
data Timeout (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal data Timeout (IOSim s) = Timeout !(TVar s TimeoutState) !(TVar s Bool) !TimeoutId \| NegativeTimeout !TimeoutId
type STM (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal type STM (IOSim s)
type ThreadId (IOSim s) Source #
Instance details Defined in Control.Monad.IOSim.Internal type ThreadId (IOSim s)

type STMSim = STM Source #

Run simulation

runSim :: forall a. (forall s. IOSim s a) -> Either Failure a Source #

IOSim is a pure monad.

runSimOrThrow :: forall a. (forall s. IOSim s a) -> a Source #

For quick experiments and tests it is often appropriate and convenient to simply throw failures as exceptions.

runSimStrictShutdown :: forall a. (forall s. IOSim s a) -> Either Failure a Source #

Like runSim but also fail if when the main thread terminates, there are other threads still running or blocked. If one is trying to follow a strict thread cleanup policy then this helps testing for that.

data Failure Source #

Simulation termination with failure

Constructors

FailureException SomeException	The main thread terminated with an exception
FailureDeadlock	The threads all deadlocked
FailureSloppyShutdown [LabeledThread]	The main thread terminated normally but other threads were still alive, and strict shutdown checking was requested. See `runSimStrictShutdown`

Instances

Instances details

Show Failure Source #
Instance details Defined in Control.Monad.IOSim Methods showsPrec :: Int -> Failure -> ShowS # show :: Failure -> String # showList :: [Failure] -> ShowS #
Exception Failure Source #
Instance details Defined in Control.Monad.IOSim Methods toException :: Failure -> SomeException # fromException :: SomeException -> Maybe Failure # displayException :: Failure -> String #

runSimTrace :: forall a. (forall s. IOSim s a) -> Trace a Source #

See runSimTraceST below.

runSimTraceST :: forall s a. IOSim s a -> ST s (Trace a) Source #

The most general method of running IOSim is in ST monad. One can recover failures or the result from Trace with traceResult, or access TraceEvents generated by the computation with traceEvents. A slightly more convenient way is exposed by runSimTrace.

liftST :: ST s a -> IOSim s a Source #

traceM :: Typeable a => a -> IOSim s () Source #

Simulation time

setCurrentTime :: UTCTime -> IOSim s () Source #

Set the current wall clock time for the thread's clock domain.

unshareClock :: IOSim s () Source #

Put the thread into a new wall clock domain, not shared with the parent thread. Changing the wall clock time in the new clock domain will not affect the other clock of other threads. All threads forked by this thread from this point onwards will share the new clock domain.

Simulation trace

data Trace a Source #

Trace is a recursive data type, it is the trace of a IOSim computation. The trace will contain information about thread sheduling, blocking on TVars, and other internal state changes of IOSim. More importantly it also supports traces generated by the computation with say (which corresponds to using putStrLn in IO), traceEventM, or dynamically typed traces with traceM (which generalise the base library traceM)

See also: traceEvents, traceResult, selectTraceEvents, selectTraceEventsDynamic and printTraceEventsSay.

Constructors

Trace !Time !ThreadId !(Maybe ThreadLabel) !TraceEvent (Trace a)
TraceMainReturn !Time a ![LabeledThread]
TraceMainException !Time SomeException ![LabeledThread]
TraceDeadlock !Time ![LabeledThread]

Instances

Instances details

Show a => Show (Trace a) Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods showsPrec :: Int -> Trace a -> ShowS # show :: Trace a -> String # showList :: [Trace a] -> ShowS #

data TraceEvent Source #

Constructors

EventSay String
EventLog Dynamic
EventThrow SomeException
EventThrowTo SomeException ThreadId
EventThrowToBlocked
EventThrowToWakeup
EventThrowToUnmasked ThreadId
EventThreadForked ThreadId
EventThreadFinished
EventThreadUnhandled SomeException
EventTxCommitted [TVarId] [TVarId]
EventTxAborted
EventTxBlocked [TVarId]
EventTxWakeup [TVarId]
EventTimerCreated TimeoutId TVarId Time
EventTimerUpdated TimeoutId Time
EventTimerCancelled TimeoutId
EventTimerExpired TimeoutId

Instances

Instances details

Show TraceEvent Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods showsPrec :: Int -> TraceEvent -> ShowS # show :: TraceEvent -> String # showList :: [TraceEvent] -> ShowS #

type ThreadLabel = String Source #

data LabeledThread Source #

Constructors

LabeledThread
Fields labeledThreadId :: ThreadId labeledThreadLabel :: Maybe ThreadLabel

Instances

Instances details

Eq LabeledThread Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods (==) :: LabeledThread -> LabeledThread -> Bool # (/=) :: LabeledThread -> LabeledThread -> Bool #
Ord LabeledThread Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods compare :: LabeledThread -> LabeledThread -> Ordering # (<) :: LabeledThread -> LabeledThread -> Bool # (<=) :: LabeledThread -> LabeledThread -> Bool # (>) :: LabeledThread -> LabeledThread -> Bool # (>=) :: LabeledThread -> LabeledThread -> Bool # max :: LabeledThread -> LabeledThread -> LabeledThread # min :: LabeledThread -> LabeledThread -> LabeledThread #
Show LabeledThread Source #
Instance details Defined in Control.Monad.IOSim.Internal Methods showsPrec :: Int -> LabeledThread -> ShowS # show :: LabeledThread -> String # showList :: [LabeledThread] -> ShowS #