-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A pure simlator for monadic concurrency with STM
--   
--   A pure simlator for monadic concurrency with STM
@package io-sim
@version 0.2.0.0

module Control.Monad.IOSim
data IOSim s a
type STMSim = STM

-- | <a>IOSim</a> is a pure monad.
runSim :: forall a. (forall s. IOSim s a) -> Either Failure a

-- | For quick experiments and tests it is often appropriate and convenient
--   to simply throw failures as exceptions.
runSimOrThrow :: forall a. (forall s. IOSim s a) -> a

-- | Like <a>runSim</a> 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.
runSimStrictShutdown :: forall a. (forall s. IOSim s a) -> Either Failure a

-- | Simulation termination with failure
data Failure

-- | The main thread terminated with an exception
FailureException :: SomeException -> Failure

-- | The threads all deadlocked
FailureDeadlock :: Failure

-- | The main thread terminated normally but other threads were still
--   alive, and strict shutdown checking was requested. See
--   <a>runSimStrictShutdown</a>
FailureSloppyShutdown :: [LabeledThread] -> Failure

-- | See <a>runSimTraceST</a> below.
runSimTrace :: forall a. (forall s. IOSim s a) -> Trace a

-- | The most general method of running <a>IOSim</a> is in <a>ST</a> monad.
--   One can recover failures or the result from <a>Trace</a> with
--   <tt>traceResult</tt>, or access <a>TraceEvent</a>s generated by the
--   computation with <tt>traceEvents</tt>. A slightly more convenient way
--   is exposed by <tt>runSimTrace</tt>.
runSimTraceST :: forall s a. IOSim s a -> ST s (Trace a)
liftST :: ST s a -> IOSim s a
traceM :: Typeable a => a -> IOSim s ()

-- | Set the current wall clock time for the thread's clock domain.
setCurrentTime :: UTCTime -> IOSim s ()

-- | 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.
unshareClock :: IOSim s ()

-- | <a>Trace</a> is a recursive data type, it is the trace of a
--   <a>IOSim</a> computation. The trace will contain information about
--   thread sheduling, blocking on <a>TVar</a>s, and other internal state
--   changes of <a>IOSim</a>. More importantly it also supports traces
--   generated by the computation with <a>say</a> (which corresponds to
--   using <a>putStrLn</a> in <a>IO</a>), <a>traceEventM</a>, or
--   dynamically typed traces with <a>traceM</a> (which generalise the
--   <tt>base</tt> library <a>traceM</a>)
--   
--   See also: <tt>traceEvents</tt>, <tt>traceResult</tt>,
--   <tt>selectTraceEvents</tt>, <tt>selectTraceEventsDynamic</tt> and
--   <tt>printTraceEventsSay</tt>.
data Trace a
Trace :: !Time -> !ThreadId -> !Maybe ThreadLabel -> !TraceEvent -> Trace a -> Trace a
TraceMainReturn :: !Time -> a -> ![LabeledThread] -> Trace a
TraceMainException :: !Time -> SomeException -> ![LabeledThread] -> Trace a
TraceDeadlock :: !Time -> ![LabeledThread] -> Trace a
data TraceEvent
EventSay :: String -> TraceEvent
EventLog :: Dynamic -> TraceEvent
EventThrow :: SomeException -> TraceEvent
EventThrowTo :: SomeException -> ThreadId -> TraceEvent
EventThrowToBlocked :: TraceEvent
EventThrowToWakeup :: TraceEvent
EventThrowToUnmasked :: ThreadId -> TraceEvent
EventThreadForked :: ThreadId -> TraceEvent
EventThreadFinished :: TraceEvent
EventThreadUnhandled :: SomeException -> TraceEvent
EventTxCommitted :: [TVarId] -> [TVarId] -> TraceEvent
EventTxAborted :: TraceEvent
EventTxBlocked :: [TVarId] -> TraceEvent
EventTxWakeup :: [TVarId] -> TraceEvent
EventTimerCreated :: TimeoutId -> TVarId -> Time -> TraceEvent
EventTimerUpdated :: TimeoutId -> Time -> TraceEvent
EventTimerCancelled :: TimeoutId -> TraceEvent
EventTimerExpired :: TimeoutId -> TraceEvent
type ThreadLabel = String
data LabeledThread
LabeledThread :: ThreadId -> Maybe ThreadLabel -> LabeledThread
[labeledThreadId] :: LabeledThread -> ThreadId
[labeledThreadLabel] :: LabeledThread -> Maybe ThreadLabel
traceEvents :: Trace a -> [(Time, ThreadId, Maybe ThreadLabel, TraceEvent)]
traceResult :: Bool -> Trace a -> Either Failure a
selectTraceEvents :: (TraceEvent -> Maybe b) -> Trace a -> [b]

-- | Select all the traced values matching the expected type. This relies
--   on the sim's dynamic trace facility.
--   
--   For convenience, this throws exceptions for abnormal sim termination.
selectTraceEventsDynamic :: forall a b. Typeable b => Trace a -> [b]

-- | Get a trace of <a>EventSay</a>.
--   
--   For convenience, this throws exceptions for abnormal sim termination.
selectTraceEventsSay :: Trace a -> [String]

-- | Print all <a>EventSay</a> to the console.
--   
--   For convenience, this throws exceptions for abnormal sim termination.
printTraceEventsSay :: Trace a -> IO ()

-- | Wrapper for Eventlog events so they can be retrieved from the trace
--   with <tt>selectTraceEventsDynamic</tt>.
newtype EventlogEvent
EventlogEvent :: String -> EventlogEvent

-- | Wrapper for Eventlog markers so they can be retrieved from the trace
--   with <tt>selectTraceEventsDynamic</tt>.
newtype EventlogMarker
EventlogMarker :: String -> EventlogMarker
execReadTVar :: TVar s a -> ST s a

-- | <i>Deprecated: Use IOSim</i>
type SimM s = IOSim s

-- | <i>Deprecated: Use STMSim</i>
type SimSTM = STM
instance GHC.Show.Show Control.Monad.IOSim.Failure
instance GHC.Exception.Type.Exception Control.Monad.IOSim.Failure
