Copyright | (c) Phil Hargett 2014 |
---|---|
License | MIT (see LICENSE file) |
Maintainer | phil@haphazardhouse.net |
Stability | experimental |
Portability | non-portable (requires STM) |
Safe Haskell | None |
Language | Haskell98 |
An implementation of synchronous remote procedure calls
(RPC) on top of
Endpoint
s.
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 Method
s 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 call
ing 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.
- type Method = String
- newCallSite :: Endpoint -> Name -> CallSite
- data CallSite
- call :: CallSite -> Name -> Method -> Message -> IO Message
- callWithTimeout :: CallSite -> Name -> Method -> Int -> Message -> IO (Maybe Message)
- gcall :: CallSite -> [Name] -> Method -> Message -> IO (Map Name Message)
- gcallWithTimeout :: CallSite -> [Name] -> Method -> Int -> Message -> IO (Map Name (Maybe Message))
- anyCall :: CallSite -> [Name] -> Method -> Message -> IO (Message, Name)
- methodSelector :: Method -> Message -> Maybe (Name, RequestId, Message)
- hear :: Endpoint -> Name -> Method -> IO (Message, Reply Message)
- hearTimeout :: Endpoint -> Name -> Method -> Int -> IO (Maybe (Message, Reply Message))
- hearAll :: Endpoint -> Name -> IO (Method, Message, Reply Message)
- hearAllTimeout :: Endpoint -> Name -> Int -> IO (Maybe (Method, Message, Reply Message))
- type Reply b = b -> IO ()
- data HandleSite
- handle :: Endpoint -> Name -> Method -> (Message -> IO Message) -> IO HandleSite
- handleAll :: Endpoint -> Name -> (Method -> Message -> IO Message) -> IO HandleSite
- hangup :: HandleSite -> IO ()
- data Request = Request {}
- data RequestId
- mkRequestId :: IO RequestId
- data Response = Response {}
Documentation
newCallSite :: Endpoint -> Name -> 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.
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.
hearAllTimeout :: Endpoint -> Name -> Int -> IO (Maybe (Method, Message, Reply Message)) Source
A variant of hearTimeout
, except it listens for any incoming RPC request on the specified Endpoint
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
.
handleAll :: Endpoint -> Name -> (Method -> Message -> IO Message) -> IO HandleSite Source
Handle all RPCs on the specified Endpoint
until hangup
is called on the returned HandleSite
hangup :: HandleSite -> IO () Source
Stop handling incoming RPCs for the indicated HandleSite
.
Encapsulates the initiating side of a call
: every invocation of call
produces a Request
that is sent
to the destination Endpoint
, where the hear
ing side will generate a Response
after completing the request'
Request | |
|
A unique identifier for a Request
mkRequestId :: IO RequestId Source
Create a new identifier for Request
s