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


-- | Cloud Haskell: Erlang-style concurrency in Haskell
--   
--   This is an implementation of Cloud Haskell, as described in <i>Towards
--   Haskell in the Cloud</i> by Jeff Epstein, Andrew Black, and Simon
--   Peyton Jones
--   (<a>http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/</a>),
--   although some of the details are different. The precise message
--   passing semantics are based on <i>A unified semantics for future
--   Erlang</i> by Hans Svensson, Lars-Åke Fredlund and Clara Benac Earle.
--   You will probably also want to install a Cloud Haskell backend such as
--   distributed-process-simplelocalnet.
@package distributed-process
@version 0.3.0


-- | Concurrent queue for single reader, single writer
module Control.Distributed.Process.Internal.CQueue
data CQueue a
data BlockSpec
NonBlocking :: BlockSpec
Blocking :: BlockSpec
Timeout :: Int -> BlockSpec
newCQueue :: IO (CQueue a)
enqueue :: CQueue a -> a -> IO ()

-- | Dequeue an element
--   
--   The timeout (if any) is applied only to waiting for incoming messages,
--   not to checking messages that have already arrived
dequeue :: CQueue a -> BlockSpec -> [a -> Maybe b] -> IO (Maybe b)

module Control.Distributed.Process.Serializable

-- | Objects that can be sent across the network
class (Binary a, Typeable a) => Serializable a

-- | Encode type representation as a bytestring
encodeFingerprint :: Fingerprint -> ByteString

-- | Decode a bytestring into a fingerprint. Throws an IO exception on
--   failure
decodeFingerprint :: ByteString -> Fingerprint

-- | The fingerprint of the typeRep of the argument
fingerprint :: Typeable a => a -> Fingerprint

-- | Size of a fingerprint
sizeOfFingerprint :: Int
data Fingerprint :: *

-- | Show fingerprint (for debugging purposes)
showFingerprint :: Fingerprint -> ShowS

-- | Reification of <a>Serializable</a> (see
--   <a>Control.Distributed.Process.Closure</a>)
data SerializableDict a
SerializableDict :: SerializableDict a
instance Typeable1 SerializableDict
instance (Binary a, Typeable a) => Serializable a


-- | Types used throughout the Cloud Haskell framework
--   
--   We collect all types used internally in a single module because many
--   of these data types are mutually recursive and cannot be split across
--   modules.
module Control.Distributed.Process.Internal.Types

-- | Node identifier
newtype NodeId
NodeId :: EndPointAddress -> NodeId
nodeAddress :: NodeId -> EndPointAddress

-- | A local process ID consists of a seed which distinguishes processes
--   from different instances of the same local node and a counter
data LocalProcessId
LocalProcessId :: Int32 -> Int32 -> LocalProcessId
lpidUnique :: LocalProcessId -> Int32
lpidCounter :: LocalProcessId -> Int32

-- | Process identifier
data ProcessId
ProcessId :: NodeId -> LocalProcessId -> ProcessId

-- | The ID of the node the process is running on
processNodeId :: ProcessId -> NodeId

-- | Node-local identifier for the process
processLocalId :: ProcessId -> LocalProcessId

-- | Union of all kinds of identifiers
data Identifier
NodeIdentifier :: NodeId -> Identifier
ProcessIdentifier :: ProcessId -> Identifier
SendPortIdentifier :: SendPortId -> Identifier
nodeOf :: Identifier -> NodeId

-- | Local nodes
data LocalNode
LocalNode :: NodeId -> EndPoint -> MVar LocalNodeState -> Chan NCMsg -> RemoteTable -> LocalNode

-- | <a>NodeId</a> of the node
localNodeId :: LocalNode -> NodeId

-- | The network endpoint associated with this node
localEndPoint :: LocalNode -> EndPoint

-- | Local node state
localState :: LocalNode -> MVar LocalNodeState

-- | Channel for the node controller
localCtrlChan :: LocalNode -> Chan NCMsg

-- | Runtime lookup table for supporting closures TODO: this should be part
--   of the CH state, not the local endpoint state
remoteTable :: LocalNode -> RemoteTable

-- | Local node state
data LocalNodeState
LocalNodeState :: Map LocalProcessId LocalProcess -> Int32 -> Int32 -> Map (Identifier, Identifier) Connection -> LocalNodeState
_localProcesses :: LocalNodeState -> Map LocalProcessId LocalProcess
_localPidCounter :: LocalNodeState -> Int32
_localPidUnique :: LocalNodeState -> Int32
_localConnections :: LocalNodeState -> Map (Identifier, Identifier) Connection

-- | Processes running on our local node
data LocalProcess
LocalProcess :: CQueue Message -> ProcessId -> MVar LocalProcessState -> ThreadId -> LocalNode -> LocalProcess
processQueue :: LocalProcess -> CQueue Message
processId :: LocalProcess -> ProcessId
processState :: LocalProcess -> MVar LocalProcessState
processThread :: LocalProcess -> ThreadId
processNode :: LocalProcess -> LocalNode

-- | Local process state
data LocalProcessState
LocalProcessState :: Int32 -> Int32 -> Int32 -> Map LocalSendPortId TypedChannel -> LocalProcessState
_monitorCounter :: LocalProcessState -> Int32
_spawnCounter :: LocalProcessState -> Int32
_channelCounter :: LocalProcessState -> Int32
_typedChannels :: LocalProcessState -> Map LocalSendPortId TypedChannel

-- | The Cloud Haskell <a>Process</a> type
newtype Process a
Process :: ReaderT LocalProcess IO a -> Process a
unProcess :: Process a -> ReaderT LocalProcess IO a

-- | Deconstructor for <a>Process</a> (not exported to the public API)
runLocalProcess :: LocalProcess -> Process a -> IO a
type LocalSendPortId = Int32

-- | A send port is identified by a SendPortId.
--   
--   You cannot send directly to a SendPortId; instead, use
--   <tt>newChan</tt> to create a SendPort.
data SendPortId
SendPortId :: ProcessId -> LocalSendPortId -> SendPortId

