courier-0.1.1.1: A message-passing library for simplifying network applications

Copyright(c) Phil Hargett 2014
LicenseMIT (see LICENSE file)
Maintainerphil@haphazardhouse.net
Stabilityexperimental
Portabilitynon-portable (requires STM)
Safe HaskellNone
LanguageHaskell98

Network.RPC

Description

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.

Synopsis

Documentation

type Method = String Source

An identifier for what method to invoke on the receiving Endpoint. If hear has been invoked on the Endpoint with a matching identifier, then calls will be delivered to that invocation of hear.

newCallSite :: Endpoint -> Name -> CallSite Source

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

data CallSite Source

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 Source

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) Source

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) Source

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)) Source

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.

anyCall :: CallSite -> [Name] -> Method -> Message -> IO (Message, Name) Source

Invoke the same method on multiple Names, and wait indefinitely until the first response from any Name, returning the value and the Name which responded.

methodSelector :: Method -> Message -> Maybe (Name, RequestId, Message) Source

A simple function that, given a Method, returns a filter suitable for use with selectMessage. The typical use case will involve partial application: methodSelector method passed as an argument to selectMessage.

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

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)) Source

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 () Source

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

data HandleSite Source

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 Source

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

hangup :: HandleSite -> IO () Source

Stop handling incoming RPCs for the indicated HandleSite.

data Request Source

Encapsulates the initiating side of a call: every invocation of call produces a Request that is sent to the destination Endpoint, where the hearing side will generate a Response after completing the request'

mkRequestId :: IO RequestId Source

Create a new identifier for Requests

data Response Source

Encapsulates the completion side of a call: every invocation of call produces a Request that is sent to the destination Endpoint, where the hearing side will generate a Response after completing the request'