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


-- | Baisc, Erlang-like message passing supporting sockets.
--   
--   This package provides Erlang-like mailboxes for message passing. It
--   also supports wrapping communication via e.g. sockets.
@package epass
@version 0.1


-- | This module provides Erlang like functionality for message passing.
--   
--   Instead of mailboxes attached to each process you have to create the
--   needed mailboxes yourself. This means that messages cannot be send to
--   processes or threads directly, but only to mailboxes. On the other
--   hand multiple threads may share a mailbox and one thread may have
--   multiple mailboxes.
--   
--   For a simple example on how to receive messages have a look at the
--   <a>MsgHandler</a> type.
module Control.Concurrent.Mailbox

-- | Any instance of <a>MailboxClass</a> may be used as a mailbox for
--   message passing. <tt>b</tt> is the mailbox type and m is the message
--   type.
class MailboxClass b
getMessage :: (MailboxClass b) => b m -> IO m
unGetMessage :: (MailboxClass b) => b m -> m -> IO ()
putMessage :: (MailboxClass b) => b m -> m -> IO ()
isEmpty :: (MailboxClass b) => b m -> IO Bool
close :: (MailboxClass b) => b m -> IO ()

-- | A <a>Chan</a> based mailbox.
data Mailbox m

-- | Creates a new mailbox.
newMailbox :: IO (Mailbox m)

-- | Send the given message to the given mailbox.
send :: (MailboxClass b) => b m -> m -> IO ()

-- | An alias for <a>send</a> in the flavor of Erlang's <tt>!</tt>.
(<!) :: (MailboxClass b) => b m -> m -> IO ()

-- | Receive messages in the flavour of Erlang's <tt>receive</tt>.
--   
--   For each message in the mailbox all message handlers are matched until
--   a matching message is found. It will be removed from the mailbox and
--   the matching message handler's action will be performed.
--   
--   If no message matches any of the message handler, <a>receive</a> will
--   block and check new incoming messages until a match is found.
receive :: (MailboxClass b) => b m -> [MsgHandler m a] -> IO a

-- | Like <a>receive</a>, but doesn't block. If no match was found, the
--   default handler is executed.
receiveNonBlocking :: (MailboxClass b) => b m -> [MsgHandler m a] -> IO a -> IO a

-- | Like <a>receive</a>, but times out after a given time. In case of
--   timeout the timeout handler is executed.
receiveTimeout :: (MailboxClass b) => b m -> Int -> [MsgHandler m a] -> IO a -> IO a

-- | A function that matches a given message and returns the corresponding
--   handler.
--   
--   In case of an pattern matching error <a>receive</a> will continue
--   matching the next <a>MsgHandler</a> / message.
--   
--   For example you may write somthing like this:
--   
--   <pre>
--   receive mbox
--       [ \ True  -&gt; handler $ return 1
--       , \ False -&gt; handler $ return 2
--       ]
--   </pre>
type MsgHandler m a = m -> Handler a

-- | The action to perfom in case of successful matching.
data Handler a

-- | Generate a handler from an <a>IO</a> action.
handler :: IO a -> Handler a

-- | Apply a function to the result of an message handler.
(.>) :: MsgHandler m a -> (a -> b) -> MsgHandler m b

-- | Combine to lists of message handlers into one list. The results of the
--   message handler will be wrapped in <a>Either</a>.
(<|>) :: [MsgHandler m a] -> [MsgHandler m b] -> [MsgHandler m (Either a b)]
instance MailboxClass Mailbox


-- | This module provides a wrapping mechanism for file handles (e.g.
--   sockets)
module Control.Concurrent.Mailbox.Wrapper

-- | Messages send over wrapped handles must be instance of this class.
--   
--   You only need to implement either <a>fromString</a> or
--   <a>fromStringReadS</a>.
class Wrappable m
toString :: (Wrappable m) => m -> String
fromString :: (Wrappable m) => String -> Maybe m
fromStringReadS :: (Wrappable m) => ReadS m

-- | Wrapper around <a>Mailbox</a>. For now the only <a>MailboxClass</a>
--   instance allowed for wrapping.
data WrapBox m

-- | Function to be called in case of error. <a>WrapBox</a> is the mailbox
--   the error occured on.
type ErrorHandler m = WrapBox m -> IOError -> IO ()

-- | Wrap the given <a>Handle</a> for reading. The returned <a>WrapBox</a>
--   can be used to receive messages from the <a>Handle</a>.
--   
--   Notice: The <a>ErrorHandler</a> will be given the returned
--   <a>WrapBox</a>. Writing to may not be what you want to do. Instead you
--   might first call <a>wrapWriteHandle</a> and then use its
--   <a>WrapBox</a> in <a>wrapReadHandle</a>s <a>ErrorHandler</a>.
wrapReadHandle :: (Wrappable m) => Handle -> ErrorHandler m -> IO (WrapBox m)

-- | Wrap the given <a>Handle</a> for writing. The returned <a>WrapBox</a>
--   can be used to send messages through the <a>Handle</a>.
wrapWriteHandle :: (Wrappable m) => Handle -> ErrorHandler m -> IO (WrapBox m)

-- | Same as <a>wrapReadHandle</a> but use an existing <a>Mailbox</a> for
--   wrapping.
wrapReadHandleWithMailbox :: (Wrappable m) => Handle -> Mailbox m -> ErrorHandler m -> IO (WrapBox m)

-- | Same as <a>wrapWriteHandle</a> but use an existing <a>Mailbox</a> for
--   wrapping.
wrapWriteHandleWithMailbox :: (Wrappable m) => Handle -> Mailbox m -> ErrorHandler m -> IO (WrapBox m)
instance MailboxClass WrapBox