-- | The ID of the process that will receive messages sent on this port
sendPortProcessId :: SendPortId -> ProcessId

-- | Process-local ID of the channel
sendPortLocalId :: SendPortId -> LocalSendPortId
data TypedChannel
TypedChannel :: (TChan a) -> TypedChannel

-- | The send send of a typed channel (serializable)
newtype SendPort a
SendPort :: SendPortId -> SendPort a

-- | The (unique) ID of this send port
sendPortId :: SendPort a -> SendPortId

-- | The receive end of a typed channel (not serializable)
data ReceivePort a

-- | A single receive port
ReceivePortSingle :: (TChan a) -> ReceivePort a

-- | A left-biased combination of receive ports
ReceivePortBiased :: [ReceivePort a] -> ReceivePort a

-- | A round-robin combination of receive ports
ReceivePortRR :: (TVar [ReceivePort a]) -> ReceivePort a

-- | Messages consist of their typeRep fingerprint and their encoding
data Message
Message :: Fingerprint -> ByteString -> Message
messageFingerprint :: Message -> Fingerprint
messageEncoding :: Message -> ByteString

-- | Turn any serialiable term into a message
createMessage :: Serializable a => a -> Message

-- | Serialize a message
messageToPayload :: Message -> [ByteString]

-- | Deserialize a message
payloadToMessage :: [ByteString] -> Message

-- | MonitorRef is opaque for regular Cloud Haskell processes
data MonitorRef
MonitorRef :: Identifier -> Int32 -> MonitorRef

-- | ID of the entity to be monitored
monitorRefIdent :: MonitorRef -> Identifier

-- | Unique to distinguish multiple monitor requests by the same process
monitorRefCounter :: MonitorRef -> Int32

-- | Message sent by process monitors
data ProcessMonitorNotification
ProcessMonitorNotification :: MonitorRef -> ProcessId -> DiedReason -> ProcessMonitorNotification

-- | Message sent by node monitors
data NodeMonitorNotification
NodeMonitorNotification :: MonitorRef -> NodeId -> DiedReason -> NodeMonitorNotification

-- | Message sent by channel (port) monitors
data PortMonitorNotification
PortMonitorNotification :: MonitorRef -> SendPortId -> DiedReason -> PortMonitorNotification

-- | Exceptions thrown when a linked process dies
data ProcessLinkException
ProcessLinkException :: ProcessId -> DiedReason -> ProcessLinkException

-- | Exception thrown when a linked node dies
data NodeLinkException
NodeLinkException :: NodeId -> DiedReason -> NodeLinkException

-- | Exception thrown when a linked channel (port) dies
data PortLinkException
PortLinkException :: SendPortId -> DiedReason -> PortLinkException

-- | Why did a process die?
data DiedReason

-- | Normal termination
DiedNormal :: DiedReason

-- | The process exited with an exception (provided as <a>String</a>
--   because <a>Exception</a> does not implement <a>Binary</a>)
DiedException :: String -> DiedReason

-- | We got disconnected from the process node
DiedDisconnect :: DiedReason

-- | The process node died
DiedNodeDown :: DiedReason

-- | Invalid (process<i>node</i>channel) identifier
DiedUnknownId :: DiedReason

-- | (Asynchronous) reply from unmonitor
newtype DidUnmonitor
DidUnmonitor :: MonitorRef -> DidUnmonitor

-- | (Asynchronous) reply from unlink
newtype DidUnlinkProcess
DidUnlinkProcess :: ProcessId -> DidUnlinkProcess

-- | (Asynchronous) reply from unlinkNode
newtype DidUnlinkNode
DidUnlinkNode :: NodeId -> DidUnlinkNode

-- | (Asynchronous) reply from unlinkPort
newtype DidUnlinkPort
DidUnlinkPort :: SendPortId -> DidUnlinkPort

-- | <a>SpawnRef</a> are used to return pids of spawned processes
newtype SpawnRef
SpawnRef :: Int32 -> SpawnRef

-- | (Asynchronius) reply from <tt>spawn</tt>
data DidSpawn
DidSpawn :: SpawnRef -> ProcessId -> DidSpawn

-- | (Asynchronous) reply from <tt>whereis</tt>
data WhereIsReply
WhereIsReply :: String -> (Maybe ProcessId) -> WhereIsReply

-- | Messages to the node controller
data NCMsg
NCMsg :: Identifier -> ProcessSignal -> NCMsg
ctrlMsgSender :: NCMsg -> Identifier
ctrlMsgSignal :: NCMsg -> ProcessSignal

