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

[ apache, library, testing ] [ Propose Tags ] [ Report a vulnerability ]

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

Documentation

Documentation is published here.


[Skip to Readme]

Modules

[Last Documentation]

  • Control
    • Monad
      • Control.Monad.IOSim
  • Data
    • List
      • Data.List.Trace

Flags

Automatic Flags
NameDescriptionDefault
asserts

Enable assertions

Disabled

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

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 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.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.21), containers, deepseq, exceptions (>=0.10), io-classes (>=1.6 && <1.8), nothunks, parallel, primitive (>=0.7 && <0.11), psqueues (>=0.2 && <0.3), QuickCheck, quiet, time (>=1.9.1 && <1.13) [details]
Tested with ghc ==8.10 || ==9.2 || ==9.4 || ==9.6 || ==9.8 || ==9.10
License Apache-2.0[multiple license files]
Copyright 2022-2024 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
Revised Revision 3 made by IOHK at 2024-08-29T09:15:44Z
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 IOHK at 2024-08-27T07:58:25Z
Distributions NixOS:1.6.0.0
Downloads 3486 total (172 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2024-08-29 [all 4 reports]

Readme for io-sim-1.6.0.0

[back to package description]

IO Simulator Monad: io-sim

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

  • optional dynamic race discovery and schedule exploration (see IOSimPOR)
  • 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.

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 of 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.