input-output-hk · coot · Jan 10, 2024 · Nov 20, 2023 · Nov 20, 2023 · Nov 20, 2023
diff --git a/NOTICE b/NOTICE
@@ -1,4 +1,4 @@
-Copyright 2019-2023 Input Output Global Inc (IOG)
+Copyright 2019-2024 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.

diff --git a/README.md b/README.md
@@ -62,40 +62,6 @@ a complex, highly concurrent, distributed system
 * `strict-stm`: strict STM operations
 * `si-timers`: non-standard timers API
 
-
-## Differences from `base`, `async`, or `exceptions` packages
-
-### Major differences
-
-* `threadDelay` is using `DiffTime` (which is measured in _seconds_ rather than _microseconds_).
-* `registerDelay` is using `DiffTime`
-* `timeout` is using `DiffTime`
-* `getMonotonicTime` returns `Time` (a newtype wrapper around `DiffTime`)
-
-
-### Minor differences
-
-Some of the types have more general kind signatures, e.g.
-
-```
-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 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 `exceptions` packages:
-
-* `Handler` (origin: `base`)
-* `MaskingState` (origin: `base`)
-* `Concurrently` (origin: `async`)
-* `ExceptionInLinkedThread` (origin: `async`): `io-class`es version does not
-  store `Async`
-* `ExitCase` (origin: `exceptions`)
-
-
 ### Issues
 
 New issues should be reported in this repository, we still have a list

diff --git a/io-classes-mtl/NOTICE b/io-classes-mtl/NOTICE
@@ -1,4 +1,4 @@
-Copyright 2023 Input Output Global Inc (IOG)
+Copyright 2023-2024 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.

diff --git a/io-classes-mtl/io-classes-mtl.cabal b/io-classes-mtl/io-classes-mtl.cabal
@@ -10,7 +10,7 @@ license:            Apache-2.0
 license-files:      LICENSE NOTICE
 author:             Duncan Coutts, Marcin Szamotulski
 maintainer:         Marcin Szamotulski coot@coot.me
-copyright:          2022-2023 Input Output Global Inc (IOG)
+copyright:          2022-2024 Input Output Global Inc (IOG)
 category:           Control
 build-type:         Simple
 extra-doc-files:    README.md CHANGELOG.md

diff --git a/io-classes/CHANGELOG.md b/io-classes/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Breaking changes
 
+* Removed deprecated module `Control.Monad.Class.MonadVar`.
+
 ### Non-breaking changes
 
 ## 1.3.1.0

diff --git a/io-classes/NOTICE b/io-classes/NOTICE
@@ -1,4 +1,4 @@
-Copyright 2019-2023 Input Output Global Inc (IOG)
+Copyright 2019-2024 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.

diff --git a/io-classes/README.md b/io-classes/README.md
@@ -80,6 +80,37 @@ packages.
 * [MonadST]: provides a way to lift `ST`-computations.
 * [MonadSay]: dummy debugging interface
 
+## Differences from `base`, `async`, or `exceptions` packages
+
+### Major differences
+
+* `getMonotonicTime` returns `Time` (a newtype wrapper around `DiffTime`)
+* `Deadlock` exceptions are not thrown to the main thread (see
+  [ref][io-deadlock]), so they cannot be caught. This was a design decision,
+  which allows to catch all deadlocks which otherwise could be captured by
+  a `catch`.
+
+### Minor differences
+
+Some of the types have more general kind signatures, e.g.
+
+```
+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 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 `exceptions` packages:
+
+* `Handler` (origin: `base`)
+* `MaskingState` (origin: `base`)
+* `Concurrently` (origin: `async`)
+* `ExceptionInLinkedThread` (origin: `async`): `io-class`es version does not
+  store `Async`
+* `ExitCase` (origin: `exceptions`)
 
 ## Debuging & Insepction
 
@@ -117,6 +148,7 @@ its limitations and so there might be some rough edges.  PRs are welcomed,
 [contributing]: https://www.github.com/input-output-hk/io-sim/tree/master/CONTRIBUTING.md
 [`nothunks`]: https://hackage.haskell.org/package/nothunks
 [labelThread-base]: https://hackage.haskell.org/package/base-4.17.0.0/docs/GHC-Conc-Sync.html#v:labelThread
+[io-deadlock]: https://hackage.haskell.org/package/base-4.19.0.0/docs/Control-Exception.html#t:Deadlock
 
 [MonadEventlog]: https://hackage.haskell.org/package/io-sim-classes/docs/Control-Monad-Class-MonadEventlog.html#t:MonadEventlog
 [Debug.Trace]: https://hackage.haskell.org/package/base/docs/Debug-Trace.html

diff --git a/io-classes/io-classes.cabal b/io-classes/io-classes.cabal
@@ -8,7 +8,7 @@ description:
   'stm', 'exceptions' & 'time' packages.
 license:             Apache-2.0
 license-files:       LICENSE NOTICE
-copyright:           2019-2023 Input Output Global Inc (IOG)
+copyright:           2019-2024 Input Output Global Inc (IOG)
 author:              Alexander Vieth, Duncan Coutts, Marcin Szamotulski, Thomas Winant
 maintainer:          Duncan Coutts duncan@well-typed.com, Marcin Szamotulski coot@coot.me
 category:            Control
