Control.Monad.IOSim

IOSim is a pure monad.

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

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

Simulation terminated a failure.

See runSimTraceST below.

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

Like https://hackage.haskell.org/package/QuickCheck-2.14.3/docs/Test-QuickCheck-Monadic.html#v:monadicST.

Note: it calls traceResult in non-strict mode, e.g. leaked threads do not cause failures.

A more general version of monadicIOSim_, which:

• allows to run in monad stacks build on top of IOSim;

• gives more control how to attach debugging information to failed tests.

Note, to use this combinator your monad needs to be defined as:

newtype M s a = M s { runM :: ReaderT State (IOSim s) a }

It's important that `M s` is a monad. For such a monad one you'll need provide a natural transformation: -- the state could also be created as an IOSim computation. nat :: forall s a. State -> M s a -> IOSim s a nat state m = runStateT (runM m) state

Like <runSTGen https://hackage.haskell.org/package/QuickCheck-2.14.3/docs/Test-QuickCheck-Monadic.html#v:runSTGen>.

Execute a simulation, discover & revert races. Note that this will execute the simulation multiple times with different schedules, and thus it's much more costly than a simple runSimTrace (also the simulation environments has much more state to track and hence it is slower).

On property failure it will show the failing schedule (ScheduleControl) which can be passed to controlSimTrace to reproduce the failure without discovering the schedule.

Run a simulation using a given schedule. This is useful to reproduce failing cases without exploring the races.

A schedule modification inserted at given execution step.

Modified execution schedule.

Race exploration options.

IOSim has the ability to store any Typeable value in its trace which can then be recovered with selectTraceEventsDynamic or selectTraceEventsDynamic'.

Trace a value, in the same was as traceM does, but from the STM monad. This is primarily useful for debugging.

Pretty print simulation trace.

Note: this is not a streaming function, it will evaluate the whole trace before printing it. If you need to print a very large trace, you might want to use

ppTrace show (ppSimEvent 0 0 0)

Like ppTrace but does not show the result value.

Pretty print a timestamped event.

Pretty print a SimEvent.

Trace each event using trace; this is useful when a trace ends with a pure error, e.g. an assertion.

Select events according to the predicate function. It throws an error if the simulation ends with Failure.

Like selectTraceEvents, but it returns even if the simulation trace ends with Failure. It also works with any return type, not only SimResult like selectTraceEvents does.

Select all the traced values matching the expected type. It relies on the sim's dynamic trace facility.

For convenience, it throws exceptions for abnormal sim termination.

Like selectTraceEventsDynamic but it also captures time of the trace event.

Like selectTraceEventsDynamic but it returns even if the simulation trace ends with Failure. It also works with any return type, not only SimResult like selectTraceEventsDynamic does.

Like selectTraceEventsDynamicWithTime' but it also captures time of the trace event. It also works with any return type, not only SimResult like selectTraceEventsDynamicWithTime does.

Get a trace of EventSay.

For convenience, it throws exceptions for abnormal sim termination.

Like selectTraceEventsSay but it also captures time of the trace event.

Like selectTraceEventsSay but it returns even if the simulation trace ends with Failure. It also works with any return type, not only SimResult like selectTraceEventsSay does.

Like selectTraceEventsSay' but it also captures time of the trace event.

The most general select function. It is a total function.

Select dynamic events. It is a total function.

Select say events. It is a total function.

Print all EventSay to the console.

For convenience, it throws exceptions for abnormal sim termination.