Struct Connection

pub struct Connection { /* private fields */ }

Send and receive Frame values from a remote peer.

When implementing networking protocols, a message on that protocol is often composed of several smaller messages known as frames. The purpose of Connection is to read and write frames on the underlying TcpStream.

To read frames, the Connection uses an internal buffer, which is filled up until there are enough bytes to create a full frame. Once this happens, the Connection creates the frame and returns it to the caller.

When sending frames, the frame is first encoded into the write buffer. The contents of the write buffer are then written to the socket.

Implementations

impl Connection

pub fn new(socket: TcpStream) -> Connection

Create a new Connection, backed by socket. Read and write buffers are initialized.

pub async fn read_frame(&mut self) -> Result<Option<Frame>>

Read a single Frame value from the underlying stream.

The function waits until it has retrieved enough data to parse a frame. Any data remaining in the read buffer after the frame has been parsed is kept there for the next call to read_frame.

Returns

On success, the received frame is returned. If the TcpStream is closed in a way that doesn’t break a frame in half, it returns None. Otherwise, an error is returned.

pub async fn write_frame(&mut self, frame: &Frame) -> Result<()>

Write a single Frame value to the underlying stream.

The Frame value is written to the socket using the various write_* functions provided by AsyncWrite. Calling these functions directly on a TcpStream is not advised, as this will result in a large number of syscalls. However, it is fine to call these functions on a buffered write stream. The data will be written to the buffer. Once the buffer is full, it is flushed to the underlying socket.

Trait Implementations

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.