io-sim 1.0.0.0

CONTRIBUTING.md

@@ -1,25 +1,19 @@
 # Building
 
-The project is build with `cabal-install`.  You might need to run `cabal
-update` after cloning the repository (to update [`Cardano Haskell
-Packages`][CHaP] (`ChaP`) index).
+The project is built with `cabal-install`.  You might need to run `cabal
+update` after cloning the repository.
 
 # Design Principles
 
 We designed `io-classes` to be as close as possible to what `base` package
-provides.  Almost all `IO` instances instantiate with api provided by one of
+provides.  Almost all `IO` instances instantiate with API provided by one of
 the core packages, see
 [example](https://github.com/input-output-hk/io-sim/blob/main/io-classes/src/Control/Monad/Class/MonadSTM.hs?plain=1#L410-L446).
 Please keep this in mind when adding new functionality.
 
-# Using in your project
+# Roles and Responsibilities
 
-Currently the package is published to [`CHaP`][CHaP].  In future it will be
-published to `Hackage`.  If you want to pull it from [`CHaP`][CHaP], this is
-relatively easy to setup; for example, checkout the
-[`cabal.project`](https://github.com/input-output-hk/typed-protocols/blob/master/cabal.project)
-file.  Alternatively, you can relay on `source-repository-package` stanza in
-a `cabal.project` file.
+Maintainers of each package are listed in the corresponding `*.cabal` file.
 
 # Testing
 
@@ -60,14 +54,15 @@ package ouroboros-network-testing
 
 # Code Style
 
-Please follow local style.  For a more detailed style guide see
+Please follow the local style.  For a more detailed style guide see
 [link](https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md).
 
 # Pull Requests
 
-Each commit shall be small and preferably address one thing at a time.  Well
-organised & documented commits make it much easier for the maintainers to
-review them.
+Each commit shall be small and preferably address one thing at a time.
+Well-organised & documented commits make it much easier for the maintainers to
+review them.  Hacking sessions are great, but please take your time to organise
+your work, this usually improves the quality too!
 
 New features should be well documented & tested, which means including new
 tests as necessary.  You might be asked by the maintainers to write & include
@@ -76,46 +71,58 @@ additional tests.
 Each commit should build & test, at least the package you are changing.  You
 can update other packages from this repository in a subsequent commit.
 
-Please use a draft PRs if the work is still in progress.
+Please use a draft PR if the work is still in progress.
 
-We require all commits to be signed, see [this guide][gh-signing-commits].
-
-If your pull requests resolves an existing issue, please link your PR to that
+If your pull requests resolve an existing issue, please link your PR to the
 issue, see [GitHub documentation][gh-link-issue].
 
-Please include your changes in `CHANGELOG.md` files (per package).
+Please include your changes in the `CHANGELOG.md` files (per package).
+
+We prefer to avoid merging commits, rebasing a well-organised PR is usually
+quite simple.
+
+## Code Style
+
+Please follow the local style.  For a more detailed style guide see
+[link](https://github.com/input-output-hk/ouroboros-network/blob/master/docs/StyleGuide.md).
 
 ## MonadSTM features
 
-If you are adding a new functionality to `MonadSTM`, don't forget to support it
+If you are adding new functionality to `MonadSTM`, don't forget to support it
 in `strict-stm` package.
 
+## CI
+
+We run CI using [GitHub actions][ci].
+
 # Releases
 
-The major version of `io-sim`, `io-classes` and `strict-stm` packages are kept
-in sync.  This means that if any of the packages introduces a breaking change
-all major version SHOULD be bumped.  The minor versions are kept independent.
+The major version of `io-sim`, `io-classes`, `strict-stm` and `si-timers`
+packages are kept in sync.  This means that if any of the packages introduce
+a breaking change all major versions SHOULD be bumped.  The minor versions are
+kept independent.  The `io-classes-mtl` is still experimental and thus it's not
+following that principle.
 
 The drawback is that if you declare `io-classes ^>= 0.x` then you will need to
-bump it when new version of `io-sim` is published (even if there are no changes
-in `io-classes`).  The con is that you just need to declare version of
-`io-classes` to have a consistent ecosystem of the three packages.
+bump it when a new version of `io-sim` is published (even if there are no changes
+in `io-classes`).  The con is that you just need to declare the version of
+`io-classes` to have a consistent ecosystem of the four packages.
 
 # Tips
 
 ## `ppTrace` is strict
 
 Both `ppTrace` and `ppTrace_` are strict.  They evaluate the trace before they
 produce any result, thus they are not useful when your trace diverges.  This
-can happen if evaluation encounters unhandled exception e.g. one of assertion
+can happen if the evaluation encounters an unhandled exception e.g. an assertion
 fires (either internal or otherwise).  In that case, instead of `ppTrace` you
 can use `Data.Trace.toList` and simply `traverse print` the list.  This will
 give you the trace up to the point of failure.
 
 ## `IOSim` and `STMSim` monads are based on lazy `ST` monad
 
 This means that any action is forced only when the result is needed.  This is
-more lazy than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
+lazier than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
 `schedule` function you need to:
 ```hs
     ...
@@ -128,5 +135,5 @@ more lazy than `IO` monad.  Thus if you want to use `Debug.Trace.traceM` inside
 [CHaP]: https://github.com/input-output-hk/cardano-haskell-packages/
 [gh-link-issue]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue
 [gh-signing-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
-
+[ci]: https://github.com/input-output-hk/io-sim/actions
 

NOTICE

@@ -1,4 +1,4 @@
-Copyright 2022 Input Output (Hong Kong) Ltd.
+Copyright 2019-2023 Input Output Global Inc (IOG)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -3,46 +3,45 @@
 
 # io-sim
 
-
-`IOSim` is an simulator monad which supports:
+`IOSim` is a simulator monad that supports:
 
 * asynchronous exceptions
 * simulated time
 * timeout API
 * software transaction memory (STM)
-* concurrency: both low level `forkIO` as well as `async` style
+* concurrency: both low-level `forkIO` as well as `async` style
 * strict STM
 * access to lazy ST
 * schedule discovery (see [IOSimPOR][io-sim-por-how-to])
-* eventlog
+* event log
 * dynamic tracing
 * tracing committed changes to `TVar`, `TMVar`s, etc.
-* labelling of threads, `TVar`'s, etc.
+* labeling of threads, `TVar`'s, etc.
 
-`io-classes` provides an interface, which allows to write code which can be run
+`io-classes` provides an interface, which allows writing code that can be run
 in both real `IO` and `IOSim`.  It is a drop-in replacement for `IO`, and
-supports interfaces commonly known from `base`, `exceptions`, `stm`, `async` or
-`time` packages.
+supports interfaces commonly known from `base`, `exceptions`, `stm`, `async`,
+or `time` packages.
 
 One of the principles of `io-classes` was to stay as close to `IO` as possible,
-thus most of the `IO` instances are directly referring to `base` or `async` api.
-However we made some distinctions, which are reported below.
+thus most of the `IO` instances are directly referring to `base` or `async`
+API.  However, we made some distinctions, which are reported below.
 
-`io-classes` supports a novel hierarchy for error handling monads as well more
-familiar `exception` style.  The new hierarchy provides `bracket` and
+`io-classes` supports a novel hierarchy for error-handling monads as well as
+more familiar `exception` style.  The new hierarchy provides `bracket` and
 `finally` functions in the `MonadThrow` class, while `catch` style operators
 are provided by a super-class `MonadCatch`.  Both `bracket` and `finally` are
 the most common functions used to write code with robust exception handling,
 exposing them through the more basic `MonadThrow` class informs the reader
 / reviewer that no tricky error handling is done in that section of the code
 base.
 
-`IOSim` exposes a detailed trace, which can be enhanced by labelling threads,
-or mutable variables, tracing `Dynamic` values (which can be recovered from the
-trace) or simple `String` based tracing.  Although its agnostic with respect to
+`IOSim` exposes a detailed trace, which can be enhanced by labeling threads, or
+mutable variables, tracing `Dynamic` values (which can be recovered from the
+trace), or simple `String` based tracing.  Although it's agnostic concerning
 the logging framework, it worked for us particularly well using
-[contra-tracer][contra-tracer].  It has been used to develop, test and debug
-a complex, highly-concurrent, distributed system
+[contra-tracer][contra-tracer].  It has been used to develop, test, and debug
+a complex, highly concurrent, distributed system
 ([ouroboros-network][ouroboros-network]), in particular
 
 * write network simulations, to verify a complex networking stack;
@@ -61,9 +60,10 @@ a complex, highly-concurrent, distributed system
 * `io-classes`: class bases interface, which allows to to abstract over the
     monad
 * `strict-stm`: strict STM operations
+* `si-timers`: non-standard timers API
 
 
-## Differences from `base`, `async` or `exceptions` packages
+## Differences from `base`, `async`, or `exceptions` packages
 
 ### Major differences
 
@@ -82,11 +82,11 @@ type Async :: (Type -> Type) -> Type -> Type
 ```
 
 The first type of kind `Type -> Type` describes the monad which could be
-instantiated to `IO`, `IOSim` or some other monad stack build with monad
+instantiated to `IO`, `IOSim` or some other monad stacks built with monad
 transformers.  The same applies to many other types, e.g. `TVar`, `TMVar`.
 
 The following types although similar to the originals are not the same as the
-ones that come from `base`, `async`, or `excpetions` packages:
+ones that come from `base`, `async`, or `exceptions` packages:
 
 * `Handler` (origin: `base`)
 * `MaskingState` (origin: `base`)

SECURITY.md

@@ -0,0 +1,2 @@
+See the security file in the [Cardano engineering handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/SECURITY.md).
+

io-classes-mtl/README.md

@@ -2,16 +2,16 @@
 
 `ReaderT` instances are included in `io-classes`, but all other instances are
 included in this package.  Some of them are rather novel and experimental
-others might be less so.   This code is not really tested, neither it has run
-in production environment as we know (let us know if you do!).
+others might be less so.   This code is not well tested, and some of it hasn't run
+in a production environment as we know (let us know if you do!).
 
 The `MonadSTM` instances for monad transformers are somewhat novel.  The `STM`
 monad is transformed together with the base monad.  This means that the
-transfomer primitive operations are available in `STM`.  For example you an
+transformer primitive operations are available in `STM`.  For example you an
 `STM` transaction can lock updating the state of the current thread.
 
 We haven't included `MonadAsync` instances (although we have an experimental
-branch how  this could be done).  It could work like the `lifted-async`
+branch how this could be done).  It could work like the `lifted-async`
 package.  But we feel this can be controversial, so it's not included.
 
 The design goal is to follow  `exception` package instances, but since we don't

io-classes-mtl/io-classes-mtl.cabal

@@ -2,6 +2,10 @@ cabal-version:      3.0
 name:               io-classes-mtl
 version:            0.1.0.0
 synopsis:           Experimental MTL instances for io-classes
+description:
+    MTL instances for
+    [io-classes](https://hackage.hasekll.org/package/io-classes) package.
+    Some of the instances are novel and some are still experimental.
 license:            Apache-2.0
 license-files:
   LICENSE
@@ -41,7 +45,7 @@ library
                       array,
                       mtl,
 
-                      io-classes ^>= 0.6.0.0,
+                      io-classes ^>= 1.0.0.0,
                       si-timers,
 
 

io-classes/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## next version
 
+## 1.0.0.0
+
 ### Breaking changes
 
 * `MonadMonotonicTime` morphed into `MonadMonotonicTimeNSec` which supports

io-classes/NOTICE

@@ -1,4 +1,4 @@
-Copyright 2019-2023 Input Output (Hong Kong) Ltd.
+Copyright 2019-2023 Input Output Global Inc (IOG)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.