Module Async_rpc_kernel__Rpc.Connection
val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t
module Heartbeat_config : sig ... end
module Client_implementations : sig ... end
val create : ?implementations:'s Async_rpc_kernel__.Implementations.t -> connection_state:(t -> 's) -> ?handshake_timeout:Core_kernel.Time_ns.Span.t -> ?heartbeat_config:Heartbeat_config.t -> ?description:Core_kernel.Info.t -> ?time_source:Async_kernel.Synchronous_time_source.t -> Async_rpc_kernel__.Transport.t -> (t, Core_kernel.Exn.t) Core_kernel.Result.t Async_kernel.Deferred.t
Initiate an Rpc connection on the given transport.
implementations
should be the bag of implementations that the calling side implements; it defaults toImplementations.null
(i.e., "I implement no RPCs").connection_state
will be called once, beforecreate
's result is determined, on the same connection thatcreate
returns. Its output will be provided to theimplementations
when queries arrive.WARNING: If specifying a custom
heartbeat_config
, make sure that both ends of the Rpc connection use compatible settings for timeout and send frequency. Otherwise, your Rpc connections might close unexpectedly.description
can be used to give some extra information about the connection, which will then show up in error messages and the connection's sexp. If you have lots of connections in your program, this can be useful for distinguishing them.time_source
can be given to define the time_source for which the heartbeating events will be scheduled. Defaults to wall-clock.
val contains_magic_prefix : bool Bin_prot.Type_class.reader
As of Feb 2017, the RPC protocol started to contain a magic number so that one can identify RPC communication. The bool returned by
contains_magic_prefix
says whether this magic number was observed.
val description : t -> Core_kernel.Info.t
val add_heartbeat_callback : t -> (unit -> unit) -> unit
After
add_heartbeat_callback t f
,f ()
will be called on every subsequent heartbeat tot
.
val close : ?streaming_responses_flush_timeout:Core_kernel.Time_ns.Span.t -> ?reason:Core_kernel.Info.t -> t -> unit Async_kernel.Deferred.t
close
starts closing the connection's transport, and returns a deferred that becomes determined when its close completes. It is ok to callclose
multiple times on the samet
; calls subsequent to the initial call will have no effect, but will return the same deferred as the original call.Before closing the underlying transport's writer,
close
waits for all streaming reponses to bePipe.upstream_flushed
with a timeout ofstreaming_responses_flush_timeout
.The
reason
for closing the connection will be passed to callers ofclose_reason
.
val close_finished : t -> unit Async_kernel.Deferred.t
close_finished
becomes determined after the close of the connection's transport completes, i.e. the same deferred thatclose
returns.close_finished
differs fromclose
in that it does not have the side effect of initiating a close.
val close_reason : t -> on_close:[ `started | `finished ] -> Core_kernel.Info.t Async_kernel.Deferred.t
close_reason ~on_close t
becomes determined when close starts or finishes based onon_close
, but additionally returns the reason that the connection was closed.
val is_closed : t -> bool
is_closed t
returnstrue
iffclose t
has been called.close
may be called internally upon errors or timeouts.
val bytes_to_write : t -> int
bytes_to_write
andflushed
just call the similarly named functions on theTransport.Writer.t
within a connection.
val flushed : t -> unit Async_kernel.Deferred.t
val with_close : ?implementations:'s Async_rpc_kernel__.Implementations.t -> ?handshake_timeout:Core_kernel.Time_ns.Span.t -> ?heartbeat_config:Heartbeat_config.t -> connection_state:(t -> 's) -> Async_rpc_kernel__.Transport.t -> dispatch_queries:(t -> 'a Async_kernel.Deferred.t) -> on_handshake_error:[ `Raise | `Call of Core_kernel.Exn.t -> 'a Async_kernel.Deferred.t ] -> 'a Async_kernel.Deferred.t
with_close
tries to create at
using the given transport. If a handshake error is the result, it callson_handshake_error
, for which the default behavior is to raise an exception. If no error results,dispatch_queries
is called ont
.After
dispatch_queries
returns, ifserver
is None, thet
will be closed and the deferred returned bydispatch_queries
wil be determined immediately. Otherwise, we'll wait until the other side closes the connection and then closet
and determine the deferred returned bydispatch_queries
.When the deferred returned by
with_close
becomes determined,Transport.close
has finished.NOTE: Because this connection is closed when the
Deferred.t
returned bydispatch_queries
is determined, you should be careful when using this withPipe_rpc
. For example, simply returning the pipe when you get it will close the pipe immediately. You should instead either use the pipe insidedispatch_queries
and not determine its result until you are done with the pipe, or use a different function likecreate
.
val server_with_close : ?handshake_timeout:Core_kernel.Time_ns.Span.t -> ?heartbeat_config:Heartbeat_config.t -> Async_rpc_kernel__.Transport.t -> implementations:'s Async_rpc_kernel__.Implementations.t -> connection_state:(t -> 's) -> on_handshake_error:[ `Raise | `Ignore | `Call of Core_kernel.Exn.t -> unit Async_kernel.Deferred.t ] -> unit Async_kernel.Deferred.t
Runs
with_close
but dispatches no queries. The implementations are required because this function doesn't let you dispatch any queries (i.e., act as a client), it would be pointless to call it if you didn't want to act as a server.