1
1
# io-sim
2
2
3
+
3
4
` IOSim ` is an simulator monad which supports:
4
5
5
6
* asynchronous exceptions
9
10
* concurrency: both low level ` forkIO ` as well as ` async ` style
10
11
* strict STM
11
12
* access to lazy ST
12
- * schedule discovery (see [ IOSimPOR] ( ./how-to-use-IOSimPOR.md ) )
13
+ * schedule discovery (see [ IOSimPOR] [ io-sim-por-how-to ] )
13
14
* eventlog
14
15
* 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 .
17
18
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.
20
23
21
24
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.
23
26
However we made some differences, which are reported below.
24
27
25
28
` io-classes ` supports a novel hierarchy for error handling monads as well more
26
29
familiar ` exception ` style. The new hierarchy provides ` bracket ` and
27
30
` finally ` functions in the ` MonadThrow ` class, while ` catch ` style operators
28
31
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,
30
33
exposing them through the more basic ` MonadThrow ` class informs the reader
31
34
/ reviewer that no tricky error handling is done in that section of the code
32
35
base.
33
36
34
37
` IOSim ` exposes a detailed trace, which can be enhanced by labelling threads,
35
38
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
39
44
40
45
* 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
+
42
52
43
53
## Packages
44
54
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
48
59
* ` strict-stm ` : strict STM operations
49
60
50
- [ ouroboros-network ] : https://github.com/input-output-hk/ouroboros-network
51
-
52
61
53
62
## Differences from ` base ` , ` async ` or ` exceptions ` packages
54
63
64
+ ### Major differences
65
+
55
66
* ` threadDelay ` is using ` DiffTime ` (which is measured in _ seconds_ rather than _ microseconds_ ).
56
67
* ` regiterDelay ` is using ` DiffTime `
57
68
* ` timeout ` is using ` DiffTime `
58
69
* ` getMonotonicTime ` returns ` Time ` (a newtype wrapper around ` DiffTime ` )
59
70
71
+
60
72
### Minor differences
61
73
62
- Some of the types have more general type signatures, e.g.
74
+ Some of the types have more general kind signatures, e.g.
63
75
64
76
```
65
77
type Async :: (Type -> Type) -> Type -> Type
66
78
```
67
79
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
69
81
instantiated to ` IO ` , ` IOSim ` or some other monad stack build with monad
70
82
transformers. The same applies to many other types, e.g. ` TVar ` , ` TMVar ` .
71
83
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:
75
86
76
87
* ` Handler ` (origin: ` base ` )
77
88
* ` MaskingState ` (origin: ` base ` )
@@ -82,12 +93,16 @@ are not the same as the ones that come from `base`, `async`, or
82
93
83
94
### Issues
84
95
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
86
97
of issues opened in the ` ouroboros-network ` repository:
87
98
88
99
* [ io-sim issues] [ io-sim-issues ]
89
100
* [ io-classes issues] [ io-sim-issues ]
90
101
102
+ [ io-sim-por-how-to ] : ./io-sim/how-to-use-IOSimPOR.md
91
103
[ ouroboros-network ] : https://github.com/input-output-hk/ouroboros-network
92
104
[ io-sim-issues ] : https://github.com/input-output-hk/ouroboros-network/issues?q=is%3Aopen+is%3Aissue+label%3Aio-sim
93
105
[ 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