@@ -56,7 +56,6 @@ library
                        Control.Monad.Class.MonadAsync
                        Control.Monad.Class.MonadEventlog
                        Control.Monad.Class.MonadFork
-                       Control.Monad.Class.MonadMVar
                        Control.Monad.Class.MonadSay
                        Control.Monad.Class.MonadST
                        Control.Monad.Class.MonadSTM

diff --git a/io-classes/src/Control/Monad/Class/MonadAsync.hs b/io-classes/src/Control/Monad/Class/MonadAsync.hs
@@ -10,6 +10,10 @@
 {-# LANGUAGE TypeFamilyDependencies #-}
 -- MonadAsync's ReaderT instance is undecidable.
 {-# LANGUAGE UndecidableInstances   #-}
+
+-- | <https://hackage.haskell.org/package/async async> API compatible with both
+-- 'IO' and <https://hackage.haskell.org/package/io-sim IOSim>.
+--
 module Control.Monad.Class.MonadAsync
   ( MonadAsync (..)
   , AsyncCancelled (..)

diff --git a/io-classes/src/Control/Monad/Class/MonadFork.hs b/io-classes/src/Control/Monad/Class/MonadFork.hs
@@ -3,6 +3,10 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeFamilies        #-}
 
+-- | A generalisation of
+-- <https://hackage.haskell.org/package/base/docs/Control-Concurrent.html Control.Concurrent>
+-- API to both 'IO' and <https://hackage.haskell.org/package/io-sim IOSim>.
+--
 module Control.Monad.Class.MonadFork
   ( MonadThread (..)
   , labelThisThread

diff --git a/io-classes/src/Control/Monad/Class/MonadMVar.hs b/io-classes/src/Control/Monad/Class/MonadMVar.hs
diff --git a/io-classes/src/Control/Monad/Class/MonadTest.hs b/io-classes/src/Control/Monad/Class/MonadTest.hs
@@ -4,7 +4,7 @@ import           Control.Monad.Reader
 
 -- | A helper monad for /IOSimPOR/.
 class Monad m => MonadTest m where
-  -- | mark a thread for schedule exploration.  All threads that are forked by
+  -- | Mark a thread for schedule exploration.  All threads that are forked by
   -- it are also included in the exploration.
   --
   exploreRaces :: m ()

diff --git a/io-classes/src/Control/Monad/Class/MonadThrow.hs b/io-classes/src/Control/Monad/Class/MonadThrow.hs
@@ -7,6 +7,10 @@
 {-# LANGUAGE TupleSections             #-}
 {-# LANGUAGE TypeFamilies              #-}
 
+-- | A generalisation of
+-- <https://hackage.haskell.org/package/base/docs/Control-Exception.html Control.Exception>
+-- API to both 'IO' and <https://hackage.haskell.org/package/io-sim IOSim>.
+--
 module Control.Monad.Class.MonadThrow
   ( MonadThrow (..)
   , MonadCatch (..)

diff --git a/io-classes/src/Control/Monad/Class/MonadTime.hs b/io-classes/src/Control/Monad/Class/MonadTime.hs
@@ -1,5 +1,9 @@
 {-# LANGUAGE DeriveGeneric #-}
 
+-- | <https://hackage.haskell.org/package/time time> and
+-- <https://hackage.haskell.org/package/base base> time API compatible with both
+-- 'IO' and <https://hackage.haskell.org/package/io-sim IOSim>.
+--
 module Control.Monad.Class.MonadTime
   ( MonadTime (..)
   , MonadMonotonicTimeNSec (..)

diff --git a/io-classes/src/Control/Monad/Class/MonadTimer.hs b/io-classes/src/Control/Monad/Class/MonadTimer.hs
@@ -4,7 +4,10 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeFamilies        #-}
 
--- | Provides classes to handle delays and timeouts.
+-- | Provides classes to handle delays and timeouts which generalised
+-- <https://hackage.haskell.org/package/base base> API to both 'IO' and
+-- <https://hackage.haskell.org/package/io-sim IOSim>.
+--
 module Control.Monad.Class.MonadTimer
   ( MonadDelay (..)
   , MonadTimer (..)

diff --git a/io-sim/CHANGELOG.md b/io-sim/CHANGELOG.md
@@ -4,8 +4,12 @@
 
 ### Breaking changes
 
+* Removed `EventTimerUpdated` constructor (not used anymore).
+
 ### Non-breaking changes
 
+* `Alternative` & `MonadPlus` instances for `IOSim`.
+
 ## 1.3.1.0
 
 ### Non-breaking changes

diff --git a/io-sim/NOTICE b/io-sim/NOTICE
@@ -1,4 +1,4 @@
-Copyright 2019-2023 Input Output Global Inc (IOG)
+Copyright 2019-2024 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.

diff --git a/io-sim/io-sim.cabal b/io-sim/io-sim.cabal
@@ -8,7 +8,7 @@ description:
   and more.
 license:             Apache-2.0
 license-files:       LICENSE NOTICE
-copyright:           2022-2023 Input Output Global Inc (IOG)
+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
 category:            Testing