-- | Signals to the node controller (see <a>NCMsg</a>)
data ProcessSignal
Link :: Identifier -> ProcessSignal
Unlink :: Identifier -> ProcessSignal
Monitor :: MonitorRef -> ProcessSignal
Unmonitor :: MonitorRef -> ProcessSignal
Died :: Identifier -> DiedReason -> ProcessSignal
Spawn :: (Closure (Process ())) -> SpawnRef -> ProcessSignal
WhereIs :: String -> ProcessSignal
Register :: String -> (Maybe ProcessId) -> ProcessSignal
NamedSend :: String -> Message -> ProcessSignal
localProcesses :: Accessor LocalNodeState (Map LocalProcessId LocalProcess)
localPidCounter :: Accessor LocalNodeState Int32
localPidUnique :: Accessor LocalNodeState Int32
localConnections :: Accessor LocalNodeState (Map (Identifier, Identifier) Connection)
localProcessWithId :: LocalProcessId -> Accessor LocalNodeState (Maybe LocalProcess)
localConnectionBetween :: Identifier -> Identifier -> Accessor LocalNodeState (Maybe Connection)
monitorCounter :: Accessor LocalProcessState Int32
spawnCounter :: Accessor LocalProcessState Int32
channelCounter :: Accessor LocalProcessState LocalSendPortId
typedChannels :: Accessor LocalProcessState (Map LocalSendPortId TypedChannel)
typedChannelWithId :: LocalSendPortId -> Accessor LocalProcessState (Maybe TypedChannel)
instance Typeable LocalProcessId
instance Typeable ProcessId
instance Typeable1 SendPort
instance Typeable1 ReceivePort
instance Typeable PortLinkException
instance Typeable NodeLinkException
instance Typeable ProcessLinkException
instance Typeable PortMonitorNotification
instance Typeable NodeMonitorNotification
instance Typeable ProcessMonitorNotification
instance Typeable DidUnmonitor
instance Typeable DidUnlinkProcess
instance Typeable DidUnlinkNode
instance Typeable DidUnlinkPort
instance Typeable SpawnRef
instance Typeable DidSpawn
instance Typeable WhereIsReply
instance Typeable1 Process
instance Eq NodeId
instance Ord NodeId
instance Binary NodeId
instance Eq LocalProcessId
instance Ord LocalProcessId
instance Show LocalProcessId
instance Eq ProcessId
instance Ord ProcessId
instance Eq SendPortId
instance Ord SendPortId
instance Eq Identifier
instance Ord Identifier
instance Binary (SendPort a)
instance Show (SendPort a)
instance Eq (SendPort a)
instance Ord (SendPort a)
instance Eq MonitorRef
instance Ord MonitorRef
instance Show MonitorRef
instance Show DiedReason
instance Eq DiedReason
instance Show PortLinkException
instance Show NodeLinkException
instance Show ProcessLinkException
instance Show PortMonitorNotification
instance Show NodeMonitorNotification
instance Show ProcessMonitorNotification
instance Binary DidUnmonitor
instance Binary DidUnlinkProcess
instance Binary DidUnlinkNode
instance Binary DidUnlinkPort
instance Show SpawnRef
instance Binary SpawnRef
instance Eq SpawnRef
instance Show DidSpawn
instance Show WhereIsReply
instance Show ProcessSignal
instance Functor Process
instance Monad Process
instance MonadIO Process
instance MonadReader LocalProcess Process
instance Applicative Process
instance Show NCMsg
instance Binary WhereIsReply
instance Binary Identifier
instance Binary SendPortId
instance Binary DidSpawn
instance Binary DiedReason
instance Binary ProcessSignal
instance Binary MonitorRef
instance Binary NCMsg
instance Binary PortMonitorNotification
instance Binary NodeMonitorNotification
instance Binary ProcessMonitorNotification
instance Binary ProcessId
instance Binary LocalProcessId
instance Exception PortLinkException
instance Exception NodeLinkException
instance Exception ProcessLinkException
instance Show Message
instance Show SendPortId
instance Show Identifier
instance Show ProcessId
instance Show NodeId

module Control.Distributed.Process.Internal.Node
sendPayload :: LocalNode -> Identifier -> Identifier -> [ByteString] -> IO ()
sendBinary :: Binary a => LocalNode -> Identifier -> Identifier -> a -> IO ()
sendMessage :: Serializable a => LocalNode -> Identifier -> Identifier -> a -> IO ()


-- | Cloud Haskell primitives
--   
--   We define these in a separate module so that we don't have to rely on
--   the closure combinators
module Control.Distributed.Process.Internal.Primitives

-- | Send a message
send :: Serializable a => ProcessId -> a -> Process ()

-- | Wait for a message of a specific type
expect :: Serializable a => Process a

-- | Create a new typed channel
newChan :: Serializable a => Process (SendPort a, ReceivePort a)

-- | Send a message on a typed channel
sendChan :: Serializable a => SendPort a -> a -> Process ()

-- | Wait for a message on a typed channel
receiveChan :: Serializable a => ReceivePort a -> Process a

-- | Merge a list of typed channels.
--   
--   The result port is left-biased: if there are messages available on
--   more than one port, the first available message is returned.
mergePortsBiased :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

-- | Like <a>mergePortsBiased</a>, but with a round-robin scheduler (rather
--   than left-biased)
mergePortsRR :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

-- | Opaque type used in <a>receiveWait</a> and <a>receiveTimeout</a>
data Match b

-- | Test the matches in order against each message in the queue
receiveWait :: [Match b] -> Process b

-- | Like <a>receiveWait</a> but with a timeout.
--   
--   If the timeout is zero do a non-blocking check for matching messages.
--   A non-zero timeout is applied only when waiting for incoming messages
--   (that is, <i>after</i> we have checked the messages that are already
--   in the mailbox).
receiveTimeout :: Int -> [Match b] -> Process (Maybe b)

-- | Match against any message of the right type
match :: Serializable a => (a -> Process b) -> Match b

-- | Match against any message of the right type that satisfies a predicate
matchIf :: Serializable a => (a -> Bool) -> (a -> Process b) -> Match b

-- | Remove any message from the queue
matchUnknown :: Process b -> Match b

-- | Terminate (throws a ProcessTerminationException)
terminate :: Process a

-- | Thrown by <a>terminate</a>
data ProcessTerminationException
ProcessTerminationException :: ProcessTerminationException

-- | Our own process ID
getSelfPid :: Process ProcessId

-- | Get the node ID of our local node
getSelfNode :: Process NodeId

-- | Link to a remote process (asynchronous)
--   
--   Note that <a>link</a> provides unidirectional linking (see
--   <tt>spawnSupervised</tt>). Linking makes no distinction between normal
--   and abnormal termination of the remote process.
link :: ProcessId -> Process ()

-- | Remove a link (synchronous)
unlink :: ProcessId -> Process ()

-- | Monitor another process (asynchronous)
monitor :: ProcessId -> Process MonitorRef

-- | Remove a monitor (synchronous)
unmonitor :: MonitorRef -> Process ()

-- | Log a string
--   
--   <tt>say message</tt> sends a message (time, pid of the current
--   process, message) to the process registered as <tt>logger</tt>. By
--   default, this process simply sends the string to <tt>stderr</tt>.
--   Individual Cloud Haskell backends might replace this with a different
--   logger process, however.
say :: String -> Process ()

