nqe 0.6.9 → 0.7.0
raw patch · 10 files changed
+767/−534 lines, 10 filesdep −mtldep −unliftiosetup-changedPVP ok
version bump matches the API change (PVP)
Dependencies removed: mtl, unliftio
API changes (from Hackage documentation)
+ Control.Concurrent.NQE.Supervisor: AsyncChildException :: SomeException -> AsyncChildException
+ Control.Concurrent.NQE.Supervisor: instance GHC.Internal.Exception.Type.Exception Control.Concurrent.NQE.Supervisor.AsyncChildException
+ Control.Concurrent.NQE.Supervisor: instance GHC.Internal.Show.Show Control.Concurrent.NQE.Supervisor.AsyncChildException
+ Control.Concurrent.NQE.Supervisor: newtype AsyncChildException
- Control.Concurrent.NQE.Conduit: conduitMailbox :: forall (m :: Type -> Type) mbox msg o. (MonadIO m, OutChan mbox, Typeable msg) => mbox msg -> ConduitT msg o m ()
+ Control.Concurrent.NQE.Conduit: conduitMailbox :: (OutChan mbox, Typeable msg) => mbox msg -> ConduitT msg o IO ()
- Control.Concurrent.NQE.Process: mailboxEmpty :: (MonadIO m, InChan mbox) => mbox msg -> m Bool
+ Control.Concurrent.NQE.Process: mailboxEmpty :: InChan mbox => mbox msg -> IO Bool
- Control.Concurrent.NQE.Process: newBoundedInbox :: MonadIO m => Natural -> m (Inbox msg)
+ Control.Concurrent.NQE.Process: newBoundedInbox :: Natural -> IO (Inbox msg)
- Control.Concurrent.NQE.Process: newInbox :: MonadIO m => m (Inbox msg)
+ Control.Concurrent.NQE.Process: newInbox :: IO (Inbox msg)
- Control.Concurrent.NQE.Process: newMailbox :: MonadUnliftIO m => m (Inbox msg, Mailbox msg)
+ Control.Concurrent.NQE.Process: newMailbox :: IO (Inbox msg, Mailbox msg)
- Control.Concurrent.NQE.Process: process :: MonadUnliftIO m => (Inbox msg -> m ()) -> m (Process msg)
+ Control.Concurrent.NQE.Process: process :: (Inbox msg -> IO ()) -> IO (Process msg)
- Control.Concurrent.NQE.Process: query :: (MonadIO m, OutChan mbox) => (Listen response -> request) -> mbox request -> m response
+ Control.Concurrent.NQE.Process: query :: OutChan mbox => (Listen response -> request) -> mbox request -> IO response
- Control.Concurrent.NQE.Process: queryS :: (MonadUnliftIO m, OutChan mbox) => Int -> (Listen response -> request) -> mbox request -> m (Maybe response)
+ Control.Concurrent.NQE.Process: queryS :: OutChan mbox => Int -> (Listen response -> request) -> mbox request -> IO (Maybe response)
- Control.Concurrent.NQE.Process: queryU :: (MonadUnliftIO m, OutChan mbox) => Int -> (Listen response -> request) -> mbox request -> m (Maybe response)
+ Control.Concurrent.NQE.Process: queryU :: OutChan mbox => Int -> (Listen response -> request) -> mbox request -> IO (Maybe response)
- Control.Concurrent.NQE.Process: receive :: (InChan mbox, MonadIO m) => mbox msg -> m msg
+ Control.Concurrent.NQE.Process: receive :: InChan mbox => mbox msg -> IO msg
- Control.Concurrent.NQE.Process: receiveMatch :: (MonadIO m, InChan mbox) => mbox msg -> (msg -> Maybe a) -> m a
+ Control.Concurrent.NQE.Process: receiveMatch :: InChan mbox => mbox msg -> (msg -> Maybe a) -> IO a
- Control.Concurrent.NQE.Process: receiveMatchS :: (MonadUnliftIO m, InChan mbox) => Int -> mbox msg -> (msg -> Maybe a) -> m (Maybe a)
+ Control.Concurrent.NQE.Process: receiveMatchS :: InChan mbox => Int -> mbox msg -> (msg -> Maybe a) -> IO (Maybe a)
- Control.Concurrent.NQE.Process: receiveMatchU :: (MonadUnliftIO m, InChan mbox) => Int -> mbox msg -> (msg -> Maybe a) -> m (Maybe a)
+ Control.Concurrent.NQE.Process: receiveMatchU :: InChan mbox => Int -> mbox msg -> (msg -> Maybe a) -> IO (Maybe a)
- Control.Concurrent.NQE.Process: send :: (MonadIO m, OutChan mbox) => msg -> mbox msg -> m ()
+ Control.Concurrent.NQE.Process: send :: OutChan mbox => msg -> mbox msg -> IO ()
- Control.Concurrent.NQE.Process: withProcess :: MonadUnliftIO m => (Inbox msg -> m ()) -> (Process msg -> m a) -> m a
+ Control.Concurrent.NQE.Process: withProcess :: (Inbox msg -> IO ()) -> (Process msg -> IO a) -> IO a
- Control.Concurrent.NQE.Process: wrapChannel :: (MonadIO m, InChan mbox, OutChan mbox) => mbox msg -> m (Inbox msg)
+ Control.Concurrent.NQE.Process: wrapChannel :: (InChan mbox, OutChan mbox) => mbox msg -> IO (Inbox msg)
- Control.Concurrent.NQE.Publisher: publish :: MonadIO m => msg -> Publisher msg -> m ()
+ Control.Concurrent.NQE.Publisher: publish :: msg -> Publisher msg -> IO ()
- Control.Concurrent.NQE.Publisher: publisher :: MonadUnliftIO m => m (Publisher msg)
+ Control.Concurrent.NQE.Publisher: publisher :: IO (Publisher msg)
- Control.Concurrent.NQE.Publisher: publisherProcess :: MonadUnliftIO m => Inbox (PublisherMessage msg) -> m ()
+ Control.Concurrent.NQE.Publisher: publisherProcess :: Inbox (PublisherMessage msg) -> IO ()
- Control.Concurrent.NQE.Publisher: subscribe :: MonadIO m => Publisher msg -> Listen msg -> m (Subscriber msg)
+ Control.Concurrent.NQE.Publisher: subscribe :: Publisher msg -> Listen msg -> IO (Subscriber msg)
- Control.Concurrent.NQE.Publisher: unsubscribe :: MonadIO m => Publisher msg -> Subscriber msg -> m ()
+ Control.Concurrent.NQE.Publisher: unsubscribe :: Publisher msg -> Subscriber msg -> IO ()
- Control.Concurrent.NQE.Publisher: withPublisher :: MonadUnliftIO m => (Publisher msg -> m a) -> m a
+ Control.Concurrent.NQE.Publisher: withPublisher :: (Publisher msg -> IO a) -> IO a
- Control.Concurrent.NQE.Publisher: withSubscription :: MonadUnliftIO m => Publisher msg -> (Inbox msg -> m a) -> m a
+ Control.Concurrent.NQE.Publisher: withSubscription :: Publisher msg -> (Inbox msg -> IO a) -> IO a
- Control.Concurrent.NQE.Supervisor: addChild :: MonadIO m => Supervisor -> ChildAction -> m Child
+ Control.Concurrent.NQE.Supervisor: addChild :: Supervisor -> ChildAction -> IO Child
- Control.Concurrent.NQE.Supervisor: removeChild :: MonadIO m => Supervisor -> Child -> m ()
+ Control.Concurrent.NQE.Supervisor: removeChild :: Supervisor -> Child -> IO ()
- Control.Concurrent.NQE.Supervisor: supervisor :: MonadUnliftIO m => Strategy -> m Supervisor
+ Control.Concurrent.NQE.Supervisor: supervisor :: Strategy -> IO Supervisor
- Control.Concurrent.NQE.Supervisor: supervisorProcess :: MonadUnliftIO m => Strategy -> Inbox SupervisorMessage -> m ()
+ Control.Concurrent.NQE.Supervisor: supervisorProcess :: Strategy -> Inbox SupervisorMessage -> IO ()
- Control.Concurrent.NQE.Supervisor: withSupervisor :: MonadUnliftIO m => Strategy -> (Supervisor -> m a) -> m a
+ Control.Concurrent.NQE.Supervisor: withSupervisor :: Strategy -> (Supervisor -> IO a) -> IO a
Files
- CHANGELOG.md +55/−0
- README.md +40/−18
- Setup.hs +1/−0
- nqe.cabal +3/−5
- src/Control/Concurrent/NQE/Conduit.hs +21/−18
- src/Control/Concurrent/NQE/Process.hs +228/−211
- src/Control/Concurrent/NQE/Publisher.hs +121/−119
- src/Control/Concurrent/NQE/Supervisor.hs +100/−35
- src/NQE.hs +41/−38
- test/Spec.hs +157/−90
CHANGELOG.md view
@@ -4,6 +4,61 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## 0.7.0 - 2026-11-15+### Changed+- Every function runs in plain `IO` (or `STM`, as before) instead of any+ `MonadIO` or `MonadUnliftIO` monad. This breaks backwards compatibility.+ Names and argument orders are the same.+- `conduitMailbox` is a `ConduitT msg o IO ()`.+- A supervisor with the `KillAll` or `IgnoreGraceful` strategy re-throws an+ asynchronous exception that stopped a child wrapped in the new+ `AsyncChildException`. It used to be wrapped in `SyncExceptionWrapper` from+ `unliftio`. Other exceptions are re-thrown unchanged, as before.+- The publisher loop uses `forever`. The workaround of 0.6.7 was only needed+ for `LoggingT`.++### Fixed+- A child of a supervisor that never blocks can be stopped. Children ran+ with asynchronous exceptions masked, because the supervisor forks them+ inside the mask under which it registers them, and a forked thread+ inherits the mask. Such a child could be interrupted only where it+ blocked: one that computed in a loop could not be cancelled, a `timeout`+ inside it never fired, and `removeChild` and the end of its supervisor+ waited for it for good. Children now start unmasked.++### Added+- `AsyncChildException`.+- Tests for timeouts, for `withSubscription`, for a supervised child that+ is cancelled directly, and for children that never block.++### Removed+- The dependencies on `unliftio` and `mtl`. The library now depends on `async`+ directly.++### Migrating+- Code that already runs in `IO` needs no change to its calls. If it imported+ `UnliftIO` only to use NQE, it can take `atomically` from+ `Control.Concurrent.STM`, `threadDelay` from `Control.Concurrent`, `cancel`+ and `Async` from `Control.Concurrent.Async`, and exceptions from+ `Control.Exception`.+- Code in another monad has to lift: `liftIO (send msg mbox)`. For the+ functions that take an action (`withProcess`, `process`, `withSupervisor`,+ `withPublisher`, `withSubscription`), run your monad inside the `IO` action.+ With a `ReaderT env IO` stack, for example:++ ```haskell+ env <- ask+ liftIO $ withProcess (\inbox -> runReaderT (server inbox) env) $ \p ->+ runReaderT (client p) env+ ```++- In a conduit over another monad, write `transPipe liftIO (conduitMailbox m)`.+- If you match on `SyncExceptionWrapper` in an exception re-thrown by a+ supervisor, match on `AsyncChildException` instead.+- The behaviour with exceptions is otherwise the same as in 0.6.9: supervisors+ stop their children, and `withSubscription` unsubscribes, with asynchronous+ exceptions blocked uninterruptibly.+ ## 0.6.9 ### Added - More and better documentation than in version 0.6.8.
README.md view
@@ -8,10 +8,9 @@ that start and watch over them, and publishers that broadcast messages to subscribers. -Everything is built on [STM](https://hackage.haskell.org/package/stm) and-[unliftio](https://hackage.haskell.org/package/unliftio). It works in `IO` and-in any monad with a `MonadUnliftIO` instance, such as `ReaderT` stacks or-`LoggingT`. It has no C dependencies.+Everything is built on [stm](https://hackage.haskell.org/package/stm) and+[async](https://hackage.haskell.org/package/async), and runs in plain `IO` and+`STM`. It has no C dependencies. - [API documentation](https://hackage.haskell.org/package/nqe) - [Changelog](https://github.com/jprupp/nqe/blob/master/CHANGELOG.md)@@ -77,6 +76,11 @@ - **Scoped lifetimes.** The `with` functions tie a process, supervisor or subscription to a block of code, so it cannot outlive it, even on an exception.+- **Plain `IO`.** Every action is an `IO` or `STM` action from the ordinary+ `base`, `stm` and `async` libraries. Signatures are short, and exceptions+ follow the rules of `Control.Exception`, with nothing in between. The cost is+ that code in a monad transformer stack has to `liftIO` its calls to NQE; see+ [Things to watch out for](#things-to-watch-out-for). - **Not quite Erlang.** No distribution, no registry, no hot code reloading and no automatic restarts. Those features add a lot of machinery that most Haskell programs never use. Supervisors report deaths; your code decides@@ -118,7 +122,7 @@ cd nqe-demo ``` - In `nqe-demo.cabal`, add `nqe` and `unliftio` to `build-depends` of the+ In `nqe-demo.cabal`, add `nqe` and `stm` to `build-depends` of the executable. 3. Paste the [quick start](#quick-start) program into `src/Main.hs`. 4. Build and run it:@@ -137,7 +141,7 @@ cabal init --non-interactive --exe ``` -Add `nqe` and `unliftio` to `build-depends` in `nqe-demo.cabal`, put the quick+Add `nqe` and `stm` to `build-depends` in `nqe-demo.cabal`, put the quick start program in `app/Main.hs`, and run it with `cabal run`. ### Adding NQE to an existing project@@ -148,7 +152,7 @@ build-depends: base , nqe- , unliftio+ , stm ``` With Stack and hpack, list it in `package.yaml`:@@ -156,15 +160,18 @@ ```yaml dependencies: - nqe- - unliftio+ - stm ``` +`stm` is there for `atomically`, which you need to run a `Listen` callback.++ If your Stack resolver does not include NQE, or has an older version, add it to `stack.yaml`: ```yaml extra-deps:- - nqe-0.6.8+ - nqe-0.7.0 ``` ## Quick start@@ -172,9 +179,9 @@ A server that answers `Ping` with `Pong`, and a client that asks it once: ```haskell+import Control.Concurrent.STM (atomically) import Control.Monad (forever) import NQE-import UnliftIO data Pong = Pong deriving Show @@ -245,10 +252,10 @@ ```haskell {-# LANGUAGE LambdaCase #-} +import Control.Concurrent (threadDelay)+import Control.Concurrent.STM (atomically) import Control.Monad (replicateM_) import NQE-import UnliftIO-import UnliftIO.Concurrent (threadDelay) main :: IO () main = do@@ -312,8 +319,8 @@ ### Thread linking -`withProcess` and `process` link the new thread to the caller with-`UnliftIO.link`. An exception in the child is re-thrown in the parent as an+`withProcess` and `process` link the new thread to the caller with `link` from+the `async` package. An exception in the child is re-thrown in the parent as an `ExceptionInLinkedThread`, so a failing process is never silent. ## Usage guide@@ -375,10 +382,17 @@ mainLoop ``` -When the supervisor stops, it cancels all its children. Children run in `IO`;-use `withRunInIO` or `toIO` to turn an action in your own monad into a-`ChildAction`.+When the supervisor stops, it cancels all its children and waits for them. It+does that with asynchronous exceptions blocked, so cancelling the supervisor+twice cannot leave children behind. +`KillAll` and `IgnoreGraceful` re-throw the exception that stopped a child. If+the child died of an asynchronous exception, for example because some other+thread called `cancel` on it instead of `removeChild`, the supervisor throws it+wrapped in `AsyncChildException`. That keeps it an error: thrown unwrapped, an+`AsyncCancelled` would pass for a normal cancellation of the supervisor and+nobody would be told. `Notify` always gets the original exception.+ ### Publishers ```haskell@@ -400,7 +414,8 @@ runConduit $ sourceHandle stdin .| linesUnboundedAsciiC .| conduitMailbox mbox ``` -With a bounded mailbox, a slow consumer slows down the producer.+With a bounded mailbox, a slow consumer slows down the producer. The sink runs+in `IO`; in a pipeline over another monad, use `transPipe liftIO`. ## Module overview @@ -424,6 +439,13 @@ unsubscribe leaks the callback and everything it refers to. - `withSubscription` uses an unbounded inbox. Read from it, or it grows without limit.+- Everything runs in `IO`. From a `ReaderT` or `LoggingT` stack, call NQE with+ `liftIO`, and run the stack again inside the `IO` action that you give to+ `withProcess`, `addChild` and the like. Versions before 0.7.0 did this for+ you; the [changelog](CHANGELOG.md) says how to migrate.+- Do not catch `SomeException` around NQE calls without letting asynchronous+ exceptions through. `cancel` and the linking of threads work by throwing+ them, and a handler that swallows them leaves threads that cannot be stopped. ## Development
Setup.hs view
@@ -1,2 +1,3 @@ import Distribution.Simple+ main = defaultMain
nqe.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: nqe-version: 0.6.9+version: 0.7.0 synopsis: Concurrency library in the style of Erlang/OTP description: Please see the README on GitHub at <https://github.com/jprupp/nqe#readme> category: Control@@ -36,14 +36,13 @@ hs-source-dirs: src build-depends:- base >=4.8 && <5+ async+ , base >=4.8 && <5 , conduit , containers , hashable- , mtl , stm , unique- , unliftio default-language: Haskell2010 test-suite nqe-test@@ -66,5 +65,4 @@ , stm , stm-conduit , text- , unliftio default-language: Haskell2010
src/Control/Concurrent/NQE/Conduit.hs view
@@ -1,21 +1,21 @@-{-# LANGUAGE FlexibleContexts #-}+{-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE MultiParamTypeClasses #-}-{-# LANGUAGE RankNTypes #-}-{-|-Module : Control.Concurrent.NQE.Conduit-Copyright : Haskoin Developers-License : MIT-Maintainer : jprupp@protonmail.ch-Stability : experimental-Portability : POSIX+{-# LANGUAGE RankNTypes #-} -Mix NQE processes with conduits for easy concurrent IO.--}+-- |+-- Module : Control.Concurrent.NQE.Conduit+-- Copyright : Haskoin Developers+-- License : MIT+-- Maintainer : jprupp@protonmail.ch+-- Stability : experimental+-- Portability : POSIX+--+-- Mix NQE processes with conduits for easy concurrent IO. module Control.Concurrent.NQE.Conduit where -import Conduit-import Control.Concurrent.NQE.Process-import Data.Typeable+import Conduit+import Control.Concurrent.NQE.Process+import Data.Typeable -- | Consumes messages from a 'Conduit' and sends them to a channel. --@@ -30,8 +30,11 @@ -- This is the bridge between streaming code and processes: a conduit that reads -- a socket or a file can feed a process directly, and a bounded mailbox turns the -- process's pace into back-pressure on the stream.+--+-- Like the rest of NQE it runs in 'IO'. In a pipeline over another monad,+-- change its monad with @'transPipe' 'liftIO'@. conduitMailbox ::- (MonadIO m, OutChan mbox, Typeable msg)- => mbox msg- -> ConduitT msg o m ()-conduitMailbox mbox = awaitForever (`send` mbox)+ (OutChan mbox, Typeable msg) =>+ mbox msg ->+ ConduitT msg o IO ()+conduitMailbox mbox = awaitForever (liftIO . (`send` mbox))
src/Control/Concurrent/NQE/Process.hs view
@@ -1,107 +1,118 @@ {-# LANGUAGE ExistentialQuantification #-}-{-# LANGUAGE FlexibleContexts #-}-{-# LANGUAGE FlexibleInstances #-}-{-# LANGUAGE MultiParamTypeClasses #-}-{-# LANGUAGE RankNTypes #-}-{-|-Module : Control.Concurrent.NQE.Process-Copyright : Haskoin Developers-License : MIT-Maintainer : jprupp@protonmail.ch-Stability : experimental-Portability : POSIX--This is the core of the NQE library. It is composed of code to deal with-processes and mailboxes. Processes represent concurrent threads that receive-messages via a mailbox, also referred to as a channel. NQE is inspired by-Erlang/OTP and it stands for “Not Quite Erlang”. A process is analogous to an-actor in Scala, or an object in the original (Alan Kay) sense of the word. To-implement synchronous communication NQE makes use of 'STM' actions embedded in-asynchronous messages.--= Why processes and mailboxes--Shared mutable state is the usual source of trouble in concurrent programs:-two threads change the same thing, and the result depends on timing. The-Erlang answer, which NQE borrows, is to give each piece of state an owner. A-process owns its state outright, and other threads can only ask it to do-things by sending messages. The process handles one message at a time, so its-state is never seen half-changed and needs no locks.--Haskell already has excellent building blocks for this: lightweight threads,-'STM' and the @async@ package. NQE does not replace them. It is a thin layer-that names the patterns people end up writing by hand on top of them, so that-programs built from many cooperating threads read the same way everywhere.--= Design choices--* __Everything is STM.__ Channels are 'TQueue' or 'TBQueue', and replies are- 'STM' actions. This means a send, a receive and a reply can be combined with- any other transaction, and selective receive ('receiveMatch') can be done- atomically.--* __Replies are callbacks, not return channels.__ A request carries a 'Listen'- action that the receiver runs. The sender decides where the reply goes: a- 'TMVar' for 'query', a queue for a stream of replies, or nowhere at all.- The receiver does not need to know.--* __Sending and receiving are separate capabilities.__ An 'Inbox' can receive;- a 'Mailbox' can only send. Handing out a 'Mailbox' lets other threads talk to- a process without being able to steal its messages.--* __Bounded channels give back-pressure.__ A fast producer writing to a- bounded inbox blocks until the consumer catches up, instead of filling- memory.--* __Failures are loud.__ 'withProcess' and 'process' link the new thread to its- parent, so an exception in a process is re-thrown in the thread that started- it rather than disappearing.--* __Not quite Erlang.__ There is no distribution, no process registry, no- hot code loading and no automatic restarts. Those features cost a lot of- complexity and most Haskell programs that want actors do not need them.--= Overview--* An 'Inbox' is the receiving end of a channel. Only the process that owns it- should read from it.-* A 'Mailbox' is the sending end of the same channel. It can be shared freely- with any thread that needs to talk to the process.-* A 'Process' bundles the 'Async' handle of a running thread together with its- 'Mailbox'.--Channels can be unbounded ('newInbox') or bounded ('newBoundedInbox'). Sending-to a full bounded channel blocks until there is space.--= Synchronous requests--Request/response communication is done by embedding a 'Listen' action in a-message. The receiving process runs the action to deliver its reply. The-'query' family of functions takes care of creating the reply variable and-waiting on it:--@-data Ping = Ping ('Listen' Pong)-data Pong = Pong--pongServer :: 'Inbox' Ping -> IO ()-pongServer inbox = forever $ do- Ping reply <- 'receive' inbox- atomically (reply Pong)+{-# LANGUAGE FlexibleContexts #-}+{-# LANGUAGE FlexibleInstances #-}+{-# LANGUAGE MultiParamTypeClasses #-}+{-# LANGUAGE RankNTypes #-} -main :: IO ()-main = 'withProcess' pongServer $ \\p -> do- Pong <- 'query' Ping p- return ()-@--}+-- |+-- Module : Control.Concurrent.NQE.Process+-- Copyright : Haskoin Developers+-- License : MIT+-- Maintainer : jprupp@protonmail.ch+-- Stability : experimental+-- Portability : POSIX+--+-- This is the core of the NQE library. It is composed of code to deal with+-- processes and mailboxes. Processes represent concurrent threads that receive+-- messages via a mailbox, also referred to as a channel. NQE is inspired by+-- Erlang/OTP and it stands for “Not Quite Erlang”. A process is analogous to an+-- actor in Scala, or an object in the original (Alan Kay) sense of the word. To+-- implement synchronous communication NQE makes use of 'STM' actions embedded in+-- asynchronous messages.+--+-- = Why processes and mailboxes+--+-- Shared mutable state is the usual source of trouble in concurrent programs:+-- two threads change the same thing, and the result depends on timing. The+-- Erlang answer, which NQE borrows, is to give each piece of state an owner. A+-- process owns its state outright, and other threads can only ask it to do+-- things by sending messages. The process handles one message at a time, so its+-- state is never seen half-changed and needs no locks.+--+-- Haskell already has excellent building blocks for this: lightweight threads,+-- 'STM' and the @async@ package. NQE does not replace them. It is a thin layer+-- that names the patterns people end up writing by hand on top of them, so that+-- programs built from many cooperating threads read the same way everywhere.+--+-- = Design choices+--+-- * __Everything is STM.__ Channels are 'TQueue' or 'TBQueue', and replies are+-- 'STM' actions. This means a send, a receive and a reply can be combined with+-- any other transaction, and selective receive ('receiveMatch') can be done+-- atomically.+--+-- * __Replies are callbacks, not return channels.__ A request carries a 'Listen'+-- action that the receiver runs. The sender decides where the reply goes: a+-- 'TMVar' for 'query', a queue for a stream of replies, or nowhere at all.+-- The receiver does not need to know.+--+-- * __Sending and receiving are separate capabilities.__ An 'Inbox' can receive;+-- a 'Mailbox' can only send. Handing out a 'Mailbox' lets other threads talk to+-- a process without being able to steal its messages.+--+-- * __Bounded channels give back-pressure.__ A fast producer writing to a+-- bounded inbox blocks until the consumer catches up, instead of filling+-- memory.+--+-- * __Failures are loud.__ 'withProcess' and 'process' link the new thread to its+-- parent, so an exception in a process is re-thrown in the thread that started+-- it rather than disappearing.+--+-- * __Plain 'IO'.__ Every action runs in 'IO' or 'STM', on top of the ordinary+-- @stm@, @async@ and @base@ libraries. Versions before 0.7.0 were polymorphic+-- in the monad, so that processes could be written directly in a @ReaderT@+-- or @LoggingT@ stack. That cost a dependency, constraints on every+-- signature and exception rules that differ from those of @base@. A+-- concrete monad is easier to read and to reason about, and a program that+-- keeps a transformer stack can still run it inside the 'IO' action that it+-- hands to 'withProcess'.+--+-- * __Not quite Erlang.__ There is no distribution, no process registry, no+-- hot code loading and no automatic restarts. Those features cost a lot of+-- complexity and most Haskell programs that want actors do not need them.+--+-- = Overview+--+-- * An 'Inbox' is the receiving end of a channel. Only the process that owns it+-- should read from it.+-- * A 'Mailbox' is the sending end of the same channel. It can be shared freely+-- with any thread that needs to talk to the process.+-- * A 'Process' bundles the 'Async' handle of a running thread together with its+-- 'Mailbox'.+--+-- Channels can be unbounded ('newInbox') or bounded ('newBoundedInbox'). Sending+-- to a full bounded channel blocks until there is space.+--+-- = Synchronous requests+--+-- Request/response communication is done by embedding a 'Listen' action in a+-- message. The receiving process runs the action to deliver its reply. The+-- 'query' family of functions takes care of creating the reply variable and+-- waiting on it:+--+-- @+-- data Ping = Ping ('Listen' Pong)+-- data Pong = Pong+--+-- pongServer :: 'Inbox' Ping -> IO ()+-- pongServer inbox = forever $ do+-- Ping reply <- 'receive' inbox+-- atomically (reply Pong)+--+-- main :: IO ()+-- main = 'withProcess' pongServer $ \\p -> do+-- Pong <- 'query' Ping p+-- return ()+-- @ module Control.Concurrent.NQE.Process where -import Control.Concurrent.Unique-import Data.Function-import Data.Hashable-import Numeric.Natural-import UnliftIO+import Control.Concurrent.Async+import Control.Concurrent.STM+import Control.Concurrent.Unique+import Data.Function+import Data.Hashable+import Numeric.Natural+import System.Timeout (timeout) -- | 'STM' function that receives an event and does something with it. --@@ -129,10 +140,12 @@ -- code that only needs to talk to a process should not be able to read its -- messages. The existential type also hides which kind of channel is behind it, -- so a bounded and an unbounded process look the same to their clients.-data Mailbox msg =- forall mbox. (OutChan mbox) =>- Mailbox !(mbox msg)- !Unique+data Mailbox msg+ = forall mbox.+ (OutChan mbox) =>+ Mailbox+ !(mbox msg)+ !Unique -- | Channel that allows to send or receive messages. --@@ -142,20 +155,22 @@ -- -- An inbox is the private end of a process. Keep it inside the process and -- share the 'Mailbox' made from it with 'inboxToMailbox'.-data Inbox msg =- forall mbox. (OutChan mbox, InChan mbox) =>- Inbox !(mbox msg)- !Unique+data Inbox msg+ = forall mbox.+ (OutChan mbox, InChan mbox) =>+ Inbox+ !(mbox msg)+ !Unique instance Eq (Mailbox msg) where- (==) = (==) `on` f- where- f (Mailbox _ u) = u+ (==) = (==) `on` f+ where+ f (Mailbox _ u) = u instance Eq (Inbox msg) where- (==) = (==) `on` f- where- f (Inbox _ u) = u+ (==) = (==) `on` f+ where+ f (Inbox _ u) = u -- | 'Async' handle and 'Mailbox' for a process. --@@ -163,11 +178,12 @@ -- directly using 'send' or 'query'. Use 'getProcessAsync' to wait for the -- process or cancel it. data Process msg = Process- { getProcessAsync :: Async ()- -- ^ handle of the thread running the process- , getProcessMailbox :: Mailbox msg- -- ^ mailbox used to send messages to the process- } deriving Eq+ { -- | handle of the thread running the process+ getProcessAsync :: Async (),+ -- | mailbox used to send messages to the process+ getProcessMailbox :: Mailbox msg+ }+ deriving (Eq) -- | Class for implementation of an 'Inbox'. --@@ -177,66 +193,69 @@ -- 'Inbox' and 'Mailbox', and on 'Process' handles. They are the extension point -- for other channel types. class InChan mbox where- -- | Are there messages queued?- mailboxEmptySTM :: mbox msg -> STM Bool- -- | Receive a message.- receiveSTM :: mbox msg -> STM msg- -- | Put a message in the mailbox such that it is received next.- requeueSTM :: msg -> mbox msg -> STM ()+ -- | Are there messages queued?+ mailboxEmptySTM :: mbox msg -> STM Bool + -- | Receive a message.+ receiveSTM :: mbox msg -> STM msg++ -- | Put a message in the mailbox such that it is received next.+ requeueSTM :: msg -> mbox msg -> STM ()+ -- | Class for implementation of a 'Mailbox'. -- -- Instances are provided for 'TQueue', 'TBQueue', 'Mailbox', 'Inbox' and -- 'Process'. class OutChan mbox where- -- | Is this bounded channel full? Always 'False' for unbounded channels.- mailboxFullSTM :: mbox msg -> STM Bool- -- | Send a message to this channel. Retries (blocks) if a bounded channel- -- is full.- sendSTM :: msg -> mbox msg -> STM ()+ -- | Is this bounded channel full? Always 'False' for unbounded channels.+ mailboxFullSTM :: mbox msg -> STM Bool + -- | Send a message to this channel. Retries (blocks) if a bounded channel+ -- is full.+ sendSTM :: msg -> mbox msg -> STM ()+ instance InChan TQueue where- mailboxEmptySTM = isEmptyTQueue- receiveSTM = readTQueue- requeueSTM msg = (`unGetTQueue` msg)+ mailboxEmptySTM = isEmptyTQueue+ receiveSTM = readTQueue+ requeueSTM msg = (`unGetTQueue` msg) instance OutChan TQueue where- mailboxFullSTM _ = return False- sendSTM msg = (`writeTQueue` msg)+ mailboxFullSTM _ = return False+ sendSTM msg = (`writeTQueue` msg) instance InChan TBQueue where- mailboxEmptySTM = isEmptyTBQueue- receiveSTM = readTBQueue- requeueSTM msg = (`unGetTBQueue` msg)+ mailboxEmptySTM = isEmptyTBQueue+ receiveSTM = readTBQueue+ requeueSTM msg = (`unGetTBQueue` msg) instance OutChan TBQueue where- mailboxFullSTM = isFullTBQueue- sendSTM msg = (`writeTBQueue` msg)+ mailboxFullSTM = isFullTBQueue+ sendSTM msg = (`writeTBQueue` msg) instance OutChan Mailbox where- mailboxFullSTM (Mailbox mbox _) = mailboxFullSTM mbox- sendSTM msg (Mailbox mbox _) = msg `sendSTM` mbox+ mailboxFullSTM (Mailbox mbox _) = mailboxFullSTM mbox+ sendSTM msg (Mailbox mbox _) = msg `sendSTM` mbox instance InChan Inbox where- mailboxEmptySTM (Inbox mbox _) = mailboxEmptySTM mbox- receiveSTM (Inbox mbox _) = receiveSTM mbox- requeueSTM msg (Inbox mbox _) = msg `requeueSTM` mbox+ mailboxEmptySTM (Inbox mbox _) = mailboxEmptySTM mbox+ receiveSTM (Inbox mbox _) = receiveSTM mbox+ requeueSTM msg (Inbox mbox _) = msg `requeueSTM` mbox instance OutChan Inbox where- mailboxFullSTM (Inbox mbox _) = mailboxFullSTM mbox- sendSTM msg (Inbox mbox _) = msg `sendSTM` mbox+ mailboxFullSTM (Inbox mbox _) = mailboxFullSTM mbox+ sendSTM msg (Inbox mbox _) = msg `sendSTM` mbox instance OutChan Process where- mailboxFullSTM (Process _ mbox) = mailboxFullSTM mbox- sendSTM msg (Process _ mbox) = msg `sendSTM` mbox+ mailboxFullSTM (Process _ mbox) = mailboxFullSTM mbox+ sendSTM msg (Process _ mbox) = msg `sendSTM` mbox instance Hashable (Process msg) where- hashWithSalt i (Process _ m) = hashWithSalt i m- hash (Process _ m) = hash m+ hashWithSalt i (Process _ m) = hashWithSalt i m+ hash (Process _ m) = hash m instance Hashable (Mailbox msg) where- hashWithSalt i (Mailbox _ u) = hashWithSalt i u- hash (Mailbox _ u) = hash u+ hashWithSalt i (Mailbox _ u) = hashWithSalt i u+ hash (Mailbox _ u) = hash u -- | Get a send-only 'Mailbox' for an 'Inbox'. inboxToMailbox :: Inbox msg -> Mailbox msg@@ -244,12 +263,11 @@ -- | Wrap a channel in an 'Inbox'. A fresh 'Unique' identifier is generated, so -- wrapping the same channel twice yields two 'Inbox' values that are not equal.-wrapChannel ::- (MonadIO m, InChan mbox, OutChan mbox) => mbox msg -> m (Inbox msg)-wrapChannel mbox = Inbox mbox <$> liftIO newUnique+wrapChannel :: (InChan mbox, OutChan mbox) => mbox msg -> IO (Inbox msg)+wrapChannel mbox = Inbox mbox <$> newUnique -- | Create an unbounded 'Inbox' backed by a 'TQueue'.-newInbox :: MonadIO m => m (Inbox msg)+newInbox :: IO (Inbox msg) newInbox = newTQueueIO >>= \c -> wrapChannel c -- | Create an 'Inbox' backed by a 'TBQueue' with an upper bound on the number@@ -258,16 +276,16 @@ -- Prefer a bounded inbox whenever the producer can outpace the consumer, such -- as a process fed by the network. Blocking the producer is almost always better -- than letting the queue, and the program's memory, grow without limit.-newBoundedInbox :: MonadIO m => Natural -> m (Inbox msg)+newBoundedInbox :: Natural -> IO (Inbox msg) newBoundedInbox i = newTBQueueIO (fromIntegral i) >>= \c -> wrapChannel c -- | Send a message to a channel. Blocks if the channel is bounded and full.-send :: (MonadIO m, OutChan mbox) => msg -> mbox msg -> m ()+send :: (OutChan mbox) => msg -> mbox msg -> IO () send msg = atomically . sendSTM msg -- | Receive the next message from a channel. Blocks until a message is -- available.-receive :: (InChan mbox, MonadIO m) => mbox msg -> m msg+receive :: (InChan mbox) => mbox msg -> IO msg receive mbox = receiveMatch mbox Just -- | Send request to channel and wait for a response. The @request@ 'STM' action@@ -286,33 +304,33 @@ -- that is, directly or indirectly, querying it back will wait forever. Keep -- requests flowing in one direction, or use 'queryS' with a timeout. query ::- (MonadIO m, OutChan mbox)- => (Listen response -> request)- -> mbox request- -> m response+ (OutChan mbox) =>+ (Listen response -> request) ->+ mbox request ->+ IO response query f m = do- r <- newEmptyTMVarIO- f (putTMVar r) `send` m- atomically $ takeTMVar r+ r <- newEmptyTMVarIO+ f (putTMVar r) `send` m+ atomically $ takeTMVar r -- | Do a 'query' but timeout after @u@ microseconds. Return 'Nothing' if -- timeout reached. queryU ::- (MonadUnliftIO m, OutChan mbox)- => Int- -> (Listen response -> request)- -> mbox request- -> m (Maybe response)+ (OutChan mbox) =>+ Int ->+ (Listen response -> request) ->+ mbox request ->+ IO (Maybe response) queryU u f m = timeout u (query f m) -- | Do a 'query' but timeout after @s@ seconds. Return 'Nothing' if -- timeout reached. queryS ::- (MonadUnliftIO m, OutChan mbox)- => Int- -> (Listen response -> request)- -> mbox request- -> m (Maybe response)+ (OutChan mbox) =>+ Int ->+ (Listen response -> request) ->+ mbox request ->+ IO (Maybe response) queryS s f m = timeout (s * 1000 * 1000) (query f m) -- | Test all messages in a channel against the supplied function and return the@@ -323,51 +341,51 @@ -- other messages for later, as Erlang's @receive@ does. Use it sparingly: every -- message that does not match is examined on each call, so a long queue of -- unmatched messages makes it slow.-receiveMatch :: (MonadIO m, InChan mbox) => mbox msg -> (msg -> Maybe a) -> m a+receiveMatch :: (InChan mbox) => mbox msg -> (msg -> Maybe a) -> IO a receiveMatch mbox = atomically . receiveMatchSTM mbox -- | Like 'receiveMatch' but with a timeout set at @u@ microseconds. Returns -- 'Nothing' if timeout is reached. receiveMatchU ::- (MonadUnliftIO m, InChan mbox)- => Int- -> mbox msg- -> (msg -> Maybe a)- -> m (Maybe a)+ (InChan mbox) =>+ Int ->+ mbox msg ->+ (msg -> Maybe a) ->+ IO (Maybe a) receiveMatchU u mbox f = timeout u $ receiveMatch mbox f -- | Like 'receiveMatch' but with a timeout set at @s@ seconds. Returns -- 'Nothing' if timeout is reached. receiveMatchS ::- (MonadUnliftIO m, InChan mbox)- => Int- -> mbox msg- -> (msg -> Maybe a)- -> m (Maybe a)+ (InChan mbox) =>+ Int ->+ mbox msg ->+ (msg -> Maybe a) ->+ IO (Maybe a) receiveMatchS s mbox f = timeout (s * 1000 * 1000) $ receiveMatch mbox f -- | Match a message in the channel as an atomic 'STM' action. Messages that do -- not match are put back in the channel in their original order. Retries if no -- message matches.-receiveMatchSTM :: InChan mbox => mbox msg -> (msg -> Maybe a) -> STM a+receiveMatchSTM :: (InChan mbox) => mbox msg -> (msg -> Maybe a) -> STM a receiveMatchSTM mbox f = go [] where go acc =- receiveSTM mbox >>= \msg ->- case f msg of- Just x -> do- requeueListSTM acc mbox- return x- Nothing -> go (msg : acc)+ receiveSTM mbox >>= \msg ->+ case f msg of+ Just x -> do+ requeueListSTM acc mbox+ return x+ Nothing -> go (msg : acc) -- | Check if the channel is empty. The result may be stale as soon as it is -- returned if other threads are writing to the channel.-mailboxEmpty :: (MonadIO m, InChan mbox) => mbox msg -> m Bool+mailboxEmpty :: (InChan mbox) => mbox msg -> IO Bool mailboxEmpty = atomically . mailboxEmptySTM -- | Put a list of messages at the start of a channel, so that the last element -- of the list is the next message to be received.-requeueListSTM :: InChan mbox => [msg] -> mbox msg -> STM ()+requeueListSTM :: (InChan mbox) => [msg] -> mbox msg -> STM () requeueListSTM xs mbox = mapM_ (`requeueSTM` mbox) xs -- | Run a process in the background and pass it to a function. Stop the@@ -377,16 +395,15 @@ -- The process receives the 'Inbox' of a newly-created unbounded channel. The -- function receives the corresponding 'Process' handle. The background thread is -- linked to the current one, so if it throws, the exception is re-thrown here--- wrapped in 'ExceptionInLinkedThread'.+-- wrapped in t'ExceptionInLinkedThread'. -- -- This is the function to reach for first. Tying the lifetime of the process to -- a scope means it cannot outlive the code that uses it, and linking means it -- cannot fail silently.-withProcess ::- MonadUnliftIO m => (Inbox msg -> m ()) -> (Process msg -> m a) -> m a+withProcess :: (Inbox msg -> IO ()) -> (Process msg -> IO a) -> IO a withProcess p f = do- (i, m) <- newMailbox- withAsync (p i) (\a -> link a >> f (Process a m))+ (i, m) <- newMailbox+ withAsync (p i) (\a -> link a >> f (Process a m)) -- | Run a process in the background and return the 'Process' handle. Background -- process exceptions are re-thrown in the current thread.@@ -394,16 +411,16 @@ -- Unlike 'withProcess', the process is not stopped automatically. Cancel it with -- 'cancel' on 'getProcessAsync' when it is no longer needed. Prefer -- 'withProcess' where possible, since it is exception-safe.-process :: MonadUnliftIO m => (Inbox msg -> m ()) -> m (Process msg)+process :: (Inbox msg -> IO ()) -> IO (Process msg) process p = do- (i, m) <- newMailbox- a <- async $ p i- link a- return (Process a m)+ (i, m) <- newMailbox+ a <- async $ p i+ link a+ return (Process a m) -- | Create an unbounded inbox and corresponding mailbox.-newMailbox :: MonadUnliftIO m => m (Inbox msg, Mailbox msg)+newMailbox :: IO (Inbox msg, Mailbox msg) newMailbox = do- i <- newInbox- let m = inboxToMailbox i- return (i, m)+ i <- newInbox+ let m = inboxToMailbox i+ return (i, m)
src/Control/Concurrent/NQE/Publisher.hs view
@@ -1,77 +1,82 @@-{-# LANGUAGE FlexibleContexts #-}-{-|-Module : Control.Concurrent.NQE.Publisher-Copyright : Haskoin Developers-License : MIT-Maintainer : jprupp@protonmail.ch-Stability : experimental-Portability : POSIX--A publisher is a process that forwards messages to subscribers. NQE publishers-are simple, and do not implement filtering directly, although that can be done-on the 'STM' 'Listen' actions that forward messages to subscribers.--If a subscriber has been added to a publisher using the 'subscribe' function, it-needs to be removed later using 'unsubscribe' when it is no longer needed, or-the publisher will continue calling its 'Listen' action in the future, likely-causing memory leaks. Prefer 'withSubscription', which unsubscribes-automatically.--= Why a publisher process--Broadcasting is common: many parts of a program want to hear about the same-events, such as new blocks or connected peers, and the code producing them-should not need to know who is listening. A publisher decouples the two. The-producer sends each event once; subscribers come and go without the producer-noticing.--= Design choices--* __Subscribers are 'Listen' actions, not inboxes.__ That leaves every policy- decision to the subscriber: it can filter events, transform them, drop them- when its queue is full, or write them anywhere an 'STM' action can.--* __Delivery is a single transaction.__ Each event is handed to all current- subscribers in one 'STM' transaction, so they all see the same events in the- same order. The cost is that one slow 'Listen' action slows the whole- publisher, which is why those actions must be quick and must not block.--* __The loop is flat.__ The publisher loop sequences with @>>=@ rather than- 'Control.Monad.forever', so that it runs in constant memory even in monads- like @LoggingT@, where @forever@ leaks.--= Example+{-# LANGUAGE FlexibleContexts #-} -@-'withPublisher' $ \\pub ->- 'withSubscription' pub $ \\inbox -> do- 'publish' "hello" pub- msg <- 'receive' inbox- print msg-@--}+-- |+-- Module : Control.Concurrent.NQE.Publisher+-- Copyright : Haskoin Developers+-- License : MIT+-- Maintainer : jprupp@protonmail.ch+-- Stability : experimental+-- Portability : POSIX+--+-- A publisher is a process that forwards messages to subscribers. NQE publishers+-- are simple, and do not implement filtering directly, although that can be done+-- on the 'STM' 'Listen' actions that forward messages to subscribers.+--+-- If a subscriber has been added to a publisher using the 'subscribe' function, it+-- needs to be removed later using 'unsubscribe' when it is no longer needed, or+-- the publisher will continue calling its 'Listen' action in the future, likely+-- causing memory leaks. Prefer 'withSubscription', which unsubscribes+-- automatically.+--+-- = Why a publisher process+--+-- Broadcasting is common: many parts of a program want to hear about the same+-- events, such as new blocks or connected peers, and the code producing them+-- should not need to know who is listening. A publisher decouples the two. The+-- producer sends each event once; subscribers come and go without the producer+-- noticing.+--+-- = Design choices+--+-- * __Subscribers are 'Listen' actions, not inboxes.__ That leaves every policy+-- decision to the subscriber: it can filter events, transform them, drop them+-- when its queue is full, or write them anywhere an 'STM' action can.+--+-- * __Delivery is a single transaction.__ Each event is handed to all current+-- subscribers in one 'STM' transaction, so they all see the same events in the+-- same order. The cost is that one slow 'Listen' action slows the whole+-- publisher, which is why those actions must be quick and must not block.+--+-- * __Unsubscribing cannot be interrupted.__ 'withSubscription' removes its+-- subscriber with asynchronous exceptions blocked, even at the points where+-- 'Control.Exception.bracket' alone would let one in. A thread that is being+-- cancelled therefore always unsubscribes, and never leaves behind a+-- subscriber that nobody reads from. The price is that the thread cannot be+-- stopped while it waits to hand over that message, which only happens if+-- the publisher was given a bounded inbox that is full.+--+-- = Example+--+-- @+-- 'withPublisher' $ \\pub ->+-- 'withSubscription' pub $ \\inbox -> do+-- 'publish' "hello" pub+-- msg <- 'receive' inbox+-- print msg+-- @ module Control.Concurrent.NQE.Publisher- ( Subscriber- , PublisherMessage(..)- , Publisher- , withSubscription- , subscribe- , unsubscribe- , withPublisher- , publisher- , publisherProcess- , publish- , publishSTM- ) where+ ( Subscriber,+ PublisherMessage (..),+ Publisher,+ withSubscription,+ subscribe,+ unsubscribe,+ withPublisher,+ publisher,+ publisherProcess,+ publish,+ publishSTM,+ )+where -import Control.Concurrent.NQE.Process-import Control.Concurrent.Unique-import Control.Monad-import Control.Monad.Reader-import Data.Function-import Data.Hashable-import Data.List-import UnliftIO+import Control.Concurrent.NQE.Process+import Control.Concurrent.STM+import Control.Concurrent.Unique+import Control.Exception (bracket, uninterruptibleMask_)+import Control.Monad+import Data.Function+import Data.Hashable+import Data.List -- | Handle of a subscriber to a process. Should be kept in order to -- unsubscribe. Subscribers are compared by a 'Unique' identifier assigned by the@@ -79,23 +84,23 @@ data Subscriber msg = Subscriber (Listen msg) Unique instance Eq (Subscriber msg) where- (==) = (==) `on` f- where- f (Subscriber _ u) = u+ (==) = (==) `on` f+ where+ f (Subscriber _ u) = u instance Hashable (Subscriber msg) where- hashWithSalt i (Subscriber _ u) = hashWithSalt i u+ hashWithSalt i (Subscriber _ u) = hashWithSalt i u -- | Messages that a publisher will take. Normally these are not built -- directly; use 'subscribe', 'unsubscribe' and 'publish' instead. data PublisherMessage msg- = Subscribe !(Listen msg) !(Listen (Subscriber msg))- -- ^ add a 'Listen' action to the subscriber list, and reply with the- -- resulting 'Subscriber' handle- | Unsubscribe !(Subscriber msg)- -- ^ remove a subscriber from the list- | Event msg- -- ^ forward a message to every subscriber+ = -- | add a 'Listen' action to the subscriber list, and reply with the+ -- resulting 'Subscriber' handle+ Subscribe !(Listen msg) !(Listen (Subscriber msg))+ | -- | remove a subscriber from the list+ Unsubscribe !(Subscriber msg)+ | -- | forward a message to every subscriber+ Event msg -- | Alias for a publisher process. Since it is a 'Process', it can be stopped -- by cancelling its 'getProcessAsync' handle.@@ -103,7 +108,7 @@ -- | Send a message to all subscribers of a publisher. The message is queued in -- the publisher's mailbox and forwarded asynchronously.-publish :: MonadIO m => msg -> Publisher msg -> m ()+publish :: msg -> Publisher msg -> IO () publish = send . Event -- | 'STM' version of 'publish'. Useful to publish a message atomically together@@ -119,62 +124,59 @@ -- This is the safe way to subscribe, because the subscription cannot outlive -- the scope. For a bounded or filtered subscription, write your own bracket -- around 'subscribe' and 'unsubscribe' with your own 'Listen' action.-withSubscription ::- MonadUnliftIO m => Publisher msg -> (Inbox msg -> m a) -> m a+withSubscription :: Publisher msg -> (Inbox msg -> IO a) -> IO a withSubscription pub f = do- inbox <- newInbox- let sub = subscribe pub (`sendSTM` inbox)- unsub = unsubscribe pub- bracket sub unsub $ \_ -> f inbox+ inbox <- newInbox+ let sub = subscribe pub (`sendSTM` inbox)+ -- Not interruptible, so that a second asynchronous exception cannot+ -- cut the clean-up short and leak the subscriber. 'bracket' from+ -- base only masks its clean-up, which lets an exception in if the+ -- send has to wait. A publisher started by this module has an+ -- unbounded mailbox, so the send does not wait.+ unsub = uninterruptibleMask_ . unsubscribe pub+ bracket sub unsub $ \_ -> f inbox -- | 'Listen' to events from a publisher. Blocks until the publisher has -- registered the subscriber, and returns a handle that must later be passed to -- 'unsubscribe'. The 'Listen' action runs inside the publisher's 'STM' -- transaction for every event, so it should be fast and must not retry.-subscribe :: MonadIO m => Publisher msg -> Listen msg -> m (Subscriber msg)+subscribe :: Publisher msg -> Listen msg -> IO (Subscriber msg) subscribe pub sub = Subscribe sub `query` pub -- | Stop listening to events from a publisher. Must provide 'Subscriber' that -- was returned from corresponding 'subscribe' action.-unsubscribe :: MonadIO m => Publisher msg -> Subscriber msg -> m ()+unsubscribe :: Publisher msg -> Subscriber msg -> IO () unsubscribe pub sub = Unsubscribe sub `send` pub -- | Start a publisher in the background and pass it to a function. The -- publisher will be stopped when the function function returns.-withPublisher :: MonadUnliftIO m => (Publisher msg -> m a) -> m a+withPublisher :: (Publisher msg -> IO a) -> IO a withPublisher = withProcess publisherProcess -- | Start a publisher in the background. It must be stopped manually by -- cancelling 'getProcessAsync'. Prefer 'withPublisher' where possible.-publisher :: MonadUnliftIO m => m (Publisher msg)+publisher :: IO (Publisher msg) publisher = process publisherProcess -- | Start a publisher in the current thread. Runs forever, processing -- 'PublisherMessage' values from the inbox.-publisherProcess :: MonadUnliftIO m => Inbox (PublisherMessage msg) -> m ()-publisherProcess inbox = newTVarIO [] >>= runReaderT go- where- -- Sequenced with (>>=) only: 'forever' uses (*>), which for a monad- -- that is only known through its dictionary (LoggingT in particular)- -- leaves a continuation frame and two thunks per message, forever.- go = receive inbox >>= publisherMessage >>= \_ -> go+publisherProcess :: Inbox (PublisherMessage msg) -> IO ()+publisherProcess inbox = do+ box <- newTVarIO []+ forever $ receive inbox >>= publisherMessage box --- | Internal function to dispatch a publisher message.-publisherMessage ::- (MonadIO m, MonadReader (TVar [Subscriber msg]) m)- => PublisherMessage msg- -> m ()-publisherMessage (Subscribe sub r) =- ask >>= \box -> do- u <- liftIO newUnique- let s = Subscriber sub u- atomically $ do- modifyTVar box (`union` [s])- r s-publisherMessage (Unsubscribe sub) =- ask >>= \box -> atomically (modifyTVar box (delete sub))-publisherMessage (Event event) =- ask >>= \box ->- atomically $- readTVar box >>= \subs ->- forM_ subs $ \(Subscriber sub _) -> sub event+-- | Internal function to dispatch a publisher message. The first argument+-- holds the current subscribers; only the publisher's own thread writes to it.+publisherMessage :: TVar [Subscriber msg] -> PublisherMessage msg -> IO ()+publisherMessage box (Subscribe sub r) = do+ u <- newUnique+ let s = Subscriber sub u+ atomically $ do+ modifyTVar box (`union` [s])+ r s+publisherMessage box (Unsubscribe sub) =+ atomically (modifyTVar box (delete sub))+publisherMessage box (Event event) =+ atomically $+ readTVar box >>= \subs ->+ forM_ subs $ \(Subscriber sub _) -> sub event
src/Control/Concurrent/NQE/Supervisor.hs view
@@ -35,14 +35,35 @@ -- how often a restart is acceptable, so the decision is left to you. 'Notify' -- exists so that you can implement any restart policy you like. ----- * __Children run in 'IO'.__ A supervisor outlives any one of its children and--- may run them in contexts unrelated to where they were added, so it cannot--- share an arbitrary monadic context with them. Convert with--- 'UnliftIO.withRunInIO' when adding a child.+-- * __Children run in 'IO'.__ Like everything else in NQE, a child is a plain+-- 'IO' action. A supervisor outlives any one of its children and runs them+-- from its own thread, unrelated to where they were added, so there is no+-- other context that it could share with them. -- -- * __Stopping is total.__ When a supervisor stops, for whatever reason, all--- of its children are cancelled. Nothing it started can leak.+-- of its children are cancelled. Nothing it started can leak. It waits for+-- them with asynchronous exceptions blocked, so that cancelling the+-- supervisor a second time cannot make it walk away from children that are+-- still stopping. The price is that a child that refuses to die holds up+-- its supervisor. --+-- * __A child can always be stopped.__ A child starts with asynchronous+-- exceptions unmasked, whatever the state of the thread that added it and+-- of the supervisor that forks it. Before 0.7.0 a child inherited the+-- mask under which the supervisor registers it, and could be interrupted+-- only where it blocked: one that computed in a loop without blocking+-- could not be cancelled, nor leave its own 'System.Timeout.timeout', and+-- held up 'removeChild' and its supervisor for good. A child that needs to+-- be masked for a while says so itself, with 'Control.Exception.mask'.+--+-- * __A dead child is an error, however it died.__ 'KillAll' and+-- 'IgnoreGraceful' re-throw the exception that stopped a child. An+-- asynchronous one, such as the t'AsyncCancelled' of a child that somebody+-- cancelled directly instead of using 'removeChild', is wrapped in+-- t'AsyncChildException' first. Thrown as it is, it would look as if the+-- supervisor itself had been cancelled, and 'link' would not report it to+-- the thread that started the supervisor.+-- -- A child is any @IO ()@ action. It is started with 'addChild', which returns -- its 'Async' handle, and can be stopped with 'removeChild'. When the supervisor -- itself stops, all of its children are cancelled.@@ -59,6 +80,7 @@ SupervisorMessage, Supervisor, Strategy (..),+ AsyncChildException (..), withSupervisor, supervisor, supervisorProcess,@@ -68,15 +90,22 @@ where import Control.Applicative+import Control.Concurrent.Async import Control.Concurrent.NQE.Process-import Control.Concurrent.STM (retry)+import Control.Concurrent.STM+import Control.Exception+ ( Exception (..),+ SomeAsyncException (..),+ SomeException,+ finally,+ mask_,+ throwIO,+ uninterruptibleMask_,+ ) import Control.Monad import Data.List-import UnliftIO --- | Alias for child action to be executed asynchronously by supervisor. Use--- 'UnliftIO.toIO' or 'UnliftIO.withRunInIO' to turn an action in another monad--- into a 'ChildAction'.+-- | Alias for child action to be executed asynchronously by supervisor. type ChildAction = IO () -- | Thread handler for child. Returned by 'addChild' and used to remove the@@ -111,41 +140,63 @@ Notify (Listen (Child, Maybe SomeException)) | -- | if a child stops for any reason, kill all children and stop the -- supervisor; if the child threw an exception, re-throw it from the- -- supervisor+ -- supervisor (see t'AsyncChildException') KillAll | -- | ignore children that stop without raising an exception; if a child -- throws, kill all children and re-throw the exception from the supervisor+ -- (see t'AsyncChildException') IgnoreGraceful | -- | keep running if a child dies and ignore it, whatever the reason IgnoreAll +-- | An asynchronous exception that stopped a child, as a supervisor with the+-- 'KillAll' or 'IgnoreGraceful' strategy re-throws it.+--+-- A child can die of an asynchronous exception without the supervisor having+-- asked for it: somebody cancels its 'Async' handle directly, a thread linked+-- to it fails, or the runtime sends it a stack overflow. The supervisor+-- treats that as a failure of the child like any other. It cannot throw the+-- exception unchanged, because the exception would then be taken for one+-- aimed at the supervisor: 'link' ignores a linked thread that ends with+-- t'AsyncCancelled', so the supervisor would stop without anybody noticing,+-- and handlers that let asynchronous exceptions through would not see an+-- error either. Wrapped in this type it is an ordinary, synchronous exception+-- that reaches the thread that started the supervisor.+--+-- Exceptions that are not asynchronous are re-thrown unchanged, and 'Notify'+-- always receives the original exception. The 'Show' instance and+-- 'displayException' print the exception inside, so logs read as if it had+-- not been wrapped.+newtype AsyncChildException = AsyncChildException SomeException++instance Show AsyncChildException where+ showsPrec p (AsyncChildException e) = showsPrec p e++instance Exception AsyncChildException where+ displayException (AsyncChildException e) = displayException e+ -- | Run a supervisor asynchronously and pass its mailbox to a function. -- Supervisor will be stopped along with all its children when the function -- ends.-withSupervisor ::- (MonadUnliftIO m) =>- Strategy ->- (Supervisor -> m a) ->- m a+withSupervisor :: Strategy -> (Supervisor -> IO a) -> IO a withSupervisor = withProcess . supervisorProcess -- | Run a supervisor as an asynchronous process. The supervisor thread is -- linked to the current thread, so exceptions it throws are re-thrown here. It -- must be stopped manually; prefer 'withSupervisor' where possible.-supervisor :: (MonadUnliftIO m) => Strategy -> m Supervisor+supervisor :: Strategy -> IO Supervisor supervisor strat = process (supervisorProcess strat) -- | Run a supervisor in the current thread. Returns when the strategy dictates -- that the supervisor should stop. All children are cancelled when this -- function exits, whether normally or due to an exception.-supervisorProcess ::- (MonadUnliftIO m) =>- Strategy ->- Inbox SupervisorMessage ->- m ()+supervisorProcess :: Strategy -> Inbox SupervisorMessage -> IO () supervisorProcess strat i = do state <- newTVarIO []- finally (loop state) (stopAll state)+ -- 'finally' from base only masks its clean-up, which lets an asynchronous+ -- exception in while 'cancel' waits for a child to end. The children are+ -- stopped uninterruptibly instead, so that none of them is left running.+ loop state `finally` uninterruptibleMask_ (stopAll state) where loop state = do e <- atomically $ Right <$> receiveSTM i <|> Left <$> waitForChild state@@ -161,16 +212,16 @@ -- -- It does not block on the child, so it is safe to call from a child of the same -- supervisor, for example to spawn helpers.-addChild :: (MonadIO m) => Supervisor -> ChildAction -> m Child+addChild :: Supervisor -> ChildAction -> IO Child addChild sup action = AddChild action `query` sup -- | Stop a 'Child' controlled by this supervisor. Will block until the child -- dies.-removeChild :: (MonadIO m) => Supervisor -> Child -> m ()+removeChild :: Supervisor -> Child -> IO () removeChild sup c = RemoveChild c `query` sup -- | Internal function to stop all children.-stopAll :: (MonadUnliftIO m) => TVar [Child] -> m ()+stopAll :: TVar [Child] -> IO () stopAll state = mask_ $ do as <- readTVarIO state mapM_ cancel as@@ -183,8 +234,7 @@ waitAnyCatchSTM as -- | Internal function to process incoming supervisor message.-processMessage ::- (MonadUnliftIO m) => TVar [Child] -> SupervisorMessage -> m Bool+processMessage :: TVar [Child] -> SupervisorMessage -> IO Bool processMessage state (AddChild ch r) = do a <- startChild state ch atomically $ r a@@ -196,11 +246,10 @@ -- | Internal function to run when a child process dies. processDead ::- (MonadUnliftIO m) => TVar [Child] -> Strategy -> (Child, Either SomeException ()) ->- m Bool+ IO Bool processDead state IgnoreAll (a, _) = do atomically . modifyTVar' state $ filter (/= a) return True@@ -208,7 +257,7 @@ atomically $ modifyTVar' state . filter $ (/= a) stopAll state case e of- Left x -> throwIO x+ Left x -> throwChild x Right () -> return False processDead state IgnoreGraceful (a, Right ()) = do atomically (modifyTVar' state (filter (/= a)))@@ -216,7 +265,7 @@ processDead state IgnoreGraceful (a, Left e) = do atomically $ modifyTVar' state (filter (/= a)) stopAll state- throwIO e+ throwChild e processDead state (Notify notif) (a, ee) = do atomically $ do as <- readTVar state@@ -231,15 +280,31 @@ Left e -> Just e Right () -> Nothing +-- | Internal function to re-throw the exception that stopped a child from the+-- supervisor. An asynchronous exception is wrapped in t'AsyncChildException',+-- so that it is thrown as a failure of the child and not mistaken for an+-- exception sent to the supervisor itself.+throwChild :: SomeException -> IO a+throwChild e =+ case fromException e of+ Just (SomeAsyncException _) -> throwIO (AsyncChildException e)+ Nothing -> throwIO e+ -- | Internal function to start a child process.-startChild :: (MonadUnliftIO m) => TVar [Child] -> ChildAction -> m Child+--+-- The fork and the registration are masked together, so that no exception+-- can leave a child running that the supervisor does not know about. A+-- forked thread inherits the mask of the thread that forks it, so the child+-- is given back its exceptions explicitly: left masked, it could only be+-- cancelled, or timed out, at a point where it blocks.+startChild :: TVar [Child] -> ChildAction -> IO Child startChild state ch = mask_ $ do- a <- liftIO $ async ch+ a <- asyncWithUnmask $ \unmask -> unmask ch atomically $ modifyTVar' state (a :) return a -- | Internal fuction to stop a child process.-stopChild :: (MonadUnliftIO m) => TVar [Child] -> Child -> m ()+stopChild :: TVar [Child] -> Child -> IO () stopChild state a = mask_ $ do isChild <- atomically $ do
src/NQE.hs view
@@ -1,42 +1,45 @@-{-|-Module : NQE-Copyright : Haskoin Developers-License : MIT-Maintainer : jprupp@protonmail.ch-Stability : experimental-Portability : POSIX--Concurrency library inspired by Erlang/OTP.+-- |+-- Module : NQE+-- Copyright : Haskoin Developers+-- License : MIT+-- Maintainer : jprupp@protonmail.ch+-- Stability : experimental+-- Portability : POSIX+--+-- Concurrency library inspired by Erlang/OTP.+--+-- NQE helps you build programs out of many small threads that each own their+-- state and talk by passing messages, instead of threads that share mutable+-- state. It adds a few well-known patterns on top of 'STM' and @async@:+-- mailboxes, request and reply, supervision and publish/subscribe. Each module+-- explains why it works the way it does.+--+-- This module re-exports everything in the library:+--+-- * "Control.Concurrent.NQE.Process": processes, inboxes, mailboxes and+-- synchronous queries.+-- * "Control.Concurrent.NQE.Supervisor": supervisors that start, monitor and stop+-- child threads.+-- * "Control.Concurrent.NQE.Publisher": a process that broadcasts messages to any+-- number of subscribers.+-- * "Control.Concurrent.NQE.Conduit": glue to feed a 'Data.Conduit.ConduitT'+-- stream into a mailbox.+module NQE+ ( -- * Processes and Mailboxes+ module Process, -NQE helps you build programs out of many small threads that each own their-state and talk by passing messages, instead of threads that share mutable-state. It adds a few well-known patterns on top of 'STM' and @async@:-mailboxes, request and reply, supervision and publish/subscribe. Each module-explains why it works the way it does.+ -- * Process Supervisors+ module Supervisor, -This module re-exports everything in the library:+ -- * Publisher and Subscribers+ module Publisher, -* "Control.Concurrent.NQE.Process": processes, inboxes, mailboxes and- synchronous queries.-* "Control.Concurrent.NQE.Supervisor": supervisors that start, monitor and stop- child threads.-* "Control.Concurrent.NQE.Publisher": a process that broadcasts messages to any- number of subscribers.-* "Control.Concurrent.NQE.Conduit": glue to feed a 'Data.Conduit.ConduitT'- stream into a mailbox.--}-module NQE- ( -- * Processes and Mailboxes- module Process- -- * Process Supervisors- , module Supervisor- -- * Publisher and Subscribers- , module Publisher- -- * Conduit Integration- , module Conduit- ) where+ -- * Conduit Integration+ module Conduit,+ )+where -import Control.Concurrent.NQE.Conduit as Conduit-import Control.Concurrent.NQE.Process as Process-import Control.Concurrent.NQE.Publisher as Publisher-import Control.Concurrent.NQE.Supervisor as Supervisor+import Control.Concurrent.NQE.Conduit as Conduit+import Control.Concurrent.NQE.Process as Process+import Control.Concurrent.NQE.Publisher as Publisher+import Control.Concurrent.NQE.Supervisor as Supervisor
test/Spec.hs view
@@ -1,112 +1,179 @@-{-# LANGUAGE FlexibleContexts #-}-{-# LANGUAGE LambdaCase #-}-{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE FlexibleContexts #-}+{-# LANGUAGE LambdaCase #-}+{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ScopedTypeVariables #-}-import Conduit-import Control.Concurrent.Async (ExceptionInLinkedThread (..))-import Control.Concurrent.STM (check)-import Control.Monad-import NQE-import Test.Hspec-import UnliftIO-import UnliftIO.Concurrent hiding (yield) +import Conduit+import Control.Concurrent (threadDelay)+import Control.Concurrent.Async+ ( AsyncCancelled (..),+ ExceptionInLinkedThread (..),+ cancel,+ )+import Control.Concurrent.MVar (newEmptyMVar, putMVar, takeMVar)+import Control.Concurrent.STM (atomically, check)+import Control.Exception+import Control.Monad+import Data.IORef (IORef, atomicModifyIORef', newIORef, readIORef)+import NQE+import System.Timeout (timeout)+import Test.Hspec+ data Pong = Pong deriving (Eq, Show)+ newtype Ping = Ping (Listen Pong) data TestError- = TestError1- | TestError2- deriving (Show, Eq)+ = TestError1+ | TestError2+ deriving (Show, Eq)+ instance Exception TestError +-- | Work that never blocks: it can be interrupted only by a thread that has+-- asynchronous exceptions unmasked.+busy :: IORef Int -> IO ()+busy counter = forever $ atomicModifyIORef' counter (\n -> (n + 1, ()))+ testError :: Selector TestError testError = const True testError1 :: Selector TestError testError1 e = e == TestError1 -threadError :: Exception e => Selector e -> Selector ExceptionInLinkedThread+threadError :: (Exception e) => Selector e -> Selector ExceptionInLinkedThread threadError e (ExceptionInLinkedThread _ s) = maybe False e (fromException s) -notifError :: Exception e => Selector e -> Selector (Maybe SomeException)+notifError :: (Exception e) => Selector e -> Selector (Maybe SomeException) notifError e s = maybe False e (s >>= fromException) -pongServer :: MonadIO m => Inbox Ping -> m ()+-- A child that died of an asynchronous exception, as its supervisor reports it.+asyncChildError :: (Exception e) => Selector e -> Selector AsyncChildException+asyncChildError e (AsyncChildException s) = maybe False e (fromException s)++pongServer :: Inbox Ping -> IO () pongServer mbox =- forever $ do- Ping r <- receive mbox- atomically (r Pong)+ forever $ do+ Ping r <- receive mbox+ atomically (r Pong) main :: IO () main =- hspec $ do- describe "two communicating processes" $- it "exchange ping/pong messages" $ do- g <- withProcess pongServer (query Ping)- g `shouldBe` Pong- describe "supervisor" $ do- let dummy = threadDelay $ 1000 * 1000- it "all processes end without failure" $ do- let action =- withSupervisor KillAll $ \sup -> do- addChild sup dummy- addChild sup dummy- threadDelay $ 100 * 1000- action `shouldReturn` ()- it "one process crashes" $ do- let action =- withSupervisor IgnoreGraceful $ \sup -> do- addChild sup dummy- addChild sup (throwIO TestError1)- threadDelay $ 500 * 1000- action `shouldThrow` threadError testError1- it "both processes crash" $ do- let action =- withSupervisor IgnoreGraceful $ \sup -> do- addChild sup (throwIO TestError1)- addChild sup (throwIO TestError2)- threadDelay $ 500 * 1000- action `shouldThrow` threadError testError- it "monitors processes" $ do- let rcv i = receive i :: IO (Maybe SomeException)- (inbox, mailbox) <- newMailbox- (t1, t2) <-- withSupervisor (Notify ((`sendSTM` mailbox) . snd)) $ \sup -> do- addChild sup (throwIO TestError1)- addChild sup (throwIO TestError2)- (,) <$> rcv inbox <*> rcv inbox- t1 `shouldSatisfy` notifError testError- t2 `shouldSatisfy` notifError testError- describe "pubsub" $ do- it "sends messages to all subscribers" $ do- let msgs = words "hello world"- (inbox1, mbox1) <- newMailbox- (inbox2, mbox2) <- newMailbox- (msgs1, msgs2) <-- withPublisher $ \pub -> do- subscribe pub (`sendSTM` mbox1)- subscribe pub (`sendSTM` mbox2)- mapM_ ((`send` pub) . Event) msgs- msgs1 <- replicateM 2 (receive inbox1)- msgs2 <- replicateM 2 (receive inbox2)- return (msgs1, msgs2)- msgs1 `shouldBe` msgs- msgs2 `shouldBe` msgs- it "drops messages when bounded queue full" $ do- let msgs = words "hello world drop"- let f mbox msg = mailboxFullSTM mbox >>= \case- True -> return ()- False -> msg `sendSTM` mbox- msgs' <-- withPublisher $ \pub -> do- inbox <- newBoundedInbox 2- subscribe pub (f (inboxToMailbox inbox))- mapM_ ((`send` pub) . Event) msgs- atomically $ check =<< mailboxFullSTM inbox- threadDelay $ 250 * 1000- msgs' <- replicateM 2 (receive inbox)- Event "meh" `send` pub- msg <- receive inbox- return $ msgs' <> [msg]- msgs' `shouldBe` words "hello world meh"+ hspec $ do+ describe "two communicating processes" $+ it "exchange ping/pong messages" $ do+ g <- withProcess pongServer (query Ping)+ g `shouldBe` Pong+ describe "timeouts" $ do+ it "give up on a query that is never answered" $ do+ inbox <- newInbox :: IO (Inbox Ping)+ queryU (10 * 1000) Ping inbox `shouldReturn` Nothing+ it "give up on a message that never comes" $ do+ inbox <- newInbox :: IO (Inbox Pong)+ receiveMatchU (10 * 1000) inbox Just `shouldReturn` Nothing+ it "do not get in the way of an answer" $ do+ g <- withProcess pongServer (queryS 5 Ping)+ g `shouldBe` Just Pong+ describe "supervisor" $ do+ let dummy = threadDelay $ 1000 * 1000+ it "all processes end without failure" $ do+ let action =+ withSupervisor KillAll $ \sup -> do+ addChild sup dummy+ addChild sup dummy+ threadDelay $ 100 * 1000+ action `shouldReturn` ()+ it "one process crashes" $ do+ let action =+ withSupervisor IgnoreGraceful $ \sup -> do+ addChild sup dummy+ addChild sup (throwIO TestError1)+ threadDelay $ 500 * 1000+ action `shouldThrow` threadError testError1+ it "both processes crash" $ do+ let action =+ withSupervisor IgnoreGraceful $ \sup -> do+ addChild sup (throwIO TestError1)+ addChild sup (throwIO TestError2)+ threadDelay $ 500 * 1000+ action `shouldThrow` threadError testError+ it "reports a child that was cancelled behind its back" $ do+ let cancelled AsyncCancelled = True+ action =+ withSupervisor KillAll $ \sup -> do+ child <- addChild sup dummy+ cancel child+ threadDelay $ 500 * 1000+ action `shouldThrow` threadError (asyncChildError cancelled)+ it "stops a child that never blocks" $ do+ counter <- newIORef (0 :: Int)+ done <- timeout (5 * 1000 * 1000) . withSupervisor IgnoreAll $ \sup -> do+ child <- addChild sup (busy counter)+ threadDelay $ 100 * 1000+ removeChild sup child+ done `shouldBe` Just ()+ readIORef counter >>= (`shouldSatisfy` (> 0))+ it "lets a child time out of work that never blocks" $ do+ counter <- newIORef (0 :: Int)+ result <- newEmptyMVar+ got <- withSupervisor IgnoreAll $ \sup -> do+ _ <- addChild sup (timeout (100 * 1000) (busy counter) >>= putMVar result)+ timeout (5 * 1000 * 1000) (takeMVar result)+ got `shouldBe` Just Nothing+ it "monitors processes" $ do+ let rcv i = receive i :: IO (Maybe SomeException)+ (inbox, mailbox) <- newMailbox+ (t1, t2) <-+ withSupervisor (Notify ((`sendSTM` mailbox) . snd)) $ \sup -> do+ addChild sup (throwIO TestError1)+ addChild sup (throwIO TestError2)+ (,) <$> rcv inbox <*> rcv inbox+ t1 `shouldSatisfy` notifError testError+ t2 `shouldSatisfy` notifError testError+ describe "pubsub" $ do+ it "sends messages to all subscribers" $ do+ let msgs = words "hello world"+ (inbox1, mbox1) <- newMailbox+ (inbox2, mbox2) <- newMailbox+ (msgs1, msgs2) <-+ withPublisher $ \pub -> do+ subscribe pub (`sendSTM` mbox1)+ subscribe pub (`sendSTM` mbox2)+ mapM_ ((`send` pub) . Event) msgs+ msgs1 <- replicateM 2 (receive inbox1)+ msgs2 <- replicateM 2 (receive inbox2)+ return (msgs1, msgs2)+ msgs1 `shouldBe` msgs+ msgs2 `shouldBe` msgs+ it "subscribes for the length of a scope" $ do+ (msg, after) <-+ withPublisher $ \pub -> do+ (inbox, msg) <-+ withSubscription pub $ \inbox -> do+ publish "hello" pub+ (,) inbox <$> receive inbox+ publish "world" pub+ -- The publisher handles messages in order, so by the+ -- time it answers this it has dealt with "world".+ _ <- subscribe pub (const (return ()))+ (,) msg <$> mailboxEmpty inbox+ msg `shouldBe` "hello"+ after `shouldBe` True+ it "drops messages when bounded queue full" $ do+ let msgs = words "hello world drop"+ let f mbox msg =+ mailboxFullSTM mbox >>= \case+ True -> return ()+ False -> msg `sendSTM` mbox+ msgs' <-+ withPublisher $ \pub -> do+ inbox <- newBoundedInbox 2+ subscribe pub (f (inboxToMailbox inbox))+ mapM_ ((`send` pub) . Event) msgs+ atomically $ check =<< mailboxFullSTM inbox+ threadDelay $ 250 * 1000+ msgs' <- replicateM 2 (receive inbox)+ Event "meh" `send` pub+ msg <- receive inbox+ return $ msgs' <> [msg]+ msgs' `shouldBe` words "hello world meh"