{"id":31883881,"url":"https://github.com/input-output-hk/io-sim","last_synced_at":"2025-10-13T03:53:01.069Z","repository":{"id":37960471,"uuid":"491940347","full_name":"input-output-hk/io-sim","owner":"input-output-hk","description":"Haskell's IO simulator which closely follows core packages (base, async, stm).","archived":false,"fork":false,"pushed_at":"2025-09-04T06:45:03.000Z","size":1998,"stargazers_count":44,"open_issues_count":27,"forks_count":22,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-09-04T08:49:27.304Z","etag":null,"topics":["haskell","partial-order-reduction","simulation-framework"],"latest_commit_sha":null,"homepage":"https://input-output-hk.github.io/io-sim/","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/input-output-hk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-13T14:59:24.000Z","updated_at":"2025-09-04T06:48:40.000Z","dependencies_parsed_at":"2025-06-02T15:07:24.604Z","dependency_job_id":"0bcc32f8-e75b-4b83-bc91-7e0a48b17d12","html_url":"https://github.com/input-output-hk/io-sim","commit_stats":{"total_commits":608,"total_committers":26,"mean_commits":"23.384615384615383","dds":0.493421052631579,"last_synced_commit":"34a2659e46652c463fe0f3e0d72dc7dd7d21c0d2"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/input-output-hk/io-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/input-output-hk%2Fio-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/input-output-hk%2Fio-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/input-output-hk%2Fio-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/input-output-hk%2Fio-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/input-output-hk","download_url":"https://codeload.github.com/input-output-hk/io-sim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/input-output-hk%2Fio-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013520,"owners_count":26085368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["haskell","partial-order-reduction","simulation-framework"],"created_at":"2025-10-13T03:52:59.553Z","updated_at":"2025-10-13T03:53:01.062Z","avatar_url":"https://github.com/input-output-hk.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Haskell CI](https://img.shields.io/github/actions/workflow/status/input-output-hk/io-sim/haskell.yml?branch=main\u0026label=Build\u0026style=for-the-badge)](https://github.com/input-output-hk/io-sim/actions/workflows/haskell.yml)\n[![handbook](https://img.shields.io/badge/policy-Cardano%20Engineering%20Handbook-informational?style=for-the-badge)](https://input-output-hk.github.io/cardano-engineering-handbook)\n[![Haddocks](https://img.shields.io/badge/documentation-Haddocks-pink?style=for-the-badge)](https://input-output-hk.github.io/io-sim)\n\n# [`io-sim`]\n\n[`IOSim`] is a simulator monad that supports:\n\n* asynchronous exceptions\n* simulated time\n* timeout API\n* software transaction memory (STM)\n* concurrency: both low-level `forkIO` as well as `async` style\n* strict STM\n* access to lazy ST\n* schedule discovery (see [IOSimPOR][io-sim-por-how-to])\n* event log\n* dynamic tracing\n* tracing committed changes to `TVar`, `TMVar`s, etc.\n* labeling of threads, `TVar`'s, etc.\n\n[`io-classes:io-classes`] provides an interface, which allows writing code that\ncan be run in both real `IO` and [`IOSim`].  It is a drop-in replacement for\n`IO`, and supports interfaces commonly known from `base`, `exceptions`, `stm`,\n`async`, or `time` packages.\n\nOne of the principles of `io-classes:io-classes` was to stay as close to `IO`\nas possible, thus most of the `IO` instances are directly referring to `base`\nor `async` API.  However, we made some distinctions, which are reported below.\n\n[`io-classes:io-classes`] supports a novel hierarchy for error-handling monads\nas well as more familiar `exception` style.  The new hierarchy provides\n`bracket` and `finally` functions in the `MonadThrow` class, while `catch`\nstyle operators are provided by a super-class `MonadCatch`.  Both `bracket` and\n`finally` are the most common functions used to write code with robust\nexception handling, exposing them through the more basic `MonadThrow` class\ninforms the reader / reviewer that no tricky error handling is done in that\nsection of the code base.\n\n[`IOSim`] exposes a detailed trace, which can be enhanced by labeling threads, or\nmutable variables, tracing `Dynamic` values (which can be recovered from the\ntrace), or simple `String` based tracing.  Although it's agnostic concerning\nthe logging framework, it worked for us particularly well using\n[contra-tracer][contra-tracer].  It has been used to develop, test, and debug\na complex, highly concurrent, distributed system\n([ouroboros-network][ouroboros-network]), in particular\n\n* write network simulations, to verify a complex networking stack;\n* write disk IO simulations, to verify a database implementation.\n\n## Supporting material\n\n* [Philipp Kant (@kantp) at Bobconf 2022][bob-conf]\n* [Armando Santos (@bolt12) at ZuriHac 2022][zuriHac-2022]\n* [Marcin Szamotulski (@coot) IOSim and Partial Order Reduction][io-sim-por-presentation]\n\n\n## Packages\n\n* [`io-sim`]: provides two simulator interpreters: [`IOSim`] and\n  `IOSimPOR` - an enhanced [`IOSim`] version with schedule discovery\n  capabilities.\n* [`io-classes:io-classes`]: class bases interface, which allows to to abstract over the\n    monad\n* [`io-classes:strict-stm`]: strict STM operations\n* [`io-classes:si-timers`]: non-standard timers API\n\n## Issues\n\nNew issues should be reported in [this][io-sim-issues] repository.\n\n[`io-classes:io-classes`]: https://hackage.haskell.org/package/io-classes\n[`io-classes:strict-stm`]:  https://hackage.haskell.org/package/io-classes\n[`io-classes:si-timers`]:  https://hackage.haskell.org/package/io-classes\n[`io-sim`]: https://hackage.haskell.org/package/io-sim\n\n[contra-tracer]: https://hackage.haskell.org/package/contra-tracer\n[io-sim-issues]: https://github.com/input-output-hk/io-sim/issues\n[io-sim-por-how-to]: ./io-sim/how-to-use-IOSimPOR.md\n[io-sim-por]: https://github.com/input-output-hk/io-sim/blob/main/io-sim/how-to-use-IOSimPOR.md\n[ouroboros-network]: https://github.com/input-output-hk/ouroboros-network\n\n[`IOSim`]: https://hackage.haskell.org/package/io-sim/docs/Control-Monad-IOSim.html#t:IOSim\n\n[bob-conf]: https://youtu.be/uedUGeWN4ZM\n[zuriHac-2022]: https://youtu.be/tKIYQgJnGkA\n[io-sim-por-presentation]: https://coot.me/presentations/iosimpor.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finput-output-hk%2Fio-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finput-output-hk%2Fio-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finput-output-hk%2Fio-sim/lists"}