https://github.com/input-output-hk/io-sim
Haskell's IO simulator which closely follows core packages (base, async, stm).
https://github.com/input-output-hk/io-sim
haskell partial-order-reduction simulation-framework
Last synced: 3 months ago
JSON representation
Haskell's IO simulator which closely follows core packages (base, async, stm).
- Host: GitHub
- URL: https://github.com/input-output-hk/io-sim
- Owner: input-output-hk
- License: apache-2.0
- Created: 2022-05-13T14:59:24.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-09-04T06:45:03.000Z (4 months ago)
- Last Synced: 2025-09-04T08:49:27.304Z (4 months ago)
- Topics: haskell, partial-order-reduction, simulation-framework
- Language: Haskell
- Homepage: https://input-output-hk.github.io/io-sim/
- Size: 1.91 MB
- Stars: 44
- Watchers: 15
- Forks: 22
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
[](https://github.com/input-output-hk/io-sim/actions/workflows/haskell.yml)
[](https://input-output-hk.github.io/cardano-engineering-handbook)
[](https://input-output-hk.github.io/io-sim)
# [`io-sim`]
[`IOSim`] is a simulator monad that supports:
* asynchronous exceptions
* simulated time
* timeout API
* software transaction memory (STM)
* concurrency: both low-level `forkIO` as well as `async` style
* strict STM
* access to lazy ST
* schedule discovery (see [IOSimPOR][io-sim-por-how-to])
* event log
* dynamic tracing
* tracing committed changes to `TVar`, `TMVar`s, etc.
* labeling of threads, `TVar`'s, etc.
[`io-classes:io-classes`] provides an interface, which allows writing code that
can be run in both real `IO` and [`IOSim`]. It is a drop-in replacement for
`IO`, and supports interfaces commonly known from `base`, `exceptions`, `stm`,
`async`, or `time` packages.
One of the principles of `io-classes:io-classes` was to stay as close to `IO`
as possible, thus most of the `IO` instances are directly referring to `base`
or `async` API. However, we made some distinctions, which are reported below.
[`io-classes:io-classes`] supports a novel hierarchy for error-handling monads
as well as more familiar `exception` style. The new hierarchy provides
`bracket` and `finally` functions in the `MonadThrow` class, while `catch`
style operators are provided by a super-class `MonadCatch`. Both `bracket` and
`finally` are the most common functions used to write code with robust
exception handling, exposing them through the more basic `MonadThrow` class
informs the reader / reviewer that no tricky error handling is done in that
section of the code base.
[`IOSim`] exposes a detailed trace, which can be enhanced by labeling threads, or
mutable variables, tracing `Dynamic` values (which can be recovered from the
trace), or simple `String` based tracing. Although it's agnostic concerning
the logging framework, it worked for us particularly well using
[contra-tracer][contra-tracer]. It has been used to develop, test, and debug
a complex, highly concurrent, distributed system
([ouroboros-network][ouroboros-network]), in particular
* write network simulations, to verify a complex networking stack;
* write disk IO simulations, to verify a database implementation.
## Supporting material
* [Philipp Kant (@kantp) at Bobconf 2022][bob-conf]
* [Armando Santos (@bolt12) at ZuriHac 2022][zuriHac-2022]
* [Marcin Szamotulski (@coot) IOSim and Partial Order Reduction][io-sim-por-presentation]
## Packages
* [`io-sim`]: provides two simulator interpreters: [`IOSim`] and
`IOSimPOR` - an enhanced [`IOSim`] version with schedule discovery
capabilities.
* [`io-classes:io-classes`]: class bases interface, which allows to to abstract over the
monad
* [`io-classes:strict-stm`]: strict STM operations
* [`io-classes:si-timers`]: non-standard timers API
## Issues
New issues should be reported in [this][io-sim-issues] repository.
[`io-classes:io-classes`]: https://hackage.haskell.org/package/io-classes
[`io-classes:strict-stm`]: https://hackage.haskell.org/package/io-classes
[`io-classes:si-timers`]: https://hackage.haskell.org/package/io-classes
[`io-sim`]: https://hackage.haskell.org/package/io-sim
[contra-tracer]: https://hackage.haskell.org/package/contra-tracer
[io-sim-issues]: https://github.com/input-output-hk/io-sim/issues
[io-sim-por-how-to]: ./io-sim/how-to-use-IOSimPOR.md
[io-sim-por]: https://github.com/input-output-hk/io-sim/blob/main/io-sim/how-to-use-IOSimPOR.md
[ouroboros-network]: https://github.com/input-output-hk/ouroboros-network
[`IOSim`]: https://hackage.haskell.org/package/io-sim/docs/Control-Monad-IOSim.html#t:IOSim
[bob-conf]: https://youtu.be/uedUGeWN4ZM
[zuriHac-2022]: https://youtu.be/tKIYQgJnGkA
[io-sim-por-presentation]: https://coot.me/presentations/iosimpor.pdf