The address of a service to which one can connect. E.g. Host_and_port.t
is a
reasonable choice when making a TCP connection. (* JS-only: Another reasonable
choice is Service_discovery_via_catalog.Std.Service_discovery.Service_id.t
*)
create ~server_name ~log ~on_event ~retry_delay get_address
returns a persistent
connection to a server whose host and port are obtained via get_address
every
time we try to connect. For example, get_address
might look up a server's host
and port in catalog at a particular path to which multiple redundant copies of a
service are publishing their location. If one copy dies, we get the address of the
another one when looking up the address afterwards.
All connection events (see the type above) are passed to the on_event
callback, if
given. If a ~log
is supplied then these events will be written there as well,
with a "persistent-connection-to" tag value of server_name
, which should be the
name of the server we are connecting to.
`Failed_to_connect error
and `Obtained_address addr
events are only reported if
they are distinct from the most recent event of the same type that has taken place
since the most recent `Attempting_to_connect
event.
Connection is retried after Time.Span.randomize ~percent:0.3 (retry_delay ())
. The
default for retry_delay
is const (sec 10.)
. Note that what this retry delay
actually throttles is the delay between two connection attempts, so when a
long-lived connection dies, connection is usually immediately retried, and if that
failed, wait for another retry delay and retry.
connected
returns the first available connection from the time it is called. When
currently connected, the returned deferred is already determined. If closed
has
been called, then the returned deferred is never determined.
close t
closes the connection. The returned deferred becomes determined once any
resources needed to maintain the connection have been released.
is_closed t
returns true if close
has ever been called (even if the returned
deferred has not yet been fulfilled).
Note that some modules implementing Closable
may call close internally upon
noticing that the connection was closed by the other side. The interface of such a
module ought to say that this is the case.