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


-- | Simple zero-configuration backend for Cloud Haskell
--   
--   Simple backend based on the TCP transport which offers node discovery
--   based on UDP multicast. This is a zero-configuration backend designed
--   to get you going with Cloud Haskell quickly without imposing any
--   structure on your application.
@package distributed-process-simplelocalnet
@version 0.3.1


-- | Multicast utilities
module Control.Distributed.Process.Backend.SimpleLocalnet.Internal.Multicast

-- | Given a hostname and a port number, initialize the multicast system.
--   
--   Note: it is important that you never send messages larger than the
--   maximum message size; if you do, all subsequent communication will
--   probably fail.
--   
--   Returns a reader and a writer.
--   
--   NOTE: By rights the two functions should be "locally" polymorphic in
--   <tt>a</tt>, but this requires impredicative types.
initMulticast :: forall a. Binary a => HostName -> PortNumber -> Int -> IO (IO (a, SockAddr), a -> IO ())


-- | Simple backend based on the TCP transport which offers node discovery
--   based on UDP multicast. This is a zero-configuration backend designed
--   to get you going with Cloud Haskell quickly without imposing any
--   structure on your application.
--   
--   To simplify getting started we provide special support for
--   <i>master</i> and <i>slave</i> nodes (see <a>startSlave</a> and
--   <a>startMaster</a>). Use of these functions is completely optional;
--   you can use the local backend without making use of the predefined
--   master and slave nodes.
--   
--   <ul>
--   <li><i>Minimal example</i></li>
--   </ul>
--   
--   <pre>
--   import System.Environment (getArgs)
--   import Control.Distributed.Process
--   import Control.Distributed.Process.Node (initRemoteTable)
--   import Control.Distributed.Process.Backend.SimpleLocalnet
--   
--   master :: Backend -&gt; [NodeId] -&gt; Process ()
--   master backend slaves = do
--     -- Do something interesting with the slaves
--     liftIO . putStrLn $ "Slaves: " ++ show slaves
--     -- Terminate the slaves when the master terminates (this is optional)
--     terminateAllSlaves backend
--   
--   main :: IO ()
--   main = do
--     args &lt;- getArgs
--   
--     case args of
--       ["master", host, port] -&gt; do
--         backend &lt;- initializeBackend host port initRemoteTable
--         startMaster backend (master backend)
--       ["slave", host, port] -&gt; do
--         backend &lt;- initializeBackend host port initRemoteTable
--         startSlave backend
--   </pre>
--   
--   <ul>
--   <li><i>Compiling and Running</i></li>
--   </ul>
--   
--   Save to <tt>example.hs</tt> and compile using
--   
--   <pre>
--   ghc -threaded example.hs
--   </pre>
--   
--   Fire up some slave nodes (for the example, we run them on a single
--   machine):
--   
--   <pre>
--   ./example slave localhost 8080 &amp;
--   ./example slave localhost 8081 &amp;
--   ./example slave localhost 8082 &amp;
--   ./example slave localhost 8083 &amp;
--   </pre>
--   
--   And start the master node:
--   
--   <pre>
--   ./example master localhost 8084
--   </pre>
--   
--   which should then output:
--   
--   <pre>
--   Slaves: [nid://localhost:8083:0,nid://localhost:8082:0,nid://localhost:8081:0,nid://localhost:8080:0]
--   </pre>
--   
--   at which point the slaves should exit.
--   
--   To run the example on multiple machines, you could run
--   
--   <pre>
--   ./example slave 198.51.100.1 8080 &amp;
--   ./example slave 198.51.100.2 8080 &amp;
--   ./example slave 198.51.100.3 8080 &amp;
--   ./example slave 198.51.100.4 8080 &amp;
--   </pre>
--   
--   on four different machines (with IP addresses 198.51.100.1..4), and
--   run the master on a fifth node (or on any of the four machines that
--   run the slave nodes).
--   
--   It is important that every node has a unique (hostname, port number)
--   pair, and that the hostname you use to initialize the node can be
--   resolved by peer nodes. In other words, if you start a node and pass
--   hostname <tt>localhost</tt> then peer nodes won't be able to reach it
--   because <tt>localhost</tt> will resolve to a different IP address for
--   them.
--   
--   <ul>
--   <li><i>Troubleshooting</i></li>
--   </ul>
--   
--   If you try the above example and the master process cannot find any
--   slaves, then it might be that your firewall settings do not allow for
--   UDP multicast (in particular, the default iptables on some Linux
--   distributions might not allow it).
module Control.Distributed.Process.Backend.SimpleLocalnet

-- | Local backend
data Backend
Backend :: IO LocalNode -> (Int -> IO [NodeId]) -> ([ProcessId] -> Process ()) -> Backend

-- | Create a new local node
[newLocalNode] :: Backend -> IO LocalNode

-- | <tt>findPeers t</tt> broadcasts a <i>who's there?</i> message on the
--   local network, waits <tt>t</tt> microseconds, and then collects and
--   returns the answers. You can use this to dynamically discover peer
--   nodes.
[findPeers] :: Backend -> Int -> IO [NodeId]

-- | Make sure that all log messages are printed by the logger on the
--   current node
[redirectLogsHere] :: Backend -> [ProcessId] -> Process ()

-- | Initialize the backend
initializeBackend :: HostName -> ServiceName -> RemoteTable -> IO Backend

-- | Calling <tt>slave</tt> sets up a new local node and then waits. You
--   start processes on the slave by calling <tt>spawn</tt> from other
--   nodes.
--   
--   This function does not return. The only way to exit the slave is to
--   CTRL-C the process or call terminateSlave from another node.
startSlave :: Backend -> IO ()

-- | Terminate the slave at the given node ID
terminateSlave :: NodeId -> Process ()

-- | Find slave nodes
findSlaves :: Backend -> Process [ProcessId]

-- | Terminate all slaves
terminateAllSlaves :: Backend -> Process ()

-- | <a>startMaster</a> finds all slaves <i>currently</i> available on the
--   local network, redirects all log messages to itself, and then calls
--   the specified process, passing the list of slaves nodes.
--   
--   Terminates when the specified process terminates. If you want to
--   terminate the slaves when the master terminates, you should manually
--   call <a>terminateAllSlaves</a>.
--   
--   If you start more slave nodes after having started the master node,
--   you can discover them with later calls to <a>findSlaves</a>, but be
--   aware that you will need to call <tt>redirectLogHere</tt> to redirect
--   their logs to the master node.
--   
--   Note that you can use functionality of <a>SimpleLocalnet</a> directly
--   (through <a>Backend</a>), instead of using
--   <a>startMaster</a><i><a>startSlave</a>, if the master</i>slave
--   distinction does not suit your application.
startMaster :: Backend -> ([NodeId] -> Process ()) -> IO ()
instance GHC.Show.Show Control.Distributed.Process.Backend.SimpleLocalnet.SlaveControllerMsg
instance GHC.Show.Show Control.Distributed.Process.Backend.SimpleLocalnet.RedirectLogsReply
instance Data.Binary.Class.Binary Control.Distributed.Process.Backend.SimpleLocalnet.RedirectLogsReply
instance Data.Binary.Class.Binary Control.Distributed.Process.Backend.SimpleLocalnet.SlaveControllerMsg
instance Data.Binary.Class.Binary Control.Distributed.Process.Backend.SimpleLocalnet.PeerDiscoveryMsg