Rpc_proxy module provides an improved reliability layer on
Rpc_client. This layer especially features:
Proxies can only handle stream connections (TCP and Unix Domain). Also, the remote endpoints must already be specified by socket addresses. (No portmapper and other indirect lookup methods.)
The proxy functionality is implemented in two layers, the managed clients, and the managed sets. The former layer can handle only one TCP connection (with reconnect), whereas the latter is able to manage a bunch of connections to the same service. Both layers can profit from a reliability cache that knows which services had errors in the past.
See below for a tutorial.
There is also a blog article explaining RPC proxies: The next server, please!
A normal RPC client has a very limited lifecylce: It is created, then a connection is made to an RPC service, messages are exchanged, and finally the connection is terminated. After that the client becomes unusable. In short, it is "use once" client.
In contrast to this, managed clients can be recycled. This is especially useful for dealing with socket errors, and connection terminations triggered by the RPC server.
How to use managed clients: For a normal RPC client the
ocamlrpcgen creates all required glue code to easily
start RPC calls. For example, if a file
proto.x is taken as input
ocamlrpcgen, a piece of code doing a call could look like:
let client = Proto_clnt.PROG.VERS.create_client connector protocol let result = Proto_clnt.PROG.VERS.procedure client argument
procedure are just placeholders for the
name of the program, the version identifier, and the procedure name.)
For RPC proxies, however, this is slightly more complicated.
does not produce a managed client that is ready for use. Instead,
only a functor is provided that can take the
Rpc_proxy.ManagedlClient module as input:
module M = Proto_clnt.Make'PROG(Rpc_proxy.ManagedClient) let esys = Unixqueue.create_unix_event_system() let mclient_config = Rpc_proxy.ManagedClient.create_mclient_config ~programs:[ Proto_clnt.PROG.VERS._program ] () in let mclient = Rpc_proxy.ManagedClient.create_mclient mclient_config connector esys let result = M.VERS.procedure mclient argument
(The functor approach has been chosen, because it gives the
user more flexibility - it is possible to apply the functor
on other implementations of improved clients than
esys is always explicit, even in the case the
user only performs synchronous calls - the user should create
esys then, pass it to
mclient, and ignore it otherwise.
Now, how does the recycling feature work? The managed client can be in one of three states:
`Down: The client is not connected. This is the initial state, and the state after errors and terminated connections (no matter whether triggered by the client or by the server)
`Connecting: The client is busy (re)connecting (only used in some cases)
`Up sockaddr: The client is connected and has the socket address
The state can be queried with
When it is
`Down, the next RPC call automatically starts the
reconnect to the service. When the connection is established, the
call is done, and the messages are exchanged that are representing
the call. After that, the state remains
`Up after the call.
When the call stops because of an error, the error is reported to
the user in the normal way, and the client is shut down, i.e. after
an error the state is
`Down. If the user decides to try the call
again, the client automatically reconnects following the outlined
rules. Note that managed clients never automatically retry calls
When the TCP connection is regularly shut down (either by the server
or by the client calling
client state is changed to
`Down at the next opportunity. Especially
a server-driven shutdown may first be detected when the next RPC call
is tried on the connection. This may or may not lead to an error
depending on the exact timing. In any way, the connection is finally
Of course, managed clients must be shut down after use, because
there is no other (automatic) way of recognizing that they are no
longer used. Call
Rpc_proxy.ManagedClient.shut_down for this.
Managed client also have a few more features that can be
esysis running. Especially for synchronous calls this is typically not the case, so one would have to call
Unixqueue.run esysnow and then to create opportunities for detecting the idle timeout.
Managed sets are another layer on top of the managed clients. These sets are able to manage several connections where each is implemented as managed client. The connections can go to the same server endpoint in order to parallelize RPCs at the client side, or to several server endpoints that provide the same service. The latter can be used for client-driven load balancing, and for client-driven failover management of HA setups (HA = high availability).
For creating a managed set, the code looks like
module M = Proto_clnt.Make'PROG(Rpc_proxy.ManagedClient) let esys = Unixqueue.create_unix_event_system() let mclient_config = Rpc_proxy.ManagedClient.create_mclient_config ~programs:[ Proto_clnt.PROG.VERS._program ] () in let mset_config = Rpc_proxy.ManagedSet.create_mset_config ~mclient_config () in let services = [| connector, n_connections; ... |] in let mset = Rpc_proxy.ManagedSet.create_mset mset_config services esys in let mclient, idx = Rpc_proxy.ManagedSet.mset_pick mset in let result = M.VERS.procedure mclient argument
The managed clients are internally created by the set - one
only should pass in
mclient_config so the set knows what kind of
client is preferred. For the simple application of maintaining
several connections to the same server, one would create the
with a one-element service array:
let services = [| connector, n_connections |]
connector describes the server port, and
the maximum number of connections to create and maintain.
function creates internally up to
n_connections managed clients,
and returns one of them. By default, it is not guaranteed that the
client is idle (meaning no previous call is pending) -
if the connections are all already busy,
starts returning busy connections (but the least busy one first).
There are a number of options allowing to modify the default behavior:
mset_pick. To do this, pass the argument
Rpc_proxy.ManagedSet.create_mset_config. It can then happen that no client is idle, and
servicesarray has more than one element, they are considered as equivalent service endpoints.
mset_pickwill pick one of the endpoints. There are two policies controlling the selection: With
~policy:`Balance_loadit is aimed at sending roughly the same number of calls to all endpoints. With
~policy:`Failoverthe services are assigned precedences by the position in the array (i.e. the first service is used as long as possible, then the second service is used, etc.). The
policyargument is again to be passed to
Of course, managed sets must be shut down after use, because
there is no other (automatic) way of recognizing that they are no
longer used. Call
Rpc_proxy.ManagedSet.shut_down for this.
The cache allows to disable certain hosts or ports when the error
counter reaches a limit. The service is disabled for a limited time span.
This is especially useful when there is an alternate port that can
jump in for the failing one, i.e. when the
services array of a
managed set has two or more elements.
There is a single global cache object, but one can also create
specific cache objects. Generally, cache objects can be shared by
many managed clients and managed sets. The hope is that sharing
is useful because more data can be made available to users of
services. If you do not want to use the global cache object, you
can create your own, and configure it in
The global cache object is automatically used when nothing else is specified. The global cache object is by default configured in a way so it does not have any effect, though. So we have to change this in order to enable the cache:
let rcache_config = Rpc_proxy.ReliabilityCache.create_rcache_config ~policy:`Independent ~threshold:3 () in Rpc_proxy.ReliabilityCache.set_global_rcache_config rcache_config
This means that 3 errors in sequence disable a service port.
means that each port is handled independently in this respect.
At the first time, the port is only disabled for one second. The duration of the time span is increased by each additional error until it reaches 64 seconds. These durations can be changed, of course.
As the impact of changing the global cache object is sometimes
unpredictable, one can also create a private cache object
Rpc_proxy.ReliabilityCache.create_rcache). Another way is
to derive a semi-private object from the global one. This means
that the error counters are global, but the interpretation can
be set individually in each use. This would look like:
let rcache_config = Rpc_proxy.ReliabilityCache.create_rcache_config ~policy:`Independent ~threshold:3 () in let rcache = Rpc_proxy.ReliabilityCache.derive_rcache (Rpc_proxy.ReliabilityCache.global_rcache()) rcache_config in ... let mclient_config = Rpc_proxy.ManagedClient.create_mclient_config ... ~rcache ... ()
In the layer of managed sets there is some limited support for automatically repeating failing idempotent RPC calls.
Instead of calling the RPC with
let mclient, idx = Rpc_proxy.ManagedSet.mset_pick mset in let result = M.VERS.procedure mclient argument
let result = Rpc_proxy.ManagedSet.idempotent_sync_call mset M.VERS.procedure'async argument
The effet is that
repeats automatically the call when an error occurs. It is
assumed that the call is idempotent so it can be repeated
without changing the meaning.
The call may be repeated several times. This is configured in
the managed set
Note that one has to pass the asynchronous version (suffix
of the RPC wrapper even when doing a synchronous call.
Also see the documentation for