pub struct Connection { /* private fields */ }Expand description
Cloneable handle of a connection task.
The task ends when Connection::shutdown is called or the last handle is dropped.
Implementations§
Source§impl Connection
impl Connection
Sourcepub async fn open<C: Connect>(
connector: C,
host: &str,
port: u16,
options: ConnectionOptions,
) -> Result<Self, ConnectorError>
pub async fn open<C: Connect>( connector: C, host: &str, port: u16, options: ConnectionOptions, ) -> Result<Self, ConnectorError>
Connects to host on port and starts the connection task.
Must be called from within a Tokio runtime.
§Errors
Returns ConnectorError::Transport when the connection cannot be established.
Sourcepub async fn request<R: Request>(
&self,
request: &R,
) -> Result<R::Response, ConnectorError>
pub async fn request<R: Request>( &self, request: &R, ) -> Result<R::Response, ConnectorError>
Sends a request and waits for its response.
§Errors
Returns ConnectorError::Server when the server answers with an error,
ConnectorError::Timeout when it does not answer in time,
ConnectorError::Transport when the connection fails while the request is pending,
ConnectorError::UnexpectedResponse when the answer has another type, and
ConnectorError::Closed when the connection is shut down.
Sourcepub async fn request_message(
&self,
payload_type: u32,
payload: Vec<u8>,
) -> Result<ProtoMessage, ConnectorError>
pub async fn request_message( &self, payload_type: u32, payload: Vec<u8>, ) -> Result<ProtoMessage, ConnectorError>
Sends an already encoded request and waits for the envelope of its response.
§Errors
Fails like Connection::request, except that the type of the answer is not checked.
Sourcepub async fn request_once(
&self,
payload_type: u32,
payload: Vec<u8>,
) -> Result<ProtoMessage, ConnectorError>
pub async fn request_once( &self, payload_type: u32, payload: Vec<u8>, ) -> Result<ProtoMessage, ConnectorError>
Sends an already encoded request that the server must not receive twice, such as an order, and waits for the envelope of the first message that answers it.
The request is written to the socket at most once. It is not sent again when the server
answers that a limit was exceeded, which is handed to the caller as the refusal it is,
and it is never replayed after a reconnection. The answer is also reported to the
subscribers of Connection::events as an Event::Message, ahead of the messages
the server sends after it, so that a reader of the events sees all the server said about
the request in the order it was said.
§Errors
Returns ConnectorError::OutcomeUnknown when the request was written and the
connection failed or the time allowed ran out before an answer arrived, in which case
the server may or may not have acted on it. ConnectorError::Transport means the
request was not written: the connection was down when it was made or was lost while it
waited its turn. ConnectorError::Closed is returned when the connection is shut down
from this side, also while the answer is awaited. Fails like
Connection::request_message otherwise.
Sourcepub async fn register_replay<R: Request>(
&self,
key: ReplayKey,
request: &R,
) -> Result<(), ConnectorError>
pub async fn register_replay<R: Request>( &self, key: ReplayKey, request: &R, ) -> Result<(), ConnectorError>
Registers a request to be sent again, under key, after every reconnection.
The request is not sent now. Requests are replayed in the order of their keys. A request
registered or replaced while the connection is being restored is replayed before
Event::Reconnected is reported.
§Errors
Returns ConnectorError::Closed when the connection is shut down.
Sourcepub async fn remove_replay(&self, key: ReplayKey) -> Result<(), ConnectorError>
pub async fn remove_replay(&self, key: ReplayKey) -> Result<(), ConnectorError>
Forgets the request registered under key.
While the connection is being restored the registered requests are looked up one at a
time, each just before it is sent, so a request removed before its turn is not replayed.
A request that was replayed already stays in force on the server: the task knows no
request that would withdraw it, which is left to the caller once
Event::Reconnected is reported.
§Errors
Returns ConnectorError::Closed when the connection is shut down.
Sourcepub async fn force_reconnect(&self) -> Result<(), ConnectorError>
pub async fn force_reconnect(&self) -> Result<(), ConnectorError>
Drops the socket on this side, which starts a reconnection as a loss would.
§Errors
Returns ConnectorError::Closed when the connection is shut down.
Sourcepub fn events(&self) -> Receiver<Event>
pub fn events(&self) -> Receiver<Event>
Subscribes to the events of the connection, starting with the next one.
A subscriber that falls more than the event capacity behind skips the oldest events and is told how many were skipped.
Sourcepub async fn closed(&self)
pub async fn closed(&self)
Waits until the connection task has ended, after which every request fails with
ConnectorError::Closed.
Sourcepub async fn shutdown(&self)
pub async fn shutdown(&self)
Stops the connection task and waits until the socket is closed.
Requests still pending fail with ConnectorError::Closed. Calling it again is
harmless.