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 :: CallSite -> Name -> Method -> Message -> IO Message

Call a method with the provided arguments on the recipient with the given name.

the caller will wait until a matching response is received.

callWithTimeout :: CallSite -> Name -> Method -> Int -> Message -> IO (Maybe Message)

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 :: CallSite -> [Name] -> Method -> Message -> IO (Map Name Message)

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 :: CallSite -> [Name] -> Method -> Int -> Message -> IO (Map Name (Maybe Message))

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.

hear :: Endpoint -> Name -> Method -> IO (Message, Reply Message)

Wait for a single incoming request to invoke the indicated Method on the specified Endpoint. Return both the method arguments and a Reply function useful for sending the reply. A good pattern for using hear will pattern match the result to a tuple of the form (args,reply), then use the args as needed to compute a result, and then finally send the result back to the client by simply passing the result to reply: reply result.

The invoker of hear must supply the Name they have bound to the Endpoint, as this helps the original requestor of the RPC differentiate responses when the RPC was a group call.

hearTimeout :: Endpoint -> Name -> Method -> Int -> IO (Maybe (Message, Reply Message))

Same as hear, except return Nothing if no request received within the specified timeout (measured in microseconds), or return a Just instance containing both the method arguments and a Reply function useful for sending the reply.

type Reply b = b -> IO ()

A Reply is a one-shot function for sending a response to an incoming request.

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 :: Endpoint -> Name -> Method -> (Message -> IO Message) -> 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.

data Request

Constructors

Request

Fields

requestId :: RequestId

requestCaller :: Name

requestMethod :: Method

requestArgs :: Message

Instances

Serialize Request

data Response

Constructors

Response

Fields

responseId :: RequestId

responseFrom :: Name

responseValue :: Message

Instances

Serialize Response