-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Lightweight Erlang-style actors for Haskell.
--   
--   Hactor is a library which aims to provide lightweight Erlang-style
--   actors for Haskell.
@package hactor
@version 1.2.0.0


-- | Module exposing more of hactor's internals. Use with caution.
module Control.Concurrent.Actor.Internal

-- | An <tt>ActorHandle</tt> acts as a reference to a specific actor.
data ActorMessage msg => ActorHandle msg
ActorHandle :: ActorContext msg -> ThreadId -> ActorHandle msg
ahContext :: ActorHandle msg -> ActorContext msg
ahThread :: ActorHandle msg -> ThreadId

-- | The <tt>ActorMessage</tt> class must be implemented by any type that
--   will be sent as a message to actors. Any given type of actor will have
--   one <tt>ActorMessage</tt> type that is sent to that actor. This
--   ensures type safety. Currently this is simply a dummy class with
--   nothing in it, but things may be added in the future.
class ActorMessage msg

-- | The <a>MonadActor</a> typeclass. This provides the <a>actorCtx</a>
--   function, which all of the actor monad's functionality is based on.
class (ActorMessage msg, MonadActorSuper m) => MonadActor msg m

-- | The base actor monad.
data ActorM msg a

-- | Sends a message to the given actor handle.
send :: (MonadIO m, ActorMessage msg) => ActorHandle msg -> msg -> m ()

-- | Reads a message from the actor's mail box. If there are no messages,
--   blocks until one is received. If you don't want this, use
--   <tt>receiveMaybe</tt> instead.
receive :: (ActorMessage msg, MonadActor msg m) => m (msg)

-- | Reads a message from the actor's mail box. If there are no messages,
--   returns <tt>Nothing</tt>.
receiveMaybe :: (ActorMessage msg, MonadActor msg m) => m (Maybe msg)

-- | An <tt>ActorM</tt> action which returns an <tt>STM</tt> action to
--   receive a message.
receiveSTM :: (ActorMessage msg, MonadActor msg m) => m (STM msg)

-- | Runs the given <a>ActorM</a> in the IO monad with the given context.
runActorM :: ActorMessage msg => ActorM msg a -> ActorContext msg -> IO a

-- | Internal function for starting actors. This takes an <tt>ActorM</tt>
--   action, makes a channel for it, wraps it in exception handling stuff,
--   and turns it into an IO monad. The function returns a tuple containing
--   the actor's context and the IO action to execute the actor.
wrapActor :: ActorMessage msg => ActorM msg () -> IO (IO (), ActorContext msg)

-- | Spawns the given actor on another thread and returns a handle to it.
spawnActor :: ActorMessage msg => ActorM msg () -> IO (ActorHandle msg)

-- | Runs the given actor on the current thread. This function effectively
--   turns the current thread into the actor's thread. Obviously, this
--   means that this function will block until the actor exits. You
--   probably want to use this for your "main" actor.
runActor :: ActorMessage msg => ActorM msg () -> IO ()

-- | Gets a handle to the current actor.
self :: (ActorMessage msg, MonadActor msg m) => m (ActorHandle msg)

-- | Gets the thread ID for the given actor handle.
actorThread :: ActorMessage msg => ActorHandle msg -> ThreadId

-- | The <tt>ActorContext</tt> holds shared information about a given
--   actor. This is information such as the actor's mail box, the list of
--   actors it's linked to, etc.
data ActorMessage msg => ActorContext msg
ActorContext :: MailBox msg -> ActorContext msg
acMailBox :: ActorContext msg -> MailBox msg

-- | The type for the actor's mail box.
type MailBox msg = TChan msg

-- | Gets the internal context object for the current actor. This is an
--   internal function and may be dangerous. Use with caution.
getContext :: (ActorMessage msg, MonadActor msg m) => m (ActorContext msg)

-- | Retrieves the mail box for the current actor. This is an internal
--   function and may be dangerous. Use with caution.
getMailBox :: (ActorMessage msg, MonadActor msg m) => m (MailBox msg)
instance Functor (ActorM msg)
instance Applicative (ActorM msg)
instance Monad (ActorM msg)
instance MonadIO (ActorM msg)
instance MonadThrow (ActorM msg)
instance ActorMessage msg => MonadBaseControl IO (ActorM msg)
instance ActorMessage msg => MonadBase IO (ActorM msg)
instance (ActorMessage msg, MonadActor msg m, MonadTrans t, MonadActorSuper (t m)) => MonadActor msg (t m)
instance ActorMessage msg => MonadActor msg (ActorM msg)
instance ActorMessage ()


-- | This module implements Erlang-style actors (what Erlang calls
--   processes).
module Control.Concurrent.Actor

-- | An <tt>ActorHandle</tt> acts as a reference to a specific actor.
data ActorMessage msg => ActorHandle msg

-- | The <tt>ActorMessage</tt> class must be implemented by any type that
--   will be sent as a message to actors. Any given type of actor will have
--   one <tt>ActorMessage</tt> type that is sent to that actor. This
--   ensures type safety. Currently this is simply a dummy class with
--   nothing in it, but things may be added in the future.
class ActorMessage msg

-- | The <a>MonadActor</a> typeclass. This provides the <a>actorCtx</a>
--   function, which all of the actor monad's functionality is based on.
class (ActorMessage msg, MonadActorSuper m) => MonadActor msg m

-- | The base actor monad.
data ActorM msg a

-- | Sends a message to the given actor handle.
send :: (MonadIO m, ActorMessage msg) => ActorHandle msg -> msg -> m ()

-- | Reads a message from the actor's mail box. If there are no messages,
--   blocks until one is received. If you don't want this, use
--   <tt>receiveMaybe</tt> instead.
receive :: (ActorMessage msg, MonadActor msg m) => m (msg)

-- | Reads a message from the actor's mail box. If there are no messages,
--   returns <tt>Nothing</tt>.
receiveMaybe :: (ActorMessage msg, MonadActor msg m) => m (Maybe msg)

-- | An <tt>ActorM</tt> action which returns an <tt>STM</tt> action to
--   receive a message.
receiveSTM :: (ActorMessage msg, MonadActor msg m) => m (STM msg)

-- | Spawns the given actor on another thread and returns a handle to it.
spawnActor :: ActorMessage msg => ActorM msg () -> IO (ActorHandle msg)

-- | Runs the given actor on the current thread. This function effectively
--   turns the current thread into the actor's thread. Obviously, this
--   means that this function will block until the actor exits. You
--   probably want to use this for your "main" actor.
runActor :: ActorMessage msg => ActorM msg () -> IO ()

-- | Gets a handle to the current actor.
self :: (ActorMessage msg, MonadActor msg m) => m (ActorHandle msg)

-- | Gets the thread ID for the given actor handle.
actorThread :: ActorMessage msg => ActorHandle msg -> ThreadId