(* $Id$ *)
(** RPC proxies *)
(** The [Rpc_proxy] module provides an improved reliability layer on
top of {!Rpc_client}. This layer especially features:
- automatic connection management: TCP connections are started
and terminated as needed
- multiple connections can be held in parallel to a remote
server to increase concurrency on the server
- failover to other servers when the orignal servers time out
- support for an initial ping at connection establishment time
to test the availability of the connection
- retransmission of idempotent RPC calls
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:
{{:http://blog.camlcity.org/blog/ocamlnet3_ha.html} The next server,
please!}
*)
module ReliabilityCache : sig
(** The reliability cache stores information about the availability
of remote servers. The managed clients put information about
recent failures into the cache.
It is advantegeous to have only one cache per process, because
this maximizes the usefulness. The cache is thread-safe.
A server endpoint is disabled when too many errors occur in
sequence. For a disabled endpoint the functions [host_is_enabled]
and/or [sockaddr_is_enabled] return [false]. The endpoint is
automatically enabled again after some timeout; this is initially
[disable_timeout_min], but is increased exponentially until
[disable_timeout_max] when further errors occur.
Independently of this machinery the functions [host_is_enabled]
and [sockaddr_is_enabled] may also return [false] when an
external availability checker says that the endpoint is down.
This information is not entered into the cache, and will also
not trigger the disable timeout. Instead, the hook function
getting the availability will be simply called again.
*)
type rcache
(** The cache *)
type rcache_policy =
[ `Independent
| `Failing_port_disables_host of int
| `Any_failing_port_disables_host
| `None
]
(** How failures of individual ports are interpreted:
- [`Independent]: When a connection to a remote port repeatedly fails,
only this port is disabled
- [`Failing_port_disables_host p]: When a connection to the TCP
port [p] repeatedly fails, the whole remote host is disabled.
Other ports do not disable the host, but are treated as in
[`Independent].
- [`Any_failing_port_disables_host]: When a connection to any TCP
port repeatedly fails, the whole remote host is disabled
- [`None]: Nothing is disabled
Note that the [rcache_availability] hook is not affected by the
policy; this hook is called anyway. The policy only determines
how the internal error counter is interpreted.
*)
type rcache_config =
{ rcache_policy : rcache_policy; (** The policy, see above *)
rcache_disable_timeout_min : float; (** For how long ports and hosts
are disabled *)
rcache_disable_timeout_max : float; (** For how long ports and hosts
are disabled at most *)
rcache_threshold : int; (** How many errors are required
for disabling a port *)
rcache_availability : rcache -> Unix.sockaddr -> bool; (** External
availability checker. Called by [sockaddr_is_enabled] before
the result is calculated *)
}
val create_rcache_config : ?policy:rcache_policy ->
?disable_timeout_min:float ->
?disable_timeout_max:float ->
?threshold:int ->
?availability:(rcache -> Unix.sockaddr -> bool) ->
unit -> rcache_config
(** Create a config record. The optional arguments set the config
components with the same name. The arguments default to:
- [policy = `None]
- [disable_timeout_min = 1.0]
- [disable_timeout_max = 64.0]
- [threshold = 1]
- [availability = fun _ _ -> true]
*)
val create_rcache : rcache_config -> rcache
(** Creates a new cache object. The same cache can be used by several
managed clients, even by totally unrelated ones
*)
val rcache_config : rcache -> rcache_config
(** Return the config *)
val global_rcache_config : unit -> rcache_config
(** Returns the global config:
- [policy = `None]
- [disable_timeout_min = 1.0]
- [disable_timeout_max = 64.0]
- [threshold = 1]
- [availability = fun _ _ -> true]
*)
val set_global_rcache_config : rcache_config -> unit
(** Sets the new global config. This is only possible as long as
neither [default_global_config] nor [global_rcache] have been called.
*)
val global_rcache : unit -> rcache
(** The global cache. Initially, this cache has the default config.
It is possible to change the default config before using the
global cache for the first time.
*)
val derive_rcache : rcache -> rcache_config -> rcache
(** [derive_cache parent config]: Returns a new cache that shares the
error counters with [parent]. The interpretation of the counters,
however, may be differently configured in [config].
Because it is advantageous to share the error information as much
as possible, the recommended way to create a new cache object is
to derive it from the global cache.
What [derive_rcache] actually does (and this is not yet
optimal): Any [incr] and [reset] of an error counter is also
forwarded to the parent cache. The tests whether hosts and ports
are enabled do an AND of the results for the cache and its parent
(i.e. both must be ok to enable). This allows some information
sharing, but only in vertical direction.
*)
val incr_rcache_error_counter : rcache -> Unix.sockaddr -> unit
(** Increase the error counter for this sockaddr. If the threshold
is reached and there is a disable policy, the sockaddr will be disabled.
This function is to be called after an RPC call times out, or
runs into a socket error.
*)
val reset_rcache_error_counter : rcache -> Unix.sockaddr -> unit
(** Reset the error counter for this sockaddr. If disabled, the
sockaddr is set to enabled again.
This function is to be called when an RPC call is successful.
*)
val sockaddr_is_enabled : rcache -> Unix.sockaddr -> bool
(** Returns whether the sockaddr is enabled. This also calls the
[rcache_availability] hook.
*)
val host_is_enabled : rcache -> Unix.inet_addr -> bool
(** Returns whether the host is enabled *)
end
module ManagedClient : sig
(** Managed clients are {!Rpc_client} clients with the ability to
reconnect in the case of errors.
Additional features:
- they can also be disabled, either based on a time criterion or
a customizable hook. This encodes the assumption that failing
servers need some time to recover
- unused connections are closed (driven by a timeout)
- support for the initial ping after establishing the connection
Initial pings are useful to test whether the connection is
really working. Servers normally accept new TCP connections without
knowing whether there are resources for processing the connections
(i.e. whether there is a process or thread waiting for serving
it). Because of this, the client cannot assume that the TCP
connection is really up only because the [connect] system call
said the connection is there. The initial ping fixes this problem:
The null procedure is once called after the TCP connection has
been established. Only when this works the client believes the
connection is really up. It is required that [mclient_programs]
is configured with at least one program, and this program must
have a procedure number 0 of type [void -> void].
In multi-threaded programs, threads must not share managed clients.
Managed clients can be used together with ocamlrpcgen-generated
modules. Provided the generated module [M_clnt] contains the
client code for program [P] and version [V], one can do
{[
module MC = M_clnt.Make'P(Rpc_proxy.ManagedClient)
]}
and call RPCs [f] as in
{[
let res = MC.V.f mc arg
]}
(if [mc] is the managed client, and [arg] the argument).
*)
type mclient
(** A managed client *)
type mclient_config =
{ mclient_rcache : ReliabilityCache.rcache; (** The rcache *)
mclient_socket_config : Rpc_client.socket_config;
(** The socket configuration *)
mclient_idle_timeout : float;
(** After how many seconds unused connections are closed.
A negative value means never. 0 means immediately. A positive
value is a point in time in the future.
*)
mclient_programs : Rpc_program.t list;
(** The programs to bind *)
mclient_msg_timeout : float;
(** After how many seconds the reply must have been arrived.
A negative value means there is no timeout. 0 means immediately.
A positive
value is a point in time in the future.
*)
mclient_msg_timeout_is_fatal : bool;
(** Whether a message timeout is to be considered as fatal error
(the client is shut down, and the error counter for the endpoint
is increased)
*)
mclient_exception_handler : (exn -> unit) option;
(** Whether to call {!Rpc_client.set_exception_handler} *)
mclient_auth_methods : Rpc_client.auth_method list;
(** Set these authentication methods in the client *)
mclient_user_name : string option;
(** The user name for authentication, None = default user *)
mclient_initial_ping : bool;
(** Whether to call procedure 0 of the first program after
connection establishment (see comments above)
*)
mclient_max_response_length : int option;
(** The maximum response length. See
{!Rpc_client.set_max_response_length}.
*)
mclient_mstring_factories : Netxdr_mstring.named_mstring_factories option
(** The factories to use for decoding managed strings *)
}
exception Service_unavailable
(** Procedure calls may end with this exception when the reliability
cache disables the service
*)
val create_mclient_config : ?rcache:ReliabilityCache.rcache ->
?socket_config:Rpc_client.socket_config ->
?idle_timeout:float ->
?programs:Rpc_program.t list ->
?msg_timeout:float ->
?msg_timeout_is_fatal:bool ->
?exception_handler:(exn -> unit) ->
?auth_methods:Rpc_client.auth_method list ->
?user_name:string option ->
?initial_ping:bool ->
?max_response_length:int ->
?mstring_factories:Netxdr_mstring.
named_mstring_factories ->
unit -> mclient_config
(** Create a config record. The optional arguments set the config
components with the same name. The defaults are:
- [rcache]: Use the global reliability cache
- [socket_config]: {!Rpc_client.default_socket_config}
- [programs]: The empty list. It is very advisable to fill this!
- [msg_timeout]: (-1), i.e. none
- [msg_timeout_is_fatal]: false
- [exception_handler]: None
- [auth_methods]: empty list
- [user_name]: None
- [initial_ping]: false
- [max_response_length]: None
- [mstring_factories]: None
*)
val create_mclient : mclient_config ->
Rpc_client.connector ->
Unixqueue.event_system ->
mclient
(** Create a managed client for this config connecting to this
connector. Only [Internet] and [Unix] connectors are supported.
*)
type state = [ `Down | `Connecting | `Up of Unix.sockaddr option]
(** The state:
- [`Down]: The initial state, and also reached after a socket
error, or after one of the shutdown functions is called.
Although [`Down], there might still some cleanup to do.
When RPC functions are called, the client is automatically
revived.
- [`Connecting]: This state is used while the initial ping is
done. It does not reflect whether the client is really
TCP-connected. Without initial ping, this state cannot occur.
- [`Up s]: The client is (so far known) up and can be used.
[s] is the socket address of the local socket
*)
val mclient_state : mclient -> state
(** Get the state *)
val mclient_serial : mclient -> int
(** Get the serial number of the connection. The serial number is
increased when the client is reconnected. If the client is down
the serial number of the next connection attempt is returned.
*)
val pending_calls : mclient -> int
(** Returns the number of pending calls *)
val event_system : mclient -> Unixqueue.event_system
(** Return the event system *)
val shut_down : mclient -> unit
val sync_shutdown : mclient -> unit
val trigger_shutdown : mclient -> (unit -> unit) -> unit
(** Shut down the managed client. See the corresponding functions
{!Rpc_client.shut_down}, {!Rpc_client.sync_shutdown}, and
{!Rpc_client.trigger_shutdown}
*)
val record_unavailability : mclient -> unit
(** Increases the error counter in the reliability cache for this
connection. The only effect can be that the error counter
exceeds the [rcache_threshold] so that the server endpoint
is disabled for some time. However, this only affects new
connections, not existing ones.
For a stricter interpretation of errors see
[enforce_unavailability].
The error counter is increased anyway when a socket error
happens, or an RPC call times out and [msg_timeout_is_fatal]
is set. This function can be used to also interpret other
misbehaviors as fatal errors.
*)
(* This is a strange function. Maybe it should go away. One could
call it after a successful RPC call when the result of this call
indicates that the server is not good enough for further use
(although it is still able to respond). However, after a successful
RPC the error counter is reset, and this cannot be prevented by
this function (too late)
*)
val enforce_unavailability : mclient -> unit
(** Enforces that all pending procedure calls get the
[Service_unavailable] exception, and that the client is shut down.
The background is this: When the reliability cache discovers an
unavailable port or host, only the new call is stopped with this
exception, but older calls remain unaffected. This function
can be used to change the policy, and to stop even pending calls.
The difference to [trigger_shutdown] is that the pending RPC
calls get the exception [Service_unavailable] instead of
{!Rpc_client.Message_lost}, and that it is enforced that the
shutdown is recorded as fatal error in the reliability cache.
*)
val set_batch_call : mclient -> unit
(** The next call is a batch call. See {!Rpc_client.set_batch_call} *)
val rpc_engine : mclient ->
(mclient -> 'a -> ((unit -> 'b) -> unit) -> unit) ->
'a ->
'b Uq_engines.engine
(** Call an RPC function in engine style:
{[ let e = rpc_engine mc f_rpc ]}
where [f_rpc] is one of the generated client functions (async
signature). The engine reaches [`Done r] when the result [r]
has arrived.
The engine is not abortable (shut the client down instead).
*)
val compare : mclient -> mclient -> int
(** [ManagedClient] can be used with [Set.Make] and [Map.Make] *)
include Rpc_client.USE_CLIENT with type t = mclient
(** We implement the [USE_CLIENT] interface for calling procedures *)
end
module ManagedSet : sig
(** Manages a set of clients *)
type mset
(** a managed set *)
type mset_policy =
[ `Failover | `Balance_load ]
(** Sets in which order managed clients are picked from the
[services] array passed to [create_mset]:
- [`Failover]: Picks an element from the first service
in [services] that is enabled and has free capacity.
That means that the first service is preferred until it is
maxed out or it fails, then the second service is preferred,
and so on.
- [`Balance_load]: Picks an element from the service in
[services] that is enabled and has the lowest load.
*)
type mset_config =
{ mset_mclient_config : ManagedClient.mclient_config;
(** The mclient config *)
mset_policy : mset_policy;
(** The policy *)
mset_pending_calls_max : int;
(** When an mclient processes this number of calls at the same time,
it is considered as fully busy. (Value must by > 0).
*)
mset_pending_calls_norm : int;
(** When an mclient processes less than this number of calls,
its load is considered as too light, and it is tried to put
more load on this client before opening another one
*)
mset_idempotent_max : int;
(** How often idempotent procedures may be tried to be called.
A negative value means infinite.
*)
mset_idempotent_wait : float;
(** Wait this number of seconds before trying again *)
}
exception Cluster_service_unavailable
(** Raised by [mset_pick] when no available endpoint can be found,
or all available endpoints have reached their maximum load.
*)
val create_mset_config : ?mclient_config:ManagedClient.mclient_config ->
?policy:mset_policy ->
?pending_calls_max:int ->
?pending_calls_norm:int ->
?idempotent_max:int ->
?idempotent_wait:float ->
unit -> mset_config
(** Create a config record. The optional arguments set the config
components with the same name. The defaults are:
- [mclient_config]: The default mclient config
- [policy]: [`Balance_load]
- [pending_calls_max]: [max_int]
- [pending_calls_norm]: 1
- [idempotent_max]: 3
- [idempotent_wait]: 5.0
*)
val create_mset : mset_config ->
(Rpc_client.connector * int) array ->
Unixqueue.event_system ->
mset
(** [create_mset config services]: The mset is created with [config],
and the [services] array describes which ports are available,
and how often each port may be contacted (i.e. max number of
connections).
*)
val mset_pick : ?from:int list -> mset -> ManagedClient.mclient * int
(** Pick an mclient for another call, or raise [Cluster_service_unavailable].
The returned int is the index in the [mset_services] array.
If [from] is given, not all specified mclients qualify for this
call. In [from] one can pass a list of indexes pointing into
the [mset_services] array, and only from these mclients the
mclient is picked. For [`Failover] policies, the order given
in [from] is respected, and the mclients are checked from left
to right.
*)
val mset_services : mset -> (Rpc_client.connector * int) array
(** Returns the service array *)
val mset_load : mset -> int array
(** Returns the number of pending calls per service *)
val event_system : mset -> Unixqueue.event_system
(** Return the event system *)
val shut_down : mset -> unit
val sync_shutdown : mset -> unit
val trigger_shutdown : mset -> (unit -> unit) -> unit
(** Shut down the managed set. See the corresponding functions
{!Rpc_client.shut_down}, {!Rpc_client.sync_shutdown}, and
{!Rpc_client.trigger_shutdown}
*)
val idempotent_async_call :
?from:int list ->
mset ->
(ManagedClient.mclient -> 'a -> ((unit -> 'b) -> unit) -> unit) ->
'a ->
((unit -> 'b) -> unit) ->
unit
(** [idempotent_async_call
mset async_call arg emit]: Picks a new
[mclient] and calls [async_call mclient arg emit].
If the call leads to a fatal error, a new [mclient]
is picked, and the call is repeated. In total, the call may be
tried [mset_idempotent_max] times. It is recommended to set
[rcache_threshold] to 1 when using this function because this
enforces that a different mclient is picked when the first one
fails.
Note that a timeout is not considered as a fatal error by default;
one has to enable that by setting [mclient_msg_timeout_is_fatal].
Note that this form of function is compatible with the
generated [foo'async] functions of the language mapping.
[from] has the same meaning as in [mset_pick].
*)
val idempotent_sync_call :
?from:int list ->
mset ->
(ManagedClient.mclient -> 'a -> ((unit -> 'b) -> unit) -> unit) ->
'a ->
'b
(** Synchronized version. Note that you have to pass an asynchronous
function as second argument. The result is synchronous, however.
*)
end
(**
{1:tut The [Rpc_proxy] tutorial}
{2:mclient Managed clients}
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.
{b How to use managed clients:} For a {i normal} RPC client the
generator [ocamlrpcgen] creates all required glue code to easily
start RPC calls. For example, if a file [proto.x] is taken as input
for [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
]}
(Here, [PROG], [VERS], [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. [ocamlrpcgen]
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
{!Rpc_proxy.ManagedClient}.)
Note that [esys] is always explicit, even in the case the
user only performs synchronous calls - the user should create
a new [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
[sockaddr]
The state can be queried with {!Rpc_proxy.ManagedClient.mclient_state}.
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
by themselves.
When the TCP connection is regularly shut down (either by the server
or by the client calling {!Rpc_proxy.ManagedClient.shut_down}), the
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
established again.
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
enabled in [mclient_config], especially:
- {b Initial ping}: This means that the TCP connection is tested
before being used for user operations. The test is done by pinging
the service once (via the RPC null procedure). This is recommended
because some connectivity problems can first be detected when the
TCP connection is actually used.
- {b Idle timeout}: The TCP connection is closed after it is
idle for some period of time. "Idle" means here that nothing is
being transmitted, and that no response from the server is expected.
The connection is closed at the first opportunity. The user should
be aware that this can only happen when the event loop for [esys]
is running. Especially for synchronous calls this is typically
not the case, so one would have to call [Unixqueue.run esys] now
and then to create opportunities for detecting the idle timeout.
- {b Reliability cache}: The cache object counts errors, and can
disable certain service endpoints if they only produce errors.
This mostly makes sense when there are alternative endpoints,
i.e. in the context of a managed set (see below).
*)
(** {2 Managed Sets}
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 [mset]
with a one-element service array:
{[
let services =
[| connector, n_connections |]
]}
where [connector] describes the server port, and [n_connections] is
the maximum number of connections to create and maintain.
The {!Rpc_proxy.ManagedSet.mset_pick}
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, [mset_pick]
starts returning busy connections (but the least busy one first).
There are a number of options allowing to modify the default
behavior:
- One can enforce that only idle clients are returned by [mset_pick].
To do this, pass the argument [~mset_pending_calls_max:1] to
{!Rpc_proxy.ManagedSet.create_mset_config}. It can then happen
that no client is idle, and [mset_pick] will raise
{!Rpc_proxy.ManagedSet.Cluster_service_unavailable}.
- If the [services] array has more than one element, they are
considered as equivalent service endpoints. [mset_pick] will
pick one of the endpoints. There are two policies controlling
the selection: With [~policy:`Balance_load] it is aimed at
sending roughly the same number of calls to all endpoints. With
[~policy:`Failover] the 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 [policy] argument
is again to be passed to {!Rpc_proxy.ManagedSet.create_mset_config}.
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.
{2 Caching reliability data}
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 [mclient_config].
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. [`Independent]
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
...
()
]}
{2 Idempotent calls}
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
]}
one uses
{[
let result =
Rpc_proxy.ManagedSet.idempotent_sync_call
mset
M.VERS.procedure'async
argument
]}
The effet is that {!Rpc_proxy.ManagedSet.idempotent_sync_call}
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 [mset] (parameter [mset_idempotent_max]).
Note that one has to pass the asynchronous version (suffix ['async])
of the RPC wrapper even when doing a synchronous call.
Also see the documentation for
{!Rpc_proxy.ManagedSet.idempotent_async_call}.
*)