-- | Register a process with the local registry (asynchronous).
--   
--   The process to be registered does not have to be local itself.
register :: String -> ProcessId -> Process ()

-- | Remove a process from the local registry (asynchronous).
unregister :: String -> Process ()

-- | Query the local process registry (synchronous).
whereis :: String -> Process (Maybe ProcessId)

-- | Named send to a process in the local registry (asynchronous)
nsend :: Serializable a => String -> a -> Process ()

-- | Register a process with a remote registry (asynchronous).
--   
--   The process to be registered does not have to live on the same remote
--   node.
registerRemote :: NodeId -> String -> ProcessId -> Process ()

-- | Remove a process from a remote registry (asynchronous).
unregisterRemote :: NodeId -> String -> Process ()

-- | Query a remote process registry (synchronous)
whereisRemote :: NodeId -> String -> Process (Maybe ProcessId)

-- | Query a remote process registry (asynchronous)
--   
--   Reply will come in the form of a <a>WhereIsReply</a> message
whereisRemoteAsync :: NodeId -> String -> Process ()

-- | Named send to a process in a remote registry (asynchronous)
nsendRemote :: Serializable a => NodeId -> String -> a -> Process ()

-- | Deserialize a closure
unClosure :: Typeable a => Closure a -> Process a

-- | Lift <a>catch</a>
catch :: Exception e => Process a -> (e -> Process a) -> Process a

-- | Lift <a>mask</a>
mask :: ((forall a. Process a -> Process a) -> Process b) -> Process b

-- | Lift <a>onException</a>
onException :: Process a -> Process b -> Process a

-- | Lift <a>bracket</a>
bracket :: Process a -> (a -> Process b) -> (a -> Process c) -> Process c

-- | Lift <a>bracket_</a>
bracket_ :: Process a -> Process b -> Process c -> Process c

-- | Lift <a>finally</a>
finally :: Process a -> Process b -> Process a

-- | Like <a>expect</a> but with a timeout
expectTimeout :: Serializable a => Int -> Process (Maybe a)

-- | Asynchronous version of <tt>spawn</tt>
--   
--   (<tt>spawn</tt> is defined in terms of <a>spawnAsync</a> and
--   <a>expect</a>)
spawnAsync :: NodeId -> Closure (Process ()) -> Process SpawnRef

-- | Link to a node
linkNode :: NodeId -> Process ()

-- | Link to a channel (send port)
linkPort :: SendPort a -> Process ()

-- | Remove a node link (synchronous)
unlinkNode :: NodeId -> Process ()

-- | Remove a channel (send port) link (synchronous)
unlinkPort :: SendPort a -> Process ()

-- | Monitor a node
monitorNode :: NodeId -> Process MonitorRef

-- | Monitor a typed channel
monitorPort :: Serializable a => SendPort a -> Process MonitorRef
instance Typeable ProcessTerminationException
instance Show ProcessTerminationException
instance Exception ProcessTerminationException

module Control.Distributed.Process.Internal.Closure.BuiltIn
remoteTable :: RemoteTable -> RemoteTable

-- | Static decoder, given a static serialization dictionary.
--   
--   See module documentation of <a>Control.Distributed.Process.Closure</a>
--   for an example.
staticDecode :: Typeable a => Static (SerializableDict a) -> Static (ByteString -> a)

-- | Serialization dictionary for '()'
sdictUnit :: Static (SerializableDict ())

-- | Serialization dictionary for <a>ProcessId</a>
sdictProcessId :: Static (SerializableDict ProcessId)

-- | Serialization dictionary for <a>SendPort</a>
sdictSendPort :: Typeable a => Static (SerializableDict a) -> Static (SerializableDict (SendPort a))
sndStatic :: Static ((a, b) -> b)

-- | <tt>CP a b</tt> is a process with input of type <tt>a</tt> and output
--   of type <tt>b</tt>
type CP a b = Closure (a -> Process b)

-- | <a>CP</a> version of <a>id</a>
idCP :: Typeable a => CP a a

-- | <a>CP</a> version of (<a>***</a>)
splitCP :: (Typeable a, Typeable b, Typeable c, Typeable d) => CP a c -> CP b d -> CP (a, b) (c, d)

-- | <a>CP</a> version of <a>return</a>
returnCP :: Serializable a => Static (SerializableDict a) -> a -> Closure (Process a)

-- | (Not quite the) <a>CP</a> version of (<a>&gt;&gt;=</a>)
bindCP :: (Typeable a, Typeable b) => Closure (Process a) -> CP a b -> Closure (Process b)

-- | <a>CP</a> version of (<a>&gt;&gt;</a>)
seqCP :: (Typeable a, Typeable b) => Closure (Process a) -> Closure (Process b) -> Closure (Process b)

-- | <a>CP</a> version of <a>link</a>
cpLink :: ProcessId -> Closure (Process ())

-- | <a>CP</a> version of <a>unlink</a>
cpUnlink :: ProcessId -> Closure (Process ())

-- | <a>CP</a> version of <a>send</a>
cpSend :: Typeable a => Static (SerializableDict a) -> ProcessId -> CP a ()

-- | <a>CP</a> version of <a>expect</a>
cpExpect :: Typeable a => Static (SerializableDict a) -> Closure (Process a)

-- | <a>CP</a> version of <a>newChan</a>
cpNewChan :: Typeable a => Static (SerializableDict a) -> Closure (Process (SendPort a, ReceivePort a))


-- | Template Haskell support
module Control.Distributed.Process.Internal.Closure.TH

-- | Create the closure, decoder, and metadata definitions for the given
--   list of functions
remotable :: [Name] -> Q [Dec]

-- | Construct a static value.
--   
--   If <tt>f : forall a1 .. an. T</tt> then <tt>$(mkStatic 'f) :: forall
--   a1 .. an. Static T</tt>. Be sure to pass <tt>f</tt> to
--   <a>remotable</a>.
mkStatic :: Name -> Q Exp

-- | If <tt>f : T1 -&gt; T2</tt> is a monomorphic function then
--   <tt>$(functionSDict 'f) :: Static (SerializableDict T1)</tt>.
--   
--   Be sure to pass <tt>f</tt> to <a>remotable</a>.
functionSDict :: Name -> Q Exp

-- | If <tt>f : T1 -&gt; Process T2</tt> is a monomorphic function then
--   <tt>$(functionTDict 'f) :: Static (SerializableDict T2)</tt>.
--   
--   Be sure to pass <tt>f</tt> to <a>remotable</a>.
functionTDict :: Name -> Q Exp
mkClosure :: Name -> Q Exp


-- | <i>Towards Haskell in the Cloud</i> (Epstein et al., Haskell Symposium
--   2011) proposes a new type construct called <tt>static</tt> that
--   characterizes values that are known statically. Cloud Haskell uses the
--   <a>Static</a> implementation from <a>Control.Distributed.Static</a>.
--   That module comes with its own extensive documentation, which you
--   should read if you want to know the details. Here we explain the
--   Template Haskell support only.
--   
--   <ul>
--   <li><i>Static values</i></li>
--   </ul>
--   
--   Given a top-level (possibly polymorphic, but unqualified) definition
--   
--   <pre>
--   f :: forall a1 .. an. T
--   f = ...
--   </pre>
--   
--   you can use a Template Haskell splice to create a static version of
--   <tt>f</tt>:
--   
--   <pre>
--   $(mkStatic 'f) :: forall a1 .. an. (Typeable a1, .., Typeable an) =&gt; Static T
--   </pre>
--   
--   Every module that you write that contains calls to <a>mkStatic</a>
--   needs to have a call to <a>remotable</a>:
--   
--   <pre>
--   remotable [ 'f, 'g, ... ]
--   </pre>
--   
--   where you must pass every function (or other value) that you pass as
--   an argument to <a>mkStatic</a>. The call to <a>remotable</a> will
--   create a definition
--   
--   <pre>
--   __remoteTable :: RemoteTable -&gt; RemoteTable
--   </pre>
--   
--   which can be used to construct the <tt>RemoteTable</tt> used to
--   initialize Cloud Haskell. You should have (at most) one call to
--   <a>remotable</a> per module, and compose all created functions when
--   initializing Cloud Haskell:
--   
--   <pre>
--   let rtable :: RemoteTable 
--       rtable = M1.__remoteTable
--              . M2.__remoteTable
--              . ...
--              . Mn.__remoteTable
--              $ initRemoteTable 
--   </pre>
--   
--   NOTE: If you get a type error from ghc along these lines
--   
--   <pre>
--   The exact Name `a_a30k' is not in scope
--        Probable cause: you used a unique name (NameU) in Template Haskell but did not bind it
--   </pre>
--   
--   then you need to enable the <tt>ScopedTypeVariables</tt> language
--   extension.
--   
--   <ul>
--   <li><i>Static serialization dictionaries</i></li>
--   </ul>
--   
--   Some Cloud Haskell primitives require static serialization
--   dictionaries (**):
--   
--   <pre>
--   call :: Serializable a =&gt; Static (SerializableDict a) -&gt; NodeId -&gt; Closure (Process a) -&gt; Process a
--   </pre>
--   
--   Given some serializable type <tt>T</tt> you can define
--   
--   <pre>
--   sdictT :: SerializableDict T
--   sdictT = SerializableDict
--   </pre>
--   
--   and then have
--   
--   <pre>
--   $(mkStatic 'sdictT) :: Static (SerializableDict T)
--   </pre>
--   
--   However, since these dictionaries are so frequently required Cloud
--   Haskell provides special support for them. When you call
--   <a>remotable</a> on a <i>monomorphic</i> function <tt>f :: T1 -&gt;
--   T2</tt>
--   
--   <pre>
--   remotable ['f]
--   </pre>
--   
--   then a serialization dictionary is automatically created for you,
--   which you can access with
--   
--   <pre>
--   $(functionSDict 'f) :: Static (SerializableDict T1)
--   </pre>
--   
--   In addition, if <tt>f :: T1 -&gt; Process T2</tt>, then a second
--   dictionary is created
--   
--   <pre>
--   $(functionTDict 'f) :: Static (SerializableDict T2)
--   </pre>
--   
--   <ul>
--   <li><i>Closures</i></li>
--   </ul>
--   
--   Suppose you have a process
--   
--   <pre>
--   isPrime :: Integer -&gt; Process Bool 
--   </pre>
--   
--   Then
--   
--   <pre>
--   $(mkClosure 'isPrime) :: Integer -&gt; Closure (Process Bool)
--   </pre>
--   
--   which you can then <tt>call</tt>, for example, to have a remote node
--   check if a number is prime.
--   
--   In general, if you have a <i>monomorphic</i> function
--   
--   <pre>
--   f :: T1 -&gt; T2
--   </pre>
--   
--   then
--   
--   <pre>
--   $(mkClosure 'f) :: T1 -&gt; Closure T2
--   </pre>
--   
--   provided that <tt>T1</tt> is serializable (*) (remember to pass
--   <tt>f</tt> to <a>remotable</a>).
--   
--   (You can also create closures manually--see the documentation of
--   <a>Control.Distributed.Static</a> for examples.)
--   
--   <ul>
--   <li><i>Example</i></li>
--   </ul>
--   
--   Here is a small self-contained example that uses closures and
--   serialization dictionaries. It makes use of the
--   Control.Distributed.Process.SimpleLocalnet Cloud Haskell backend.
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   import System.Environment (getArgs)
--   import Control.Distributed.Process
--   import Control.Distributed.Process.Closure
--   import Control.Distributed.Process.Backend.SimpleLocalnet
--   import Control.Distributed.Process.Node (initRemoteTable)
--   
--   isPrime :: Integer -&gt; Process Bool
--   isPrime n = return . (n `elem`) . takeWhile (&lt;= n) . sieve $ [2..]
--     where
--       sieve :: [Integer] -&gt; [Integer]
--       sieve (p : xs) = p : sieve [x | x &lt;- xs, x `mod` p &gt; 0]
--   
--   remotable ['isPrime]
--   
--   master :: [NodeId] -&gt; Process ()
--   master [] = liftIO $ putStrLn "no slaves"
--   master (slave:_) = do
--     isPrime79 &lt;- call $(functionTDict 'isPrime) slave ($(mkClosure 'isPrime) (79 :: Integer))
--     liftIO $ print isPrime79 
--   
--   main :: IO ()
--   main = do
--     args &lt;- getArgs
--     case args of
--       ["master", host, port] -&gt; do
--         backend &lt;- initializeBackend host port rtable 
--         startMaster backend master 
--       ["slave", host, port] -&gt; do
--         backend &lt;- initializeBackend host port rtable 
--         startSlave backend
--     where
--       rtable :: RemoteTable
--       rtable = __remoteTable initRemoteTable 
--   </pre>
--   
--   <ul>
--   <li><i>Notes</i></li>
--   </ul>
--   
--   (*) If <tt>T1</tt> is not serializable you will get a type error in
--   the generated code. Unfortunately, the Template Haskell infrastructure
--   cannot check a priori if <tt>T1</tt> is serializable or not due to a
--   bug in the Template Haskell libraries
--   (<a>http://hackage.haskell.org/trac/ghc/ticket/7066</a>)
--   
--   (**) Even though <tt>call</tt> is passed an explicit serialization
--   dictionary, we still need the <tt>Serializable</tt> constraint because
--   <tt>Static</tt> is not the <i>true</i> static. If it was, we could
--   <tt>unstatic</tt> the dictionary and pattern match on it to bring the
--   <tt>Typeable</tt> instance into scope, but unless proper
--   <tt>static</tt> support is added to ghc we need both the type class
--   argument and the explicit dictionary.
module Control.Distributed.Process.Closure

-- | Create the closure, decoder, and metadata definitions for the given
--   list of functions
remotable :: [Name] -> Q [Dec]

-- | Construct a static value.
--   
--   If <tt>f : forall a1 .. an. T</tt> then <tt>$(mkStatic 'f) :: forall
--   a1 .. an. Static T</tt>. Be sure to pass <tt>f</tt> to
--   <a>remotable</a>.
mkStatic :: Name -> Q Exp
mkClosure :: Name -> Q Exp

-- | If <tt>f : T1 -&gt; T2</tt> is a monomorphic function then
--   <tt>$(functionSDict 'f) :: Static (SerializableDict T1)</tt>.
--   
--   Be sure to pass <tt>f</tt> to <a>remotable</a>.
functionSDict :: Name -> Q Exp

-- | If <tt>f : T1 -&gt; Process T2</tt> is a monomorphic function then
--   <tt>$(functionTDict 'f) :: Static (SerializableDict T2)</tt>.
--   
--   Be sure to pass <tt>f</tt> to <a>remotable</a>.
functionTDict :: Name -> Q Exp

-- | Reification of <a>Serializable</a> (see
--   <a>Control.Distributed.Process.Closure</a>)
data SerializableDict a
SerializableDict :: SerializableDict a

-- | Static decoder, given a static serialization dictionary.
--   
--   See module documentation of <a>Control.Distributed.Process.Closure</a>
--   for an example.
staticDecode :: Typeable a => Static (SerializableDict a) -> Static (ByteString -> a)

-- | Serialization dictionary for '()'
sdictUnit :: Static (SerializableDict ())

-- | Serialization dictionary for <a>ProcessId</a>
sdictProcessId :: Static (SerializableDict ProcessId)

-- | Serialization dictionary for <a>SendPort</a>
sdictSendPort :: Typeable a => Static (SerializableDict a) -> Static (SerializableDict (SendPort a))

-- | <tt>CP a b</tt> is a process with input of type <tt>a</tt> and output
--   of type <tt>b</tt>
type CP a b = Closure (a -> Process b)

-- | <a>CP</a> version of <a>id</a>
idCP :: Typeable a => CP a a

-- | <a>CP</a> version of (<a>***</a>)
splitCP :: (Typeable a, Typeable b, Typeable c, Typeable d) => CP a c -> CP b d -> CP (a, b) (c, d)

-- | <a>CP</a> version of <a>return</a>
returnCP :: Serializable a => Static (SerializableDict a) -> a -> Closure (Process a)

-- | (Not quite the) <a>CP</a> version of (<a>&gt;&gt;=</a>)
bindCP :: (Typeable a, Typeable b) => Closure (Process a) -> CP a b -> Closure (Process b)

-- | <a>CP</a> version of (<a>&gt;&gt;</a>)
seqCP :: (Typeable a, Typeable b) => Closure (Process a) -> Closure (Process b) -> Closure (Process b)

-- | <a>CP</a> version of <a>link</a>
cpLink :: ProcessId -> Closure (Process ())

-- | <a>CP</a> version of <a>unlink</a>
cpUnlink :: ProcessId -> Closure (Process ())

-- | <a>CP</a> version of <a>send</a>
cpSend :: Typeable a => Static (SerializableDict a) -> ProcessId -> CP a ()

-- | <a>CP</a> version of <a>expect</a>
cpExpect :: Typeable a => Static (SerializableDict a) -> Closure (Process a)

-- | <a>CP</a> version of <a>newChan</a>
cpNewChan :: Typeable a => Static (SerializableDict a) -> Closure (Process (SendPort a, ReceivePort a))


-- | Local nodes
module Control.Distributed.Process.Node

-- | Local nodes
data LocalNode

-- | Initialize a new local node.
newLocalNode :: Transport -> RemoteTable -> IO LocalNode

-- | Force-close a local node
--   
--   TODO: for now we just close the associated endpoint
closeLocalNode :: LocalNode -> IO ()

-- | Spawn a new process on a local node
forkProcess :: LocalNode -> Process () -> IO ProcessId

-- | Run a process on a local node and wait for it to finish
runProcess :: LocalNode -> Process () -> IO ()
initRemoteTable :: RemoteTable

-- | <a>NodeId</a> of the node
localNodeId :: LocalNode -> NodeId
instance Functor NC
instance Monad NC
instance MonadIO NC
instance MonadState NCState NC
instance MonadReader LocalNode NC


-- | <ul>
--   <li><i>Cloud Haskell</i></li>
--   </ul>
--   
--   This is an implementation of Cloud Haskell, as described in <i>Towards
--   Haskell in the Cloud</i> by Jeff Epstein, Andrew Black, and Simon
--   Peyton Jones
--   (<a>http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/</a>),
--   although some of the details are different. The precise message
--   passing semantics are based on <i>A unified semantics for future
--   Erlang</i> by Hans Svensson, Lars-Åke Fredlund and Clara Benac Earle.
module Control.Distributed.Process

-- | Process identifier
data ProcessId

-- | Node identifier
data NodeId

-- | The Cloud Haskell <a>Process</a> type
data Process a

-- | A send port is identified by a SendPortId.
--   
--   You cannot send directly to a SendPortId; instead, use
--   <tt>newChan</tt> to create a SendPort.
data SendPortId

-- | The ID of the node the process is running on
processNodeId :: ProcessId -> NodeId

-- | The ID of the process that will receive messages sent on this port
sendPortProcessId :: SendPortId -> ProcessId

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a

-- | Send a message
send :: Serializable a => ProcessId -> a -> Process ()

-- | Wait for a message of a specific type
expect :: Serializable a => Process a

-- | The receive end of a typed channel (not serializable)
data ReceivePort a

-- | The send send of a typed channel (serializable)
data SendPort a

-- | The (unique) ID of this send port
sendPortId :: SendPort a -> SendPortId

-- | Create a new typed channel
newChan :: Serializable a => Process (SendPort a, ReceivePort a)

-- | Send a message on a typed channel
sendChan :: Serializable a => SendPort a -> a -> Process ()

-- | Wait for a message on a typed channel
receiveChan :: Serializable a => ReceivePort a -> Process a

-- | Merge a list of typed channels.
--   
--   The result port is left-biased: if there are messages available on
--   more than one port, the first available message is returned.
mergePortsBiased :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

-- | Like <a>mergePortsBiased</a>, but with a round-robin scheduler (rather
--   than left-biased)
mergePortsRR :: Serializable a => [ReceivePort a] -> Process (ReceivePort a)

-- | Opaque type used in <a>receiveWait</a> and <a>receiveTimeout</a>
data Match b

-- | Test the matches in order against each message in the queue
receiveWait :: [Match b] -> Process b

-- | Like <a>receiveWait</a> but with a timeout.
--   
--   If the timeout is zero do a non-blocking check for matching messages.
--   A non-zero timeout is applied only when waiting for incoming messages
--   (that is, <i>after</i> we have checked the messages that are already
--   in the mailbox).
receiveTimeout :: Int -> [Match b] -> Process (Maybe b)

-- | Match against any message of the right type
match :: Serializable a => (a -> Process b) -> Match b

-- | Match against any message of the right type that satisfies a predicate
matchIf :: Serializable a => (a -> Bool) -> (a -> Process b) -> Match b

-- | Remove any message from the queue
matchUnknown :: Process b -> Match b

-- | Spawn a process
--   
--   For more information about <a>Closure</a>, see
--   <a>Control.Distributed.Process.Closure</a>.
--   
--   See also <a>call</a>.
spawn :: NodeId -> Closure (Process ()) -> Process ProcessId

-- | Run a process remotely and wait for it to reply
--   
--   We monitor the remote process: if it dies before it can send a reply,
--   we die too.
--   
--   For more information about <a>Static</a>, <a>SerializableDict</a>, and
--   <a>Closure</a>, see <a>Control.Distributed.Process.Closure</a>.
--   
--   See also <a>spawn</a>.
call :: Serializable a => Static (SerializableDict a) -> NodeId -> Closure (Process a) -> Process a

-- | Terminate (throws a ProcessTerminationException)
terminate :: Process a

-- | Thrown by <a>terminate</a>
data ProcessTerminationException
ProcessTerminationException :: ProcessTerminationException

-- | <a>SpawnRef</a> are used to return pids of spawned processes
data SpawnRef

-- | Our own process ID
getSelfPid :: Process ProcessId

-- | Get the node ID of our local node
getSelfNode :: Process NodeId

-- | Link to a remote process (asynchronous)
--   
--   Note that <a>link</a> provides unidirectional linking (see
--   <tt>spawnSupervised</tt>). Linking makes no distinction between normal
--   and abnormal termination of the remote process.
link :: ProcessId -> Process ()

-- | Link to a node
linkNode :: NodeId -> Process ()

-- | Link to a channel (send port)
linkPort :: SendPort a -> Process ()

-- | Remove a link (synchronous)
unlink :: ProcessId -> Process ()

-- | Remove a node link (synchronous)
unlinkNode :: NodeId -> Process ()

-- | Remove a channel (send port) link (synchronous)
unlinkPort :: SendPort a -> Process ()

-- | Monitor another process (asynchronous)
monitor :: ProcessId -> Process MonitorRef

-- | Monitor a node
monitorNode :: NodeId -> Process MonitorRef

-- | Monitor a typed channel
monitorPort :: Serializable a => SendPort a -> Process MonitorRef

-- | Remove a monitor (synchronous)
unmonitor :: MonitorRef -> Process ()

-- | Exceptions thrown when a linked process dies
data ProcessLinkException
ProcessLinkException :: ProcessId -> DiedReason -> ProcessLinkException

-- | Exception thrown when a linked node dies
data NodeLinkException
NodeLinkException :: NodeId -> DiedReason -> NodeLinkException

-- | Exception thrown when a linked channel (port) dies
data PortLinkException
PortLinkException :: SendPortId -> DiedReason -> PortLinkException

-- | MonitorRef is opaque for regular Cloud Haskell processes
data MonitorRef

-- | Message sent by process monitors
data ProcessMonitorNotification
ProcessMonitorNotification :: MonitorRef -> ProcessId -> DiedReason -> ProcessMonitorNotification

-- | Message sent by node monitors
data NodeMonitorNotification
NodeMonitorNotification :: MonitorRef -> NodeId -> DiedReason -> NodeMonitorNotification

-- | Message sent by channel (port) monitors
data PortMonitorNotification
PortMonitorNotification :: MonitorRef -> SendPortId -> DiedReason -> PortMonitorNotification

-- | Why did a process die?
data DiedReason

-- | Normal termination
DiedNormal :: DiedReason

-- | The process exited with an exception (provided as <a>String</a>
--   because <a>Exception</a> does not implement <a>Binary</a>)
DiedException :: String -> DiedReason

-- | We got disconnected from the process node
DiedDisconnect :: DiedReason

-- | The process node died
DiedNodeDown :: DiedReason

-- | Invalid (process<i>node</i>channel) identifier
DiedUnknownId :: DiedReason

-- | A closure is a static value and an encoded environment
data Closure a :: * -> *
Closure :: Static (ByteString -> a) -> ByteString -> Closure a

-- | A static value. Static is opaque; see <a>staticLabel</a> and
--   <a>staticApply</a>.
data Static a :: * -> *

-- | Deserialize a closure
unClosure :: Typeable a => Closure a -> Process a

-- | Runtime dictionary for <a>unstatic</a> lookups
data RemoteTable :: *

-- | Log a string
--   
--   <tt>say message</tt> sends a message (time, pid of the current
--   process, message) to the process registered as <tt>logger</tt>. By
--   default, this process simply sends the string to <tt>stderr</tt>.
--   Individual Cloud Haskell backends might replace this with a different
--   logger process, however.
say :: String -> Process ()

-- | Register a process with the local registry (asynchronous).
--   
--   The process to be registered does not have to be local itself.
register :: String -> ProcessId -> Process ()

-- | Remove a process from the local registry (asynchronous).
unregister :: String -> Process ()

-- | Query the local process registry (synchronous).
whereis :: String -> Process (Maybe ProcessId)

-- | Named send to a process in the local registry (asynchronous)
nsend :: Serializable a => String -> a -> Process ()

-- | Register a process with a remote registry (asynchronous).
--   
--   The process to be registered does not have to live on the same remote
--   node.
registerRemote :: NodeId -> String -> ProcessId -> Process ()

-- | Remove a process from a remote registry (asynchronous).
unregisterRemote :: NodeId -> String -> Process ()

-- | Query a remote process registry (synchronous)
whereisRemote :: NodeId -> String -> Process (Maybe ProcessId)

-- | Query a remote process registry (asynchronous)
--   
--   Reply will come in the form of a <a>WhereIsReply</a> message
whereisRemoteAsync :: NodeId -> String -> Process ()

-- | Named send to a process in a remote registry (asynchronous)
nsendRemote :: Serializable a => NodeId -> String -> a -> Process ()

-- | (Asynchronous) reply from <tt>whereis</tt>
data WhereIsReply
WhereIsReply :: String -> (Maybe ProcessId) -> WhereIsReply

-- | Lift <a>catch</a>
catch :: Exception e => Process a -> (e -> Process a) -> Process a

-- | Lift <a>mask</a>
mask :: ((forall a. Process a -> Process a) -> Process b) -> Process b

-- | Lift <a>onException</a>
onException :: Process a -> Process b -> Process a

-- | Lift <a>bracket</a>
bracket :: Process a -> (a -> Process b) -> (a -> Process c) -> Process c

-- | Lift <a>bracket_</a>
bracket_ :: Process a -> Process b -> Process c -> Process c

-- | Lift <a>finally</a>
finally :: Process a -> Process b -> Process a

-- | Like <a>expect</a> but with a timeout
expectTimeout :: Serializable a => Int -> Process (Maybe a)

-- | Asynchronous version of <tt>spawn</tt>
--   
--   (<tt>spawn</tt> is defined in terms of <a>spawnAsync</a> and
--   <a>expect</a>)
spawnAsync :: NodeId -> Closure (Process ()) -> Process SpawnRef

-- | Spawn a child process, have the child link to the parent and the
--   parent monitor the child
spawnSupervised :: NodeId -> Closure (Process ()) -> Process (ProcessId, MonitorRef)

-- | Spawn a process and link to it
--   
--   Note that this is just the sequential composition of <a>spawn</a> and
--   <a>link</a>. (The <a>Unified</a> semantics that underlies Cloud
--   Haskell does not even support a synchronous link operation)
spawnLink :: NodeId -> Closure (Process ()) -> Process ProcessId

-- | Like <a>spawnLink</a>, but monitor the spawned process
spawnMonitor :: NodeId -> Closure (Process ()) -> Process (ProcessId, MonitorRef)

-- | Spawn a new process, supplying it with a new <a>ReceivePort</a> and
--   return the corresponding <a>SendPort</a>.
spawnChannel :: Typeable a => Static (SerializableDict a) -> NodeId -> Closure (ReceivePort a -> Process ()) -> Process (SendPort a)

-- | (Asynchronius) reply from <tt>spawn</tt>
data DidSpawn
DidSpawn :: SpawnRef -> ProcessId -> DidSpawn

-- | Spawn a process on the local node
spawnLocal :: Process () -> Process ProcessId

-- | Create a new typed channel, spawn a process on the local node, passing
--   it the receive port, and return the send port
spawnChannelLocal :: Serializable a => (ReceivePort a -> Process ()) -> Process (SendPort a)