Network.RPC

An implementation of synchronous remote procedure calls (RPC) on top of Endpoints.

Applications exporting services for use by other applications via RPC call handle to start listening for incoming RPC requests for a specific Method. If multiple functions or Methods are exported, then separate calls to handle are necessary, one for each exported Method. Each call to handle produces a HandleSite which may be used to terminate future handling of RPCs for that specific method by calling hangup on the returned HandleSite.

Applications wishing to make RPCs to other applications or services do so by first constructing a CallSite, and then calling specific methods on the target handler through that CallSite.

Both single and multiple target RPCs are available, as are variants that either wait indefinitely or at most for a defined timeout.

Documentation

type Method = String

newCallSite :: Endpoint -> Name -> CallSite

Create a new CallSite using the indicated Endpoint for sending RPCs and using the specified Name for receiving responses.

data CallSite

A call site is a location for making RPCs: it includes an endpoint and a name by which recipients can return the call

call :: (Serialize a, Serialize b) => CallSite -> Name -> Method -> a -> IO b

Call a method with the provided arguments on the recipient with the given name. A request will be made through the CallSite's Endpoint, and then the caller will wait until a matching response is received.

callWithTimeout :: (Serialize a, Serialize b) => CallSite -> Name -> Method -> Int -> a -> IO (Maybe b)

Call a method with the provided arguments on the recipient with the given name. A request will be made through the CallSite's Endpoint, and then the caller will wait until a matching response is received. If a response is received within the provided timeout (measured in microseconds), then return the value wrapped in Just; otherwise, if the timeout expires before the call returns, then return 'Nothing.

gcall :: (Serialize a, Serialize b) => CallSite -> [Name] -> Method -> a -> IO (Map Name b)

Group call or RPC: call a method with the provided arguments on all the recipients with the given names. A request will be made through the CallSite's Endpoint, and then the caller will wait until all matching responses are received.

gcallWithTimeout :: (Serialize a, Serialize b) => CallSite -> [Name] -> Method -> Int -> a -> IO (Map Name (Maybe b))

Group call or RPC but with a timeout: call a method with the provided arguments on all the recipients with the given names. A request will be made through the CallSite's Endpoint, and then the caller will wait until all matching responses are received or the timeout occurs. The returned Map has a key for every Name that was a target of the call, and the value of that key will be Nothing if no response was received before the timeout, or Just value if a response was received.

data HandleSite

A HandleSite is a just reference to the actual handler of a specific method. Mostly for invoking hangup on the handler, once it is no longer needed.

handle :: (Serialize a, Serialize b) => Endpoint -> Name -> Method -> (a -> IO b) -> IO HandleSite

Handle all RPCs to invoke the indicated Method on the specified Endpoint, until hangup is called on the returned HandleSite.

hangup :: HandleSite -> IO ()

Stop handling incoming RPCs for the indicated HandleSite.