From c32338494912308dc33f081a36ec0a3f5f1c19e4 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Thu, 3 Sep 2020 16:17:33 +0200 Subject: [PATCH] io-sim: include readme file --- io-sim/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 io-sim/README.md diff --git a/io-sim/README.md b/io-sim/README.md new file mode 100644 index 00000000000..7acc0c65cd1 --- /dev/null +++ b/io-sim/README.md @@ -0,0 +1,35 @@ +# Simulator Monad + +A pure simulator monad built on top of the `ST` monad which supports: + + * synchronous and asynchronous exceptions; including: throwing, catching and + masking synchronous and asynchronous exceptions; + * concurrency (using simulated threads), with interfaces shaped by the + `base` and `async` libraries; + * software transactional memory (`STM`); + * simulated time; + * timeouts; + * dynamically typed traces and event log tracing; + * lifting any `ST` computations; + * deadlock detection. + +`io-sim` is a drop-in replacement for the `IO` monad. It was designed to write easily +testable Haskell networking code. Using +[io-sim-classes](https://hackage.haskell.org/package/io-sim-classes) library +one can write code that can run in both: real `IO` and the `SimM` monad. One +of the design goals was to keep the api as close as possible to `base`, +`exceptions`, `async` and `stm` packages. + +As a design choice `IOSim` does not support `MVar`s by default, but they can be +simulated using `stm` interface. + +`io-sim` supports both `io-sim-classes` class hierarchy and `base` +/ `exceptions` class hierarchies (they diverge in some detail). + + +The package contains thorough tests, including tests of `STM` against the original +specification (as described in [Composable Memory +Transactions](https://research.microsoft.com/en-us/um/people/simonpj/papers/stm/stm.pdf) +and its `GHC` implementation. This can be seen in both ways: as a check that +our implementation matches the specification and the `GHC` implementation, but also +the other way around: that `GHC`s `STM` implementation meets the specification.