From 7e25bfae4699790439adb86b32e2ac170d1b47e8 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Mon, 20 Nov 2023 21:38:49 +0100 Subject: [PATCH 1/7] io-sim: removed EventTimerUpdated The constructor is no longer used. --- io-sim/CHANGELOG.md | 2 ++ io-sim/src/Control/Monad/IOSim/Types.hs | 6 ------ 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/io-sim/CHANGELOG.md b/io-sim/CHANGELOG.md index 9a3d2e6f..8c776bc6 100644 --- a/io-sim/CHANGELOG.md +++ b/io-sim/CHANGELOG.md @@ -4,6 +4,8 @@ ### Breaking changes +* Removed `EventTimerUpdated` constructor (not used anymore). + ### Non-breaking changes ## 1.3.1.0 diff --git a/io-sim/src/Control/Monad/IOSim/Types.hs b/io-sim/src/Control/Monad/IOSim/Types.hs index d2566d70..cfa6075d 100644 --- a/io-sim/src/Control/Monad/IOSim/Types.hs +++ b/io-sim/src/Control/Monad/IOSim/Types.hs @@ -1047,8 +1047,6 @@ data SimEventType | EventTimerCreated TimeoutId TVarId Time -- ^ a new 'Timeout' created (via `newTimeout`) - | EventTimerUpdated TimeoutId Time - -- ^ a 'Timeout' was updated (via `updateTimeout`) | EventTimerCancelled TimeoutId -- ^ a 'Timeout' was cancelled (via `cancelTimeout`) | EventTimerFired TimeoutId @@ -1153,10 +1151,6 @@ ppSimEventType = \case show timer, " ", show tvarId, " ", show t ] - EventTimerUpdated timer t -> - concat [ "TimerUpdated ", - show timer, " ", - show t ] EventTimerCancelled timer -> "TimerCancelled " ++ show timer EventTimerFired timer -> "TimerFired " ++ show timer EventThreadStatus tid tid' -> From 19f22cec7e7b190db57f915ea85ec9a9ad53ef6a Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Mon, 20 Nov 2023 21:39:37 +0100 Subject: [PATCH 2/7] io-sim: improved haddocks --- io-sim/src/Control/Monad/IOSim.hs | 57 ++++++++++++---------- io-sim/src/Control/Monad/IOSim/Internal.hs | 8 +-- io-sim/src/Control/Monad/IOSim/Types.hs | 20 ++++++-- 3 files changed, 51 insertions(+), 34 deletions(-) diff --git a/io-sim/src/Control/Monad/IOSim.hs b/io-sim/src/Control/Monad/IOSim.hs index 45233afa..3398643c 100644 --- a/io-sim/src/Control/Monad/IOSim.hs +++ b/io-sim/src/Control/Monad/IOSim.hs @@ -133,6 +133,9 @@ import System.IO.Unsafe import qualified Debug.Trace as Debug +-- | Select events according to the predicate function. It throws an error if +-- the simulation ends with 'Failure'. +-- selectTraceEvents :: (Time -> SimEventType -> Maybe b) -> SimTrace a @@ -150,6 +153,9 @@ selectTraceEvents fn = [] . traceSelectTraceEvents fn +-- | Like 'selectTraceEvents', but it returns even if the simulation trace ends +-- with 'Failure'. +-- selectTraceEvents' :: (Time -> SimEventType -> Maybe b) -> SimTrace a @@ -216,10 +222,10 @@ detachTraceRaces = Trace.filter (\a -> case a of SimRacesFound {} -> False _ -> True) --- | Select all the traced values matching the expected type. This relies on --- the sim's dynamic trace facility. +-- | Select all the traced values matching the expected type. It relies on the +-- sim's dynamic trace facility. -- --- For convenience, this throws exceptions for abnormal sim termination. +-- For convenience, it throws exceptions for abnormal sim termination. -- selectTraceEventsDynamic :: forall a b. Typeable b => SimTrace a -> [b] selectTraceEventsDynamic = selectTraceEvents fn @@ -228,7 +234,8 @@ selectTraceEventsDynamic = selectTraceEvents fn fn _ (EventLog dyn) = fromDynamic dyn fn _ _ = Nothing --- | Like 'selectTraceEventsDynamic' but also captures time of the trace event. +-- | Like 'selectTraceEventsDynamic' but it also captures time of the trace +-- event. -- selectTraceEventsDynamicWithTime :: forall a b. Typeable b => SimTrace a -> [(Time, b)] selectTraceEventsDynamicWithTime = selectTraceEvents fn @@ -237,8 +244,8 @@ selectTraceEventsDynamicWithTime = selectTraceEvents fn fn t (EventLog dyn) = (t,) <$> fromDynamic dyn fn _ _ = Nothing --- | Like 'selectTraceEventsDynamic' but returns partial trace if an exception --- is found in it. +-- | Like 'selectTraceEventsDynamic' but it returns even if the simulation trace +-- ends with 'Failure'. -- selectTraceEventsDynamic' :: forall a b. Typeable b => SimTrace a -> [b] selectTraceEventsDynamic' = selectTraceEvents' fn @@ -247,7 +254,8 @@ selectTraceEventsDynamic' = selectTraceEvents' fn fn _ (EventLog dyn) = fromDynamic dyn fn _ _ = Nothing --- | Like `selectTraceEventsDynamic'` but also captures time of the trace event. +-- | Like `selectTraceEventsDynamic'` but it also captures time of the trace +-- event. -- selectTraceEventsDynamicWithTime' :: forall a b. Typeable b => SimTrace a -> [(Time, b)] selectTraceEventsDynamicWithTime' = selectTraceEvents' fn @@ -258,7 +266,7 @@ selectTraceEventsDynamicWithTime' = selectTraceEvents' fn -- | Get a trace of 'EventSay'. -- --- For convenience, this throws exceptions for abnormal sim termination. +-- For convenience, it throws exceptions for abnormal sim termination. -- selectTraceEventsSay :: SimTrace a -> [String] selectTraceEventsSay = selectTraceEvents fn @@ -267,7 +275,7 @@ selectTraceEventsSay = selectTraceEvents fn fn _ (EventSay s) = Just s fn _ _ = Nothing --- | Like 'selectTraceEventsSay' but also captures time of the trace event. +-- | Like 'selectTraceEventsSay' but it also captures time of the trace event. -- selectTraceEventsSayWithTime :: SimTrace a -> [(Time, String)] selectTraceEventsSayWithTime = selectTraceEvents fn @@ -276,8 +284,8 @@ selectTraceEventsSayWithTime = selectTraceEvents fn fn t (EventSay s) = Just (t, s) fn _ _ = Nothing --- | Like 'selectTraceEventsSay' but return partial trace if an exception is --- found in it. +-- | Like 'selectTraceEventsSay' but it returns even if the simulation trace +-- ends with 'Failure'. -- selectTraceEventsSay' :: SimTrace a -> [String] selectTraceEventsSay' = selectTraceEvents' fn @@ -286,7 +294,7 @@ selectTraceEventsSay' = selectTraceEvents' fn fn _ (EventSay s) = Just s fn _ _ = Nothing --- | Like `selectTraceEventsSay'` but also captures time of the trace event. +-- | Like `selectTraceEventsSay'` but it also captures time of the trace event. -- selectTraceEventsSayWithTime' :: SimTrace a -> [(Time, String)] selectTraceEventsSayWithTime' = selectTraceEvents' fn @@ -297,13 +305,13 @@ selectTraceEventsSayWithTime' = selectTraceEvents' fn -- | Print all 'EventSay' to the console. -- --- For convenience, this throws exceptions for abnormal sim termination. +-- For convenience, it throws exceptions for abnormal sim termination. -- printTraceEventsSay :: SimTrace a -> IO () printTraceEventsSay = mapM_ print . selectTraceEventsSay --- | The most general select function. It is a _total_ function. +-- | The most general select function. It is a /total function/. -- traceSelectTraceEvents :: (Time -> SimEventType -> Maybe b) @@ -324,7 +332,7 @@ traceSelectTraceEvents fn = bifoldr ( \ v _acc -> Nil v ) ) undefined -- it is ignored --- | Select dynamic events. It is a _total_ function. +-- | Select dynamic events. It is a /total function/. -- traceSelectTraceEventsDynamic :: forall a b. Typeable b => SimTrace a -> Trace (SimResult a) b @@ -335,7 +343,7 @@ traceSelectTraceEventsDynamic = traceSelectTraceEvents fn fn _ _ = Nothing --- | Select say events. It is a _total_ function. +-- | Select say events. It is a /total function/. -- traceSelectTraceEventsSay :: forall a. SimTrace a -> Trace (SimResult a) String traceSelectTraceEventsSay = traceSelectTraceEvents fn @@ -417,7 +425,7 @@ runSimOrThrow mainAction = runSimStrictShutdown :: forall a. (forall s. IOSim s a) -> Either Failure a runSimStrictShutdown mainAction = traceResult True (runSimTrace mainAction) --- | Fold through the trace and return either a 'Failure' or the simulation +-- | Fold through the trace and return either 'Failure' or a simulation -- result, i.e. the return value of the main thread. -- traceResult :: Bool @@ -502,19 +510,18 @@ runSimTrace mainAction = runST (runSimTraceST mainAction) -- slot. In /IOSim/ and /IOSimPOR/ time only moves explicitly through timer -- events, e.g. things like `Control.Monad.Class.MonadTimer.SI.threadDelay`, -- `Control.Monad.Class.MonadTimer.SI.registerDelay` or the --- `Control.Monad.Class.MonadTimer.NonStandard.MonadTimeout` API. The usual +-- `Control.Monad.Class.MonadTimer.MonadTimeout.NonStandard` API. The usual -- QuickCheck techniques can help explore different schedules of -- threads too. -- | Execute a simulation, discover & revert races. Note that this will execute -- the simulation multiple times with different schedules, and thus it's much -- more costly than a simple `runSimTrace` (also the simulation environments has --- much more state to track and hence is slower). +-- much more state to track and hence it is slower). -- -- On property failure it will show the failing schedule (`ScheduleControl`) --- which can be plugged to `controlSimTrace`. --- --- Note: `exploreSimTrace` evaluates each schedule in parallel (using `par`). +-- which can be passed to `controlSimTrace` to reproduce the failure without +-- discovering the schedule. -- exploreSimTrace :: forall a test. Testable test @@ -533,8 +540,6 @@ exploreSimTrace optsf main k = -- | An 'ST' version of 'exploreSimTrace'. The callback also receives -- 'ScheduleControl'. This is mostly useful for testing /IOSimPOR/ itself. -- --- Note: `exploreSimTraceST` evaluates each schedule sequentially. --- exploreSimTraceST :: forall s a test. Testable test => (ExplorationOptions -> ExplorationOptions) @@ -689,7 +694,7 @@ raceReversals ControlDefault = 0 raceReversals (ControlAwait mods) = length mods raceReversals ControlFollow{} = error "Impossible: raceReversals ControlFollow{}" --- compareTraces is given (maybe) a passing trace and a failing trace, +-- `compareTracesST` is given (maybe) a passing trace and a failing trace, -- and identifies the point at which they diverge, where it inserts a -- "sleep" event for the thread that is delayed in the failing case, -- and a "wake" event before its next action. It also returns the @@ -697,7 +702,7 @@ raceReversals ControlFollow{} = error "Impossible: raceReversals ControlFoll -- to be consumed lazily (and perhaps only partially), and since the -- sleeping thread is not of interest unless the trace is consumed -- this far, then we collect its identity only if it is reached using --- unsafePerformIO. +-- `unsafePerformIO`. -- TODO: return StepId compareTracesST :: forall a b s. diff --git a/io-sim/src/Control/Monad/IOSim/Internal.hs b/io-sim/src/Control/Monad/IOSim/Internal.hs index 4da5330d..4a383abe 100644 --- a/io-sim/src/Control/Monad/IOSim/Internal.hs +++ b/io-sim/src/Control/Monad/IOSim/Internal.hs @@ -991,10 +991,10 @@ lookupThreadLabel :: IOSimThreadId -> Map IOSimThreadId (Thread s a) -> Maybe Th lookupThreadLabel tid threads = join (threadLabel <$> Map.lookup tid threads) --- | The most general method of running 'IOSim' is in 'ST' monad. One can --- recover failures or the result from 'SimTrace' with --- 'Control.Monad.IOSim.traceResult', or access 'SimEventType's generated by the --- computation with 'Control.Monad.IOSim.traceEvents'. A slightly more +-- | The most general method of running 'IOSim' is in the lazy 'ST' monad. One +-- can recover failures or the result from 'SimTrace' with +-- 'Control.Monad.IOSim.traceResult', or access 'SimEventType's generated by +-- the computation with 'Control.Monad.IOSim.traceEvents'. A slightly more -- convenient way is exposed by 'Control.Monad.IOSim.runSimTrace'. -- runSimTraceST :: forall s a. IOSim s a -> ST s (SimTrace a) diff --git a/io-sim/src/Control/Monad/IOSim/Types.hs b/io-sim/src/Control/Monad/IOSim/Types.hs index cfa6075d..6fde8dcf 100644 --- a/io-sim/src/Control/Monad/IOSim/Types.hs +++ b/io-sim/src/Control/Monad/IOSim/Types.hs @@ -143,7 +143,7 @@ newtype IOSim s a = IOSim { unIOSim :: forall r. (a -> SimA s r) -> SimA s r } runIOSim :: IOSim s a -> SimA s a runIOSim (IOSim k) = k Return --- | 'IOSim' has the ability to story any 'Typeable' value in its trace which +-- | 'IOSim' has the ability to store any 'Typeable' value in its trace which -- can then be recovered with `selectTraceEventsDynamic` or -- `selectTraceEventsDynamic'`. -- @@ -234,7 +234,9 @@ data StmA s a where LiftSTStm :: StrictST.ST s a -> (a -> StmA s b) -> StmA s b FixStm :: (x -> STM s x) -> (x -> StmA s r) -> StmA s r --- Exported type +-- | `IOSim`'s 'MonadSTM.STM' monad, as 'IOSim' it is parametrised by @s@, e.g. +-- @STMSim s a@ is monadic expression of type @a@. +-- type STMSim = STM -- @@ -630,8 +632,9 @@ instance MonadST (IOSim s) where -- | Lift an 'StrictST.ST' computation to 'IOSim'. -- --- Note: you can use 'MonadST' to lift 'StrictST.ST' computations, this is just +-- Note: you can use 'MonadST' to lift 'StrictST.ST' computations, this is -- a more convenient function just for 'IOSim'. +-- liftST :: StrictST.ST s a -> IOSim s a liftST action = IOSim $ oneShot $ \k -> LiftST action k @@ -816,7 +819,7 @@ data SimResult a -- ^ Return value of the main thread. | MainException !Time !(Labelled IOSimThreadId) SomeException ![Labelled IOSimThreadId] -- ^ Exception thrown by the main thread. - | Deadlock !Time ![Labelled IOSimThreadId] + | Deadlock !Time ![Labelled IOSimThreadId] -- ^ Deadlock discovered in the simulation. Deadlocks are discovered if -- simply the simulation cannot do any progress in a given time slot and -- there's no event which would advance the time. @@ -824,6 +827,7 @@ data SimResult a -- ^ Only returned by /IOSimPOR/ when a step execution took longer than -- 'explorationStepTimelimit` was exceeded. | InternalError String + -- ^ An `IOSim` bug, please report to deriving (Show, Functor) ppSimResult :: Show a @@ -874,6 +878,12 @@ type SimTrace a = Trace.Trace (SimResult a) SimEvent -- | Pretty print simulation trace. -- +-- Note: this is not a streaming function, it will evaluate the whole trace +-- before printing it. If you need to print a very large trace, you might want +-- to use +-- +-- @'Trace.ppTrace' show ('ppSimEvent' 0 0 0)@ +-- ppTrace :: Show a => SimTrace a -> String ppTrace tr = Trace.ppTrace (ppSimResult timeWidth tidWidth labelWidth) @@ -1083,6 +1093,8 @@ data SimEventType | EventPerformAction StepId -- ^ /IOSimPOR/ event: perform action of the given step | EventReschedule ScheduleControl + -- ^ /IOSimPOR/ event: reschedule a thread following the given + -- `ScheduleControl` | EventEffect VectorClock Effect -- ^ /IOSimPOR/ event: executed effect; Useful for debugging IOSimPOR or From 3a46912bf927f3b6ce17f7b8e979844ed1ee3b49 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Mon, 20 Nov 2023 21:40:59 +0100 Subject: [PATCH 3/7] io-classes: removed a deprecated module --- io-classes/CHANGELOG.md | 2 ++ io-classes/io-classes.cabal | 1 - io-classes/src/Control/Monad/Class/MonadMVar.hs | 3 --- 3 files changed, 2 insertions(+), 4 deletions(-) delete mode 100644 io-classes/src/Control/Monad/Class/MonadMVar.hs diff --git a/io-classes/CHANGELOG.md b/io-classes/CHANGELOG.md index 6b2e6266..bc227f7f 100644 --- 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/io-classes.cabal b/io-classes/io-classes.cabal index 8bc37dc1..d5ca6802 100644 --- a/io-classes/io-classes.cabal +++ b/io-classes/io-classes.cabal @@ -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/MonadMVar.hs b/io-classes/src/Control/Monad/Class/MonadMVar.hs deleted file mode 100644 index 637b3649..00000000 --- a/io-classes/src/Control/Monad/Class/MonadMVar.hs +++ /dev/null @@ -1,3 +0,0 @@ -module Control.Monad.Class.MonadMVar {-# DEPRECATED "Use Control.Concurrent.Class.MonadMVar" #-} (module X) where - -import Control.Concurrent.Class.MonadMVar as X \ No newline at end of file From ddb44a08f1ab482aa661797d94e60981d57fcee3 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Mon, 20 Nov 2023 21:39:48 +0100 Subject: [PATCH 4/7] io-classes: improved haddocks --- io-classes/src/Control/Monad/Class/MonadAsync.hs | 4 ++++ io-classes/src/Control/Monad/Class/MonadFork.hs | 4 ++++ io-classes/src/Control/Monad/Class/MonadTest.hs | 2 +- io-classes/src/Control/Monad/Class/MonadThrow.hs | 4 ++++ io-classes/src/Control/Monad/Class/MonadTime.hs | 4 ++++ io-classes/src/Control/Monad/Class/MonadTimer.hs | 5 ++++- 6 files changed, 21 insertions(+), 2 deletions(-) diff --git a/io-classes/src/Control/Monad/Class/MonadAsync.hs b/io-classes/src/Control/Monad/Class/MonadAsync.hs index b120efd0..633f565c 100644 --- 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 #-} + +-- | API compatible with both +-- 'IO' and . +-- 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 index e83afb8e..44d92292 100644 --- 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 +-- +-- API to both 'IO' and . +-- module Control.Monad.Class.MonadFork ( MonadThread (..) , labelThisThread diff --git a/io-classes/src/Control/Monad/Class/MonadTest.hs b/io-classes/src/Control/Monad/Class/MonadTest.hs index a53c645f..7cf86d9f 100644 --- 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 index 96f5cd9a..f3e50c55 100644 --- 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 +-- +-- API to both 'IO' and . +-- 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 index 3a7434dd..4308842c 100644 --- a/io-classes/src/Control/Monad/Class/MonadTime.hs +++ b/io-classes/src/Control/Monad/Class/MonadTime.hs @@ -1,5 +1,9 @@ {-# LANGUAGE DeriveGeneric #-} +-- | and +-- time API compatible with both +-- 'IO' and . +-- 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 index 433d17ee..fbbffd2f 100644 --- 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 +-- API to both 'IO' and +-- . +-- module Control.Monad.Class.MonadTimer ( MonadDelay (..) , MonadTimer (..) From dd1f489c651f280f338a4e23bc905b792d3e53e7 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sat, 2 Dec 2023 13:07:54 +0100 Subject: [PATCH 5/7] io-classes: updated README.md Moved the differences section to `io-classes`, removed entries which are no longer true and added one about `Deadlock` exceptions. Technically this is a difference between `io-sim` and `GHC` `RTS`, but it makes more sense to document it in `io-classes`. --- README.md | 34 ---------------------------------- io-classes/README.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index c7774fd3..d53bda7d 100644 --- 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/README.md b/io-classes/README.md index a6377274..1fd010b5 100644 --- 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 From 39686f26d45a6fd4861d6f56b3df3f7c99c3d12b Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sat, 2 Dec 2023 19:23:48 +0100 Subject: [PATCH 6/7] io-sim: IOSim's Alternative and MonadPlus instances --- io-sim/CHANGELOG.md | 2 ++ io-sim/src/Control/Monad/IOSim/Types.hs | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/io-sim/CHANGELOG.md b/io-sim/CHANGELOG.md index 8c776bc6..7565b770 100644 --- a/io-sim/CHANGELOG.md +++ b/io-sim/CHANGELOG.md @@ -8,6 +8,8 @@ ### Non-breaking changes +* `Alternative` & `MonadPlus` instances for `IOSim`. + ## 1.3.1.0 ### Non-breaking changes diff --git a/io-sim/src/Control/Monad/IOSim/Types.hs b/io-sim/src/Control/Monad/IOSim/Types.hs index 6fde8dcf..183c67a2 100644 --- a/io-sim/src/Control/Monad/IOSim/Types.hs +++ b/io-sim/src/Control/Monad/IOSim/Types.hs @@ -12,6 +12,7 @@ {-# LANGUAGE NumericUnderscores #-} {-# LANGUAGE PatternSynonyms #-} {-# LANGUAGE RankNTypes #-} +{-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeFamilies #-} -- Needed for `SimEvent` type. @@ -136,6 +137,7 @@ import Control.Monad.IOSimPOR.Types import qualified System.IO.Error as IO.Error (userError) import Data.List (intercalate) +import GHC.IO (mkUserError) {-# ANN module "HLint: ignore Use readTVarIO" #-} newtype IOSim s a = IOSim { unIOSim :: forall r. (a -> SimA s r) -> SimA s r } @@ -287,6 +289,11 @@ instance Fail.MonadFail (IOSim s) where instance MonadFix (IOSim s) where mfix f = IOSim $ oneShot $ \k -> Fix f k +instance Alternative (IOSim s) where + empty = throwIO (mkUserError "mzero") + (<|>) !a b = a `catch` \(_ :: IOError) -> b + +instance MonadPlus (IOSim s) instance Functor (STM s) where {-# INLINE fmap #-} From 79f1951af05e3cd86835f5f43c1ae397ff775d7d Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Tue, 2 Jan 2024 11:22:56 +0100 Subject: [PATCH 7/7] Updated cabal & NOTICE files --- NOTICE | 2 +- io-classes-mtl/NOTICE | 2 +- io-classes-mtl/io-classes-mtl.cabal | 2 +- io-classes/NOTICE | 2 +- io-classes/io-classes.cabal | 2 +- io-sim/NOTICE | 2 +- io-sim/io-sim.cabal | 2 +- si-timers/NOTICE | 2 +- si-timers/si-timers.cabal | 2 +- strict-mvar/NOTICE | 2 +- strict-mvar/strict-mvar.cabal | 2 +- strict-stm/NOTICE | 2 +- strict-stm/strict-stm.cabal | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/NOTICE b/NOTICE index acd2b2cd..d9803424 100644 --- 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/io-classes-mtl/NOTICE b/io-classes-mtl/NOTICE index 031c8ce0..c351c4bf 100644 --- 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 index db755237..7cc0487f 100644 --- 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/NOTICE b/io-classes/NOTICE index acd2b2cd..d9803424 100644 --- 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/io-classes.cabal b/io-classes/io-classes.cabal index d5ca6802..cbf7198b 100644 --- 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 diff --git a/io-sim/NOTICE b/io-sim/NOTICE index acd2b2cd..d9803424 100644 --- 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 index b91d0e8c..0c1965c5 100644 --- 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 diff --git a/si-timers/NOTICE b/si-timers/NOTICE index acd2b2cd..d9803424 100644 --- a/si-timers/NOTICE +++ b/si-timers/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/si-timers/si-timers.cabal b/si-timers/si-timers.cabal index 3b00cc1c..a2bac1e2 100644 --- a/si-timers/si-timers.cabal +++ b/si-timers/si-timers.cabal @@ -7,7 +7,7 @@ description: compatible with [io-sim](https://hackage.haskell.org/package/io-sim). 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: Duncan Coutts, Neil Davis, Marcin Szamotulski maintainer: Duncan Coutts duncan@well-typed.com, Marcin Szamotulski coot@coot.me category: Time diff --git a/strict-mvar/NOTICE b/strict-mvar/NOTICE index 15b771a0..4763d79e 100644 --- a/strict-mvar/NOTICE +++ b/strict-mvar/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/strict-mvar/strict-mvar.cabal b/strict-mvar/strict-mvar.cabal index bdfcbe34..87881f6f 100644 --- a/strict-mvar/strict-mvar.cabal +++ b/strict-mvar/strict-mvar.cabal @@ -8,7 +8,7 @@ description: & [io-sim](https://hackage.haskell.org/package/io-sim). 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: IOG Engineering Team maintainer: operations@iohk.io category: Concurrency diff --git a/strict-stm/NOTICE b/strict-stm/NOTICE index acd2b2cd..d9803424 100644 --- a/strict-stm/NOTICE +++ b/strict-stm/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/strict-stm/strict-stm.cabal b/strict-stm/strict-stm.cabal index b8413fa1..d28f66d1 100644 --- a/strict-stm/strict-stm.cabal +++ b/strict-stm/strict-stm.cabal @@ -9,7 +9,7 @@ description: & [io-sim](https://hackage.haskell.org/package/io-sim). 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 dunca@well-typed.com, Marcin Szamotulski coot@coot.me category: Concurrency