timeouts and exceptions

CONTRIBUTING.md

@@ -30,6 +30,34 @@ The `typed-protocols-examples` package contains two simple protocols `PingPong`
 cabal run typed-protocols-examples:test
 ```
 
+If you contribute a more complex feature, it might be a good idea to run the
+tests suites from the `ouroboros-network` repository, especially:
+
+* `network-mux:test`
+* `ouroboros-network-framework:test`
+* `ouroboros-network:test`
+
+If you've been working on `IOSimPOR`, please enable the `nightly` cabal flag in
+the `ouroboros-network-testing` framework.  To configure `ouroboros-network`
+repository with the right `io-sim` you can include the following snippet in
+`cabal.project.local` file:
+```
+source-repository-package
+  type: git
+  location: <local .git directory; ssh or http url>
+  tag: <hash of the commit, branch name, etc>
+  subdir:
+    io-classes
+    io-classes-mtl
+    io-sim
+    si-timers
+    strict-stm
+    strict-mvar
+
+package ouroboros-network-testing
+  flags: +nightly
+```
+
 # Code Style
 
 Please follow local style.  For a more detailed style guide see
@@ -73,6 +101,29 @@ 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.
 
+# 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
+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
+`schedule` function you need to:
+```hs
+    ...
+    !_ <- Debug.Trace.traceM "hello"
+    ...
+```
+
+
 
 [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

io-sim/src/Control/Monad/IOSim/CommonTypes.hs

@@ -13,6 +13,8 @@ import           Data.Map (Map)
 import           Data.STRef.Lazy
 import           Data.Set (Set)
 
+import qualified GHC.Conc as GHC
+
 data ThreadId = RacyThreadId [Int]
               | ThreadId     [Int]    -- non racy threads have higher priority
   deriving (Eq, Ord, Show)
@@ -84,5 +86,32 @@ data FinishedReason = FinishedNormally
                     | FinishedDied
                     deriving (Ord, Eq, Show, Enum, Bounded)
 
-data Deschedule = Yield | Interruptable | Blocked | Terminated FinishedReason | Sleep
+data Deschedule = Yield
+                | Interruptable
+                | Blocked BlockedReason
+                | Terminated FinishedReason
+                | Sleep
   deriving Show
+
+-- TODO: we should track threads which died and finished as the
+-- `GHC.ThreadStatus` does (`IOSim` does not track this information).
+--
+data ThreadStatus = ThreadRunning
+                  | ThreadBlocked BlockedReason
+                  | ThreadFinished
+                  | ThreadDied
+  deriving (Eq, Show)
+
+data BlockedReason = BlockedOnSTM
+                   | BlockedOnOther
+  deriving (Eq, Show)
+
+ghcThreadStatus :: ThreadStatus -> GHC.ThreadStatus
+ghcThreadStatus ThreadRunning  = GHC.ThreadRunning
+ghcThreadStatus (ThreadBlocked reason) =
+    case reason of
+      BlockedOnSTM   -> GHC.ThreadBlocked GHC.BlockedOnSTM
+      BlockedOnOther -> GHC.ThreadBlocked GHC.BlockedOnOther
+ghcThreadStatus ThreadFinished = GHC.ThreadFinished
+ghcThreadStatus ThreadDied     = GHC.ThreadDied
+