packages feed

nqe-0.7.0: src/Control/Concurrent/NQE/Process.hs

{-# 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.
--
-- * __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.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.
--
-- This is typically used as a callback embedded in a message so that the
-- receiver can reply to the sender, or by a 'Control.Concurrent.NQE.Publisher'
-- to forward events to subscribers. Because it runs in 'STM' it must not block
-- for long, and should normally just write to a 'TMVar', 'TQueue' or similar.
--
-- Using an 'STM' callback rather than a reply channel keeps the receiver
-- ignorant of how the sender wants its answer, and lets the reply be part of the
-- same transaction as whatever else the receiver does.
type Listen a = a -> STM ()

-- | Channel that only allows messages to be sent to it.
--
-- A 'Mailbox' hides the underlying channel implementation, so that any type
-- with an 'OutChan' instance can be used. Each mailbox carries a 'Unique'
-- identifier, which is used for its 'Eq' and 'Hashable' instances. Two
-- mailboxes are equal if and only if they point to the same channel.
--
-- Obtain one from an 'Inbox' using 'inboxToMailbox', or create a pair with
-- 'newMailbox'.
--
-- The point of a separate send-only type is the principle of least authority:
-- 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

-- | Channel that allows to send or receive messages.
--
-- An 'Inbox' is the receiving end of a channel and should be owned by a single
-- process. Like 'Mailbox', it carries a 'Unique' identifier used for equality.
-- Create one with 'newInbox', 'newBoundedInbox' or 'wrapChannel'.
--
-- 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

instance Eq (Mailbox msg) where
  (==) = (==) `on` f
    where
      f (Mailbox _ u) = u

instance Eq (Inbox msg) where
  (==) = (==) `on` f
    where
      f (Inbox _ u) = u

-- | 'Async' handle and 'Mailbox' for a process.
--
-- A 'Process' is an instance of 'OutChan', so messages can be sent to it
-- directly using 'send' or 'query'. Use 'getProcessAsync' to wait for the
-- process or cancel it.
data Process msg = Process
  { -- | 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'.
--
-- Instances are provided for 'TQueue', 'TBQueue' and 'Inbox'.
--
-- The classes exist so that the same functions work on raw STM queues, on
-- '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 ()

-- | 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 ()

instance InChan TQueue where
  mailboxEmptySTM = isEmptyTQueue
  receiveSTM = readTQueue
  requeueSTM msg = (`unGetTQueue` msg)

instance OutChan TQueue where
  mailboxFullSTM _ = return False
  sendSTM msg = (`writeTQueue` msg)

instance InChan TBQueue where
  mailboxEmptySTM = isEmptyTBQueue
  receiveSTM = readTBQueue
  requeueSTM msg = (`unGetTBQueue` msg)

instance OutChan TBQueue where
  mailboxFullSTM = isFullTBQueue
  sendSTM msg = (`writeTBQueue` msg)

instance OutChan Mailbox where
  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

instance OutChan Inbox where
  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

instance Hashable (Process msg) where
  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

-- | Get a send-only 'Mailbox' for an 'Inbox'.
inboxToMailbox :: Inbox msg -> Mailbox msg
inboxToMailbox (Inbox m u) = Mailbox m u

-- | 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 :: (InChan mbox, OutChan mbox) => mbox msg -> IO (Inbox msg)
wrapChannel mbox = Inbox mbox <$> newUnique

-- | Create an unbounded 'Inbox' backed by a 'TQueue'.
newInbox :: IO (Inbox msg)
newInbox = newTQueueIO >>= \c -> wrapChannel c

-- | Create an 'Inbox' backed by a 'TBQueue' with an upper bound on the number
-- of queued messages. Senders block while the inbox is full.
--
-- 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 :: 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 :: (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) => mbox msg -> IO msg
receive mbox = receiveMatch mbox Just

-- | Send request to channel and wait for a response. The @request@ 'STM' action
-- will be created by this function.
--
-- The first argument is usually a data constructor that takes a 'Listen'
-- callback as its last field. This function creates an empty 'TMVar', builds
-- the request with a callback that fills it, sends the request, and blocks until
-- the receiver runs the callback.
--
-- If the receiver never answers, this function blocks forever. See 'queryU' and
-- 'queryS' for versions with a timeout.
--
-- This is the NQE equivalent of a function call across threads. It is also the
-- main way to deadlock an NQE program: a process that queries another process
-- that is, directly or indirectly, querying it back will wait forever. Keep
-- requests flowing in one direction, or use 'queryS' with a timeout.
query ::
  (OutChan mbox) =>
  (Listen response -> request) ->
  mbox request ->
  IO response
query f m = do
  r <- newEmptyTMVarIO
  f (putTMVar r) `send` m
  atomically $ takeTMVar r

-- | Do a 'query' but timeout after @u@ microseconds. Return 'Nothing' if
-- timeout reached.
queryU ::
  (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 ::
  (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
-- first matching message. Will block until a match is found. Messages that do
-- not match remain in the channel.
--
-- Selective receive lets a process wait for one particular reply while leaving
-- 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 :: (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 ::
  (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 ::
  (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 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)

-- | 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 :: (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 xs mbox = mapM_ (`requeueSTM` mbox) xs

-- | Run a process in the background and pass it to a function. Stop the
-- background process once the function returns. Background process exceptions
-- are re-thrown in the current thread.
--
-- 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 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 :: (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))

-- | Run a process in the background and return the 'Process' handle. Background
-- process exceptions are re-thrown in the current thread.
--
-- 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 :: (Inbox msg -> IO ()) -> IO (Process msg)
process p = do
  (i, m) <- newMailbox
  a <- async $ p i
  link a
  return (Process a m)

-- | Create an unbounded inbox and corresponding mailbox.
newMailbox :: IO (Inbox msg, Mailbox msg)
newMailbox = do
  i <- newInbox
  let m = inboxToMailbox i
  return (i, m)