Control.Concurrent.NQE.Process

Documentation

class Eq (mbox msg) => Mailbox mbox msg where

Mailboxes are used to communicate with processes (actors). A process will usually listen in a loop for events entering its mailbox. A process is its mailbox, so it may be named as the process that it communicates with.

>>> :m + Control.Monad NQE UnliftIO
>>> registry <- newTQueueIO :: IO (TQueue String)
>>> let run = receive registry >>= putStrLn . ("Registered: " ++)
>>> withAsync run $ \a -> "Bruce Wayne" `send` registry >> wait a
Registered: Bruce Wayne

Minimal complete definition

mailboxEmptySTM, mailboxFullSTM, sendSTM, receiveSTM, requeueSTM

Methods

mailboxEmptySTM :: mbox msg -> STM Bool

STM action that responds true if the mailbox is empty. Useful to avoid blocking on an empty mailbox.

mailboxFullSTM :: mbox msg -> STM Bool

STM action that responds true if the mailbox is full and would block if a new message is received.

sendSTM :: msg -> mbox msg -> STM ()

STM action to send a message to a mailbox. This is usually called from a process that wishes to communicate with actor that owns the mailbox.

receiveSTM :: mbox msg -> STM msg

STM action to receive a message from a mailbox. This should be called from the process that owns the mailbox.

requeueSTM :: msg -> mbox msg -> STM ()

Put a message back in the mailbox so that it is the next one to be received. Used for pattern matching.

Instances

Mailbox TQueue msg

Defined in Control.Concurrent.NQE.Process

Methods

mailboxEmptySTM :: TQueue msg -> STM Bool

mailboxFullSTM :: TQueue msg -> STM Bool

sendSTM :: msg -> TQueue msg -> STM ()

receiveSTM :: TQueue msg -> STM msg

requeueSTM :: msg -> TQueue msg -> STM ()

Mailbox TBQueue msg

Defined in Control.Concurrent.NQE.Process

Methods

mailboxEmptySTM :: TBQueue msg -> STM Bool

mailboxFullSTM :: TBQueue msg -> STM Bool

sendSTM :: msg -> TBQueue msg -> STM ()

receiveSTM :: TBQueue msg -> STM msg

requeueSTM :: msg -> TBQueue msg -> STM ()

Mailbox Inbox msg

Defined in Control.Concurrent.NQE.Process

Methods

mailboxEmptySTM :: Inbox msg -> STM Bool

mailboxFullSTM :: Inbox msg -> STM Bool

sendSTM :: msg -> Inbox msg -> STM ()

receiveSTM :: Inbox msg -> STM msg

requeueSTM :: msg -> Inbox msg -> STM ()

data Inbox msg

Wrapped Mailbox hiding its implementation.

Instances

Mailbox Inbox msg

Defined in Control.Concurrent.NQE.Process

Methods

mailboxEmptySTM :: Inbox msg -> STM Bool

mailboxFullSTM :: Inbox msg -> STM Bool

sendSTM :: msg -> Inbox msg -> STM ()

receiveSTM :: Inbox msg -> STM msg

requeueSTM :: msg -> Inbox msg -> STM ()

Eq (Inbox msg)

Defined in Control.Concurrent.NQE.Process

Methods

(==) :: Inbox msg -> Inbox msg -> Bool

(/=) :: Inbox msg -> Inbox msg -> Bool

Hashable (Inbox msg)

Defined in Control.Concurrent.NQE.Process

Methods

hashWithSalt :: Int -> Inbox msg -> Int

hash :: Inbox msg -> Int

type Reply a = a -> STM ()

STM action to reply to a synchronous request.

type Listen a = a -> STM ()

STM action for an event listener.

newInbox :: (MonadIO m, Mailbox mbox msg) => mbox msg -> m (Inbox msg)

Create a new Inbox with a Unique identifier inside. If you run this function more than once with the same Mailbox, its results will be different from the Eq or Hashable point of view.

send :: (MonadIO m, Mailbox mbox msg) => msg -> mbox msg -> m ()

Send a message to a mailbox.

receive :: (MonadIO m, Mailbox mbox msg) => mbox msg -> m msg

Receive a message from the mailbox. This function should be called only by the process that owns the malibox.

query :: (MonadIO m, Mailbox mbox msg) => (Reply a -> msg) -> mbox msg -> m a

Use a partially-applied message type that takes a `Reply a` as its last argument. This function will create the STM action for the response, send the message to a process and await for the STM action to be fulfilled before responding response. It implements synchronous communication with a process.

Example:

>>> :m + NQE UnliftIO
>>> data Message = Square Integer (Reply Integer)
>>> doubler <- newTQueueIO :: IO (TQueue Message)
>>> let proc = receive doubler >>= \(Square i r) -> atomically $ r (i * i)
>>> withAsync proc $ \_ -> Square 2 `query` doubler
4

In this example the Square constructor takes a Reply action as its last argument. It is passed partially-applied to query, which adds a new Reply action before sending it to the doubler and then waiting for it. The doubler process will run the Reply action n STM with the reply as its argument. In this case i * i.

receiveMatch :: (MonadIO m, Mailbox mbox msg) => mbox msg -> (msg -> Maybe a) -> m a

Test all the messages in a mailbox against the supplied function and return the output of the function only when it is Just. Will block until a message matches. All messages that did not match are left in the mailbox. Only call from process that owns mailbox.

receiveMatchSTM :: Mailbox mbox msg => mbox msg -> (msg -> Maybe a) -> STM a

Match a message in the mailbox as an atomic STM action.

mailboxEmpty :: (MonadIO m, Mailbox mbox msg) => mbox msg -> m Bool

Check if the mailbox is empty.