io-sim: A pure simulator for monadic concurrency with STM.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

These packages miss upper bounds: - QuickCheck - array - containers - criterion - deepseq - exceptions - nothunks - quiet - tasty - tasty-hunit - tasty-quickcheck Please add them, using `cabal gen-bounds` for suggestions. For more information see: https://pvp.haskell.org/

A pure simulator monad with support of concurency (base, async), stm, synchronous and asynchronous exceptions, timeouts & delays, dynamic traces, and more.

[Skip to Readme]

Properties

Versions	1.0.0.0, 1.0.0.1, 1.1.0.0, 1.2.0.0, 1.3.0.0, 1.3.1.0, 1.3.1.0, 1.4.0.0, 1.4.1.0, 1.5.0.0, 1.5.1.0, 1.6.0.0
Change log	CHANGELOG.md
Dependencies	base (>=4.9 && <4.20), containers, deepseq, exceptions (>=0.10), io-classes (>=1.3 && <1.4), nothunks, psqueues (>=0.2 && <0.3), QuickCheck, quiet, si-timers (>=1.3 && <1.4), strict-stm (>=1.3 && <1.4), time (>=1.9.1 && <1.13) [details]
License	Apache-2.0[multiple license files]
Copyright	2022-2023 Input Output Global Inc (IOG)
Author	Alexander Vieth, Duncan Coutts, John Hughes, Marcin Szamotulski
Maintainer	Duncan Coutts duncan@well-typed.com, Marcin Szamotulski coot@coot.me
Category	Testing
Bug tracker	https://github.com/input-output-hk/io-sim/issues
Source repo	head: git clone https://github.com/input-output-hk/io-sim(io-sim)
Uploaded	by coot at 2023-11-20T11:03:47Z

Modules

Control
- Monad
  - Control.Monad.IOSim
Data
- List
  - Data.List.Trace

Flags

Automatic Flags

Name	Description	Default
asserts	Enable assertions	Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

io-sim-1.3.1.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

coot, IOHK

For package maintainers and hackage trustees

edit package information

Readme for io-sim-1.3.1.0

[back to package description]

IOSim - IO Simulator Monad

A pure simulator monad built on top of the lazy ST monad which supports:

optional dynamic race discovery and schedule exploration
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;
inspection of STM mutable data structures;
deadlock detection;
MonadFix instances for both IOSim and its corresponding STM monad.
partial order reduction (see IOSimPOR).

io-sim together with io-classes is a drop-in replacement for the IO monad (with some ramifications). It was designed to write easily testable Haskell code (including simulating socket programming or disk IO). Using io-classes and si-timers libraries one can write code that can run in both: the real IO and the IOSim monad provided by this package. One of the design goals was to keep the API as close as possible to base, exceptions, async, and stm packages.

io-sim package also provides two interpreters, a standard one and IOSimPOR which supports dynamic discovery or race conditions and schedule exploration with partial order reduction.

io-sim provides API to explore traces produced by a simulation. It can contain arbitrary Haskell terms, a feature that is very useful to build property-based tests using QuickCheck.

The package contains thorough tests, including tests of STM against the original specification (as described in Composable Memory Transactions 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 GHCs STM implementation meets the specification.