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

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

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.

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

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)

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)

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.

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

A variant of hear, except it listens for any incoming RPC request on the specified Endpoint.

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

A variant of hearTimeout, except it listens for any incoming RPC request on the specified Endpoint

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.

Constructors

HandleSite Name (Async ())

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.

handleAll :: Endpoint -> Name -> (Method -> Message -> IO Message) -> IO HandleSite

Handle all RPCs 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

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'

Constructors

Request

Fields

• requestId :: RequestId
• requestCaller :: Name
• requestMethod :: Method
• requestArgs :: Message

Instances

Eq Request

Methods

(==) :: Request -> Request -> Bool

(/=) :: Request -> Request -> Bool

Show Request

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

Serialize Request

Methods

put :: Putter Request

get :: Get Request

data RequestId

A unique identifier for a Request

Instances

Eq RequestId

Methods

(==) :: RequestId -> RequestId -> Bool

(/=) :: RequestId -> RequestId -> Bool

Show RequestId

Methods

showsPrec :: Int -> RequestId -> ShowS

show :: RequestId -> String

showList :: [RequestId] -> ShowS

Generic RequestId

Associated Types

type Rep RequestId :: * -> *

Methods

from :: RequestId -> Rep RequestId x

to :: Rep RequestId x -> RequestId

Serialize RequestId

Methods

put :: Putter RequestId

get :: Get RequestId

type Rep RequestId

type Rep RequestId = D1 (MetaData "RequestId" "Network.RPC" "courier-0.1.1.5-5BT5u0NPfE64Kby3wLlubv" True) (C1 (MetaCons "RequestId" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Word32, Word32, Word32, Word32))))

mkRequestId :: IO RequestId

Create a new identifier for Requests

data Response

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'

Constructors

Response

Fields

• responseId :: RequestId
• responseFrom :: Name
• responseValue :: Message

Instances

Eq Response

Methods

(==) :: Response -> Response -> Bool

(/=) :: Response -> Response -> Bool

Show Response

Methods

showsPrec :: Int -> Response -> ShowS

show :: Response -> String

showList :: [Response] -> ShowS

Serialize Response

Methods

put :: Putter Response

get :: Get Response