Actors.lhs

> {-# LANGUAGE GeneralizedNewtypeDeriving, ViewPatterns #-}

This module exports a simple, idiomatic implementation of the Actor Model.

> module Control.Concurrent.Actors (
>     -- * Actor computations
>       Actor
>     , Loop
>     , NextActor(..)
>     , ActorM()
>     -- ** Building Actors
>     , continue
>     , continue_
>     , done
>     , aseq
>     -- * Message passing and IO
>     , send
>     -- ** Actor system output:
>     , receive
>     , receiveList
>     -- ** Mailbox
>     , Mailbox()
>     , newMailbox
>     -- * Running Actors
>     , Action()
>     , forkActor
>     , forkActorUsing
>     , forkLoop
>     , runActorUsing
>     , runLoop
>     ) where
>
> import Control.Monad
> import Control.Monad.IO.Class
> import Control.Monad.Trans.Maybe
> import Control.Concurrent
> import Control.Applicative

TODO?:
    - Function for combining mailboxes (make a monoid? Only allow doing this in IO?)

    Alternately: what if we delegated a single 'mainActor' that is in IO, and which
    any Actor can send a message to? This would be an IO event loop and we would run
    this IO loop from 'main' which would block until... so tired.

    RE: Mailbox Class:
        - Having such a class is a decent idea anyway since we may want to have
          a synchronous Mailbox type, in which case we should 

Here we define the Actor environment, similar to IO, in which we can launch new
Actors and send messages to Actors in scope. The implementation is hidden from
the user to enforce these restrictions.

> -- | The Actor encironment in which Actors can be spawned and sent messages
> newtype ActorM a = ActorM { actorM :: MaybeT IO a }
>                  deriving (Monad, Functor, Applicative, 
>                            Alternative, MonadPlus, MonadIO)
>
> runActorM = runMaybeT . actorM

First we define an Actor: a function that takes an input, maybe returning a new
actor:

    TODO: Consider making Actor the newtype and eliminating NextActor
      newtype Actor i = Actor { actor :: i -> ActorM (Actor i) }
      continue :: (i -> ActorM (Actor i)) -> ActorM (Actor i)


> type Actor i = i -> ActorM (NextActor i)
> newtype NextActor i = NextActor { nextActor :: Actor i } 

Now some functions for building Actor computations:

> -- | Continue with a new Actor computation step
> continue :: Actor i -> ActorM (NextActor i)
> continue = return . NextActor

    IMPLEMENTATION NOTE: 
        when an actor terminates, its mailbox persists and we                        
        currently provide no functions to query an actor's status.                    
        Signaling an actor's termination should be done with                          
        message passing.

> -- | Actor terminating:
> done :: ActorM (NextActor i)
> done = mzero

    IMPLEMENTATION NOTE: 
        We might find that we can use the monoid abstraction, or 
        that we should make Actor a newtype for other reasons. For
        now we have this for composing

> -- | compose two actors. The second will take over when the first exits
> aseq :: Actor i -> Actor i -> Actor i
> aseq f g i = NextActor <$> (nextf <|> return g)
>     where nextf = (`aseq` g) . nextActor <$> f i


A Loop is just an Actor that ignores its input. We provide some useful
functions for building and running such computations:

> -- | An Actor that discards its input, i.e. a simple loop.
> type Loop = ActorM (NextActor ())
>
> -- | Continue with a Loop computation
> continue_ :: Loop -> ActorM (NextActor i)
> continue_ = fmap (NextActor . fixConst . nextActor)
>     where fixConst c = const $ continue_ $ c ()



Here we define the "mailbox" that an Actor collects messages from, and other
actors send messages to. It is simply a Chan with hidden implementation.

    IMPLEMENTATION NOTE: 
        we make no attempt to ensure that only one actor is reading                    
        from a given Chan. This means two Actors can share the work                    
        reading from the same mailbox.
        
        If we want to change this in the future, Mailbox will contain
        a type :: TVar ThreadID

        To implement synchronous chans (or singly-buffered chans), 
        we can use a SyncMailbox type containing an MVar and
        possibly another Var for ensuring syncronicity. An MVar
        writer will never block indefinitely. Use a class for writing
        and reading these mailbox types.

     
> -- | the buffered message passing medium used between actors
> newtype Mailbox i = Mailbox { mailbox :: Chan i }
>

    IMPLEMENTATION NOTE: 
        We allow sending of messages to Actors in IO, treating the 
        main thread as something of an Actor with special privileges;
        It can launch actors and message them, but also read as it 
        pleases from Mailboxes


> -- | Send a message to an Actor. Actors can only be passed messages from other
> -- actors.
> send :: (Action m)=> Mailbox a -> a -> m ()
> send b = liftIOtoA . writeChan (mailbox b)

> -- | Read a message from a mailbox in the IO monad. This can be used as the
> -- mechanism for output from an Actor system. Blocks if the actor is empty
> receive :: Mailbox o -> IO o
> receive = readChan . mailbox

> -- | Return a lazy list of mailbox contents
> receiveList :: Mailbox o -> IO [o]
> receiveList = getChanContents . mailbox

> -- | create a new mailbox that Actors can be launched to read from or
> -- send messages to in order to communicate with other actors
> newMailbox :: (Action m)=> m (Mailbox a)
> newMailbox = liftIOtoA newChan >>= return . Mailbox


The Action class represents environments in which we can operate on actors. That
is we would like to be able to send a message in IO

> -- | monads in the Action class can participate in message passing and other
> -- Actor operations
> class Monad m => Action m where
>     liftIOtoA :: IO a -> m a
>
>     forkA :: IO () -> m ()
>     forkA io = liftIOtoA $ forkIO io >> return ()
>
> instance Action IO where
>     liftIOtoA = id
>
> instance Action ActorM where
>     liftIOtoA = ActorM . liftIO




> -- | fork an actor, returning its mailbox
> forkActor :: (Action m)=> Actor i -> m (Mailbox i)
> forkActor a = do
>     b <- newMailbox
>     forkActorUsing b a
>     return b
>     
> -- | fork an actor that reads from the supplied Mailbox
> forkActorUsing :: (Action m)=> Mailbox i -> Actor i -> m ()
> forkActorUsing b = forkA . actorHandler b
>
> -- | fork a looping computation which starts immediately
> forkLoop :: (Action m)=> Loop -> m ()
> forkLoop = forkA . runLoop  
>
> -- | run a Loop actor in the main thread, returning when the computation exits
> runLoop :: Loop -> IO ()
> runLoop l = runActorM l >>= 
>              maybe (return ()) (runLoop . ($ ()) .  nextActor)

>
> -- | run an Actor in the main thread, returning when the Actor exits
> runActorUsing :: Mailbox i -> Actor i -> IO ()
> runActorUsing = actorHandler


Internal function that feeds the actor computation its values. This may be
extended to support additional functionality in the future.

> actorHandler :: Mailbox i -> Actor i -> IO ()
> actorHandler (mailbox->c) = loop
>     where loop a = readChan c >>= 
>                     runActorM . a >>= 
>                      maybe (return ()) (loop . nextActor)