Skip to content

Commit 06c5690

Browse files
authored
Merge pull request #4 from input-output-hk/coot/README.md
Updated README.md file
2 parents f97c720 + 416ce43 commit 06c5690

File tree

1 file changed

+37
-22
lines changed

1 file changed

+37
-22
lines changed

README.md

Lines changed: 37 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# io-sim
22

3+
34
`IOSim` is an simulator monad which supports:
45

56
* asynchronous exceptions
@@ -9,69 +10,79 @@
910
* concurrency: both low level `forkIO` as well as `async` style
1011
* strict STM
1112
* access to lazy ST
12-
* schedule discovery (see [IOSimPOR](./how-to-use-IOSimPOR.md))
13+
* schedule discovery (see [IOSimPOR][io-sim-por-how-to])
1314
* eventlog
1415
* dynamic tracing
15-
* tracing committed changes to `TVar`, `TMVar`s, ...
16-
* labeling of threads, `TVar`'s, ...
16+
* tracing committed changes to `TVar`, `TMVar`s, etc.
17+
* labelling of threads, `TVar`'s, etc.
1718

18-
`io-classes` provide a common interface, which allow to write code which can be
19-
run in both real `IO` and `IOSim`. It is a drop-in replacement for `IO`.
19+
`io-classes` provides an interface, which allows to write code which can be run
20+
in both real `IO` and `IOSim`. It is a drop-in replacement for `IO`, and
21+
supports interfaces commonly known from `base`, `exceptions`, `stm`, `async` or
22+
`time` packages.
2023

2124
One of the principles of `io-classes` was to stay as close to `IO` as possible,
22-
thus most of the `IO` instances are directly referring to `base`, `async` api.
25+
thus most of the `IO` instances are directly referring to `base` or `async` api.
2326
However we made some differences, which are reported below.
2427

2528
`io-classes` supports a novel hierarchy for error handling monads as well more
2629
familiar `exception` style. The new hierarchy provides `bracket` and
2730
`finally` functions in the `MonadThrow` class, while `catch` style operators
2831
are provided by a super-class `MonadCatch`. Both `bracket` and `finally` are
29-
the most common interface used to write code with robust exception handling,
32+
the most common functions used to write code with robust exception handling,
3033
exposing them through the more basic `MonadThrow` class informs the reader
3134
/ reviewer that no tricky error handling is done in that section of the code
3235
base.
3336

3437
`IOSim` exposes a detailed trace, which can be enhanced by labelling threads,
3538
or mutable variables, tracing `Dynamic` values (which can be recovered from the
36-
trace) or simple `String` based tracing. It has been used to develop & test
37-
a complex concurrent system ([ouroboros-network][ouroboros-network]), in
38-
particular
39+
trace) or simple `String` based tracing. Although its agnostic with respect to
40+
the logging framework, it worked of us particularly well using
41+
[contra-tracer][contra-tracer]. It has been used to develop, test and debug
42+
a complex, highly-concurrent, distributed system
43+
([ouroboros-network][ouroboros-network]), in particular
3944

4045
* write network simulations, to verify a complex networking stack;
41-
* write disk IO simulations, to verify database solution.
46+
* write disk IO simulations, to verify a database implementation.
47+
48+
### Supporting material
49+
50+
* [Philipp Kant (@kantp) at Bobconf 2022][bob-conf]
51+
4252

4353
## Packages
4454

45-
* `io-sim`: provides two simulator monads: `IOSim` and `IOSimPOR` - an enhanced
46-
`IOSim` version with schedule discovery capabilities.
47-
* `io-classes`: class bases interface
55+
* `io-sim`: provides two simulator interpreters: `IOSim` and `IOSimPOR` - an
56+
enhanced `IOSim` version with schedule discovery capabilities.
57+
* `io-classes`: class bases interface, which allows to to abstract over the
58+
monad
4859
* `strict-stm`: strict STM operations
4960

50-
[ouroboros-network]: https://github.com/input-output-hk/ouroboros-network
51-
5261

5362
## Differences from `base`, `async` or `exceptions` packages
5463

64+
### Major differences
65+
5566
* `threadDelay` is using `DiffTime` (which is measured in _seconds_ rather than _microseconds_).
5667
* `regiterDelay` is using `DiffTime`
5768
* `timeout` is using `DiffTime`
5869
* `getMonotonicTime` returns `Time` (a newtype wrapper around `DiffTime`)
5970

71+
6072
### Minor differences
6173

62-
Some of the types have more general type signatures, e.g.
74+
Some of the types have more general kind signatures, e.g.
6375

6476
```
6577
type Async :: (Type -> Type) -> Type -> Type
6678
```
6779

68-
The first type of kind `Type -> Type` describe the monad which could be
80+
The first type of kind `Type -> Type` describes the monad which could be
6981
instantiated to `IO`, `IOSim` or some other monad stack build with monad
7082
transformers. The same applies to many other types, e.g. `TVar`, `TMVar`.
7183

72-
The types although similar to the original
73-
are not the same as the ones that come from `base`, `async`, or
74-
`excpetions` packages:
84+
The following types although similar to the originals are not the same as the
85+
ones that come from `base`, `async`, or `excpetions` packages:
7586

7687
* `Handler` (origin: `base`)
7788
* `MaskingState` (origin: `base`)
@@ -82,12 +93,16 @@ are not the same as the ones that come from `base`, `async`, or
8293

8394
### Issues
8495

85-
Although new issues should be reported in this repository, we still have a list
96+
New issues should be reported in this repository, we still have a list
8697
of issues opened in the `ouroboros-network` repository:
8798

8899
* [io-sim issues][io-sim-issues]
89100
* [io-classes issues][io-sim-issues]
90101

102+
[io-sim-por-how-to]: ./io-sim/how-to-use-IOSimPOR.md
91103
[ouroboros-network]: https://github.com/input-output-hk/ouroboros-network
92104
[io-sim-issues]: https://github.com/input-output-hk/ouroboros-network/issues?q=is%3Aopen+is%3Aissue+label%3Aio-sim
93105
[io-classes-issues]: https://github.com/input-output-hk/ouroboros-network/issues?q=is%3Aopen+is%3Aissue+label%3Aio-classes
106+
[contra-tracer]: https://hackage.haskell.org/package/contra-tracer
107+
[io-sim-por]: https://github.com/input-output-hk/io-sim/blob/main/io-sim/how-to-use-IOSimPOR.md
108+
[bob-conf]: https://www.youtube.com/watch?v=e74TE0b4xEM&t=13662s

0 commit comments

Comments
 (0)