package async_rpc_kernel

Initiate an Rpc connection on the given transport. implementations should be the bag of implementations that the calling side implements; it defaults to Implementations.null (i.e., "I implement no RPCs").

protocol_version_headers should contain the pre-shared protocol version headers, if applicable. The client and server must agree on whether these were shared and, if so, what they contained, or there may be a protocol error.

connection_state will be called once, before create's result is determined, on the same connection that create returns. Its output will be provided to the implementations 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.

max_metadata_size will limit how many bytes of metadata this peer can send along with each query. It defaults to 1k. User-provided metadata exceeding that size will be truncated. WARNING: setting this value too high allows this connection to send large amounts of data to the callee, unnoticed, which can severely degrade performance.

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.

identification can be used to send an additional information to the peer. This is intended to be used for identifying the identity of the /process/ as opposed to the identity of the user. We use a bigstring to leave the option for clients to interpret as structured data of their choosing.

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.

After add_heartbeat_callback t f, f () will be called after every subsequent heartbeat received by t.

Changes the heartbeat timeout and restarts the timer by setting last_seen_alive to the current time.

The last time either any message has been received or reset_heartbeat_timeout was called.

close starts closing the connection's transport, and returns a deferred that becomes determined when its close completes. It is ok to call close multiple times on the same t; 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 responses to be Pipe.upstream_flushed with a timeout of streaming_responses_flush_timeout.

The reason for closing the connection will be passed to callers of close_reason.

close_finished becomes determined after the close of the connection's transport completes, i.e. the same deferred that close returns. close_finished differs from close in that it does not have the side effect of initiating a close.

close_reason ~on_close t becomes determined when close starts or finishes based on on_close, but additionally returns the reason that the connection was closed.

is_closed t returns true iff close t has been called. close may be called internally upon errors or timeouts.

bytes_to_write and flushed just call the similarly named function on the Transport.Writer.t within a connection.

bytes_written just calls the similarly named functions on the Transport.Writer.t within a connection.

bytes_read just calls the similarly named function on the Transport.Reader.t within a connection.

Peer menu will become determined before any other messages are received. The menu is sent automatically on creation of a connection. If the peer is using an older version, the value is immediately determined to be None. If the connection is closed before the menu is received, an error is returned.

It is expected that one will call Versioned_rpc.Connection_with_menu.create instead of this function and that will request the menu via rpc if it gets None.

Like peer_menu but returns an rpc result

Peer identification will become determined before any other messages are received. If the peer is using an older version, the peer id is immediately determined to be None. If the connection is closed before the menu is received, None is returned.

with_close tries to create a t using the given transport. If a handshake error is the result, it calls on_handshake_error, for which the default behavior is to raise an exception. If no error results, dispatch_queries is called on t.

After dispatch_queries returns, if server is None, the t will be closed and the deferred returned by dispatch_queries will be determined immediately. Otherwise, we'll wait until the other side closes the connection and then close t and determine the deferred returned by dispatch_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 by dispatch_queries is determined, you should be careful when using this with Pipe_rpc. For example, simply returning the pipe when you get it will close the pipe immediately. You should instead either use the pipe inside dispatch_queries and not determine its result until you are done with the pipe, or use a different function like create.

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.