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


-- | A proven synchronization server for high performance computing.
--   
@package Parry
@version 0.1.0.0


-- | This module contains all data types exchanged between the client and
--   the server, except for the initial "<tt>Hello</tt>" message, and is
--   mostly exposed for full disclosure of the protocol's proof.
module Parry.Protocol

-- | The type of messages sent by the client, exposed here for full
--   disclosure of the protocol's proof.
data ClientMessage j
GetJob :: Integer -> PublicKey -> ClientMessage j
JobDone :: Integer -> [j] -> j -> ClientMessage j
clientId :: ClientMessage j -> Integer
jobResults :: ClientMessage j -> [j]
currentJob :: ClientMessage j -> j
NewJobs :: Integer -> [j] -> j -> j -> [j] -> ClientMessage j
clientId :: ClientMessage j -> Integer
jobResults :: ClientMessage j -> [j]
currentJob :: ClientMessage j -> j
nextJob :: ClientMessage j -> j
newJobs :: ClientMessage j -> [j]
Alive :: Integer -> ClientMessage j

-- | The type of messages sent by the server, exposed here for full
--   disclosure of the protocol's proof.
data ServerMessage j
Job :: Bool -> j -> ServerMessage j
Finished :: ServerMessage j
Ack :: ServerMessage j
Die :: ServerMessage j
instance Generic (ClientMessage j)
instance Show j => Show (ClientMessage j)
instance Generic (ServerMessage j)
instance Show j => Show (ServerMessage j)
instance Datatype D1ClientMessage
instance Constructor C1_0ClientMessage
instance Constructor C1_1ClientMessage
instance Constructor C1_2ClientMessage
instance Constructor C1_3ClientMessage
instance Selector S1_1_0ClientMessage
instance Selector S1_1_1ClientMessage
instance Selector S1_1_2ClientMessage
instance Selector S1_2_0ClientMessage
instance Selector S1_2_1ClientMessage
instance Selector S1_2_2ClientMessage
instance Selector S1_2_3ClientMessage
instance Selector S1_2_4ClientMessage
instance Datatype D1ServerMessage
instance Constructor C1_0ServerMessage
instance Constructor C1_1ServerMessage
instance Constructor C1_2ServerMessage
instance Constructor C1_3ServerMessage
instance Binary j => Binary (ServerMessage j)
instance Binary j => Binary (ClientMessage j)


-- | Tool to build clients for Parry.
module Parry.Client

-- | For a job to be usable by Parry's clients, it must be a member of this
--   class.
class Client j
isResult :: Client j => j -> Bool

-- | <tt><a>client</a> config work</tt> calls its argument function
--   <tt>work</tt> on a boolean <tt>s</tt> (if the server asked to share
--   jobs) and the actual job <tt>j</tt> that must be done. <tt>work</tt>
--   must return a list of resulting jobs, that may include results (see
--   <a>Client</a>).
--   
--   Workers asked to share their input job should share it as early as
--   possible: this usually means that the job already got killed in a
--   previous attempt, probably because of its length.
client :: (Binary j, Client j) => Config -> (Bool -> ([j] -> [j] -> IO ()) -> j -> IO [j]) -> IO ()

-- | Client configuration
data Config
Config :: String -> PortID -> PrivateKey -> PublicKey -> Config

-- | The server's host name (either a DNS name or an IP address).
server :: Config -> String

-- | The port number (for instance <tt><a>PortNumber</a> 5129</tt>).
port :: Config -> PortID

-- | The private key to sign messages.
privateKey :: Config -> PrivateKey

-- | The public key, that the server must know of before the clients
--   connect.
publicKey :: Config -> PublicKey

-- | A default configuration, matching the server's <a>defaultConfig</a>.
--   Note that, like in the server, you must provide your own private key
--   for signing the protocol messages. See <a>defaultConfig</a> for an
--   example method to generate these keys.
defaultConfig :: PrivateKey -> PublicKey -> Config


-- | Tools to build synchronization servers. For instance, to write a
--   simple server with just a web interface on port 8000, you would use:
--   
--   <pre>
--   import Control.Concurrent
--   import Parry.Server
--   import Parry.WebUI
--   
--   main::IO ()
--   main=do
--     state&lt;-initState initial
--     _&lt;-forkIO $ webUI 8000 state
--     server (defaultConfig public) state
--   </pre>
module Parry.Server

-- | The class of jobs and job results that Parry can deal with. For
--   efficiency and to keep types simple, jobs and results are stored in a
--   single type.
class Exhaustive j
depth :: Exhaustive j => j -> Int
killed :: Exhaustive j => j -> Int
kill :: Exhaustive j => j -> j

-- | The class of results, and how to combine them in the server state.
class Result j r
addResult :: Result j r => HostName -> r -> j -> r

-- | Creates a valid server state from an initial job.
initState :: (Exhaustive j, Ord j, Result j r) => [j] -> r -> IO (MVar (State j r))

-- | Reads initial state from a file, or calls <a>initState</a> if the file
--   does not exist.
stateFromFile :: (Binary r, Binary j, Exhaustive j, Result j r, Ord j) => FilePath -> [j] -> r -> IO (MVar (State j r))

-- | Saves state to the given file with the given periodicity, in
--   microseconds. This function does not return, so calling it inside a
--   <a>forkIO</a> is probably the best thing to do.
saveThread :: (Binary r, Binary j) => FilePath -> Int -> MVar (State j r) -> IO ()

-- | This type is exposed mostly for writing alternative user interfaces.
--   Other operations must be done using the functions in this module, or
--   the correction of the protocol can be lost.
data State j r
State :: Set (Int, j) -> Map Integer (HostName, PublicKey, j, Double, Double) -> Set Integer -> r -> Integer -> Int -> Integer -> [PublicKey] -> State j r

-- | Available jobs
jobs :: State j r -> Set (Int, j)

-- | Map from the machine id to its hostname, its current job, its starting
--   time, the last time we heard from it.
ongoing :: State j r -> Map Integer (HostName, PublicKey, j, Double, Double)

-- | Set of unemployed machines
unemployed :: State j r -> Set Integer

-- | The results.
results :: State j r -> r

-- | The smallest available machine id. In a run of the server, it is
--   guaranteed that are never assigned the same.
newId :: State j r -> Integer

-- | Total number of jobs killed from the beginning (for benchmarking
--   purposes).
killings :: State j r -> Int

-- | Number of jobs finished (for benchmarking purposes).
solved :: State j r -> Integer

-- | The list of authorized RSA public keys.
authorizedKeys :: State j r -> [PublicKey]

-- | Server configuration
data Config
Config :: PortID -> Int -> FilePath -> Config

-- | The network port the synchronization server will listen on.
port :: Config -> PortID

-- | The maximal number of simultaneous threads that can be launched.
maxThreads :: Config -> Int

-- | Log file
logFile :: Config -> FilePath

-- | Default server configuration, matching the client. Note that you must
--   provide your own public key for signing the messages.
defaultConfig :: Config

-- | Starts the synchronization server.
server :: (Ord j, Binary j, Exhaustive j, Result j r) => Config -> MVar (State j r) -> IO ()
instance (Show j, Show r) => Show (State j r)
instance (Ord j, Read j, Read r) => Read (State j r)
instance Generic (State j r)
instance Datatype D1State
instance Constructor C1_0State
instance Selector S1_0_0State
instance Selector S1_0_1State
instance Selector S1_0_2State
instance Selector S1_0_3State
instance Selector S1_0_4State
instance Selector S1_0_5State
instance Selector S1_0_6State
instance Selector S1_0_7State
instance (Binary j, Binary r) => Binary (State j r)


module Parry.WebUI

-- | Starts the default web server.
webUI :: (Exhaustive j, Html j, Html r) => PortNumber -> MVar (State j r) -> IO ()
class Html a
toHtml :: Html a => a -> Builder