Portability | non-portable (requires STM) |
---|---|
Stability | experimental |
Maintainer | phil@haphazardhouse.net |
Safe Haskell | None |
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))
- hear :: Endpoint -> Name -> Method -> IO (Message, Reply Message)
- hearTimeout :: Endpoint -> Name -> Method -> Int -> IO (Maybe (Message, Reply Message))
- type Reply b = b -> IO ()
- data HandleSite
- handle :: Endpoint -> Name -> Method -> (Message -> IO Message) -> IO HandleSite
- hangup :: HandleSite -> IO ()
- data Request = Request {
- requestId :: RequestId
- requestCaller :: Name
- requestMethod :: Method
- requestArgs :: Message
- data Response = Response {
- responseId :: RequestId
- responseFrom :: Name
- responseValue :: Message
Documentation
newCallSite :: Endpoint -> Name -> CallSiteSource
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 MessageSource
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.
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.
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 HandleSiteSource
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
.
Request | |
|
Response | |
|