Trait async_proto::Protocol

source · [−]
pub trait Protocol: Sized {
    fn read<'a, R: AsyncRead + Unpin + Send + 'a>(
        stream: &'a mut R
    ) -> Pin<Box<dyn Future<Output = Result<Self, ReadError>> + Send + 'a>>;
    fn write<'a, W: AsyncWrite + Unpin + Send + 'a>(
        &'a self,
        sink: &'a mut W
    ) -> Pin<Box<dyn Future<Output = Result<(), WriteError>> + Send + 'a>>;
    fn read_sync(stream: &mut impl Read) -> Result<Self, ReadError>;
    fn write_sync(&self, sink: &mut impl Write) -> Result<(), WriteError>;

    fn read_owned<R: AsyncRead + Unpin + Send + 'static>(
        stream: R
    ) -> Pin<Box<dyn Future<Output = Result<(R, Self), ReadError>> + Send>> { ... }
    fn try_read(
        stream: &mut impl Read,
        buf: &mut Vec<u8>
    ) -> Result<Option<Self>, ReadError> { ... }
    fn read_ws<'a, R: Stream<Item = Result<Message, Error>> + Unpin + Send + 'a>(
        stream: &'a mut R
    ) -> Pin<Box<dyn Future<Output = Result<Self, ReadError>> + Send + 'a>> { ... }
    fn write_ws<'a, W: Sink<Message, Error = Error> + Unpin + Send + 'a>(
        &'a self,
        sink: &'a mut W
    ) -> Pin<Box<dyn Future<Output = Result<(), WriteError>> + Send + 'a>>
   where
        Self: Sync,
    { ... }
    fn read_warp<'a, R: Stream<Item = Result<Message, Error>> + Unpin + Send + 'a>(
        stream: &'a mut R
    ) -> Pin<Box<dyn Future<Output = Result<Self, ReadError>> + Send + 'a>> { ... }
    fn write_warp<'a, W: Sink<Message, Error = Error> + Unpin + Send + 'a>(
        &'a self,
        sink: &'a mut W
    ) -> Pin<Box<dyn Future<Output = Result<(), WriteError>> + Send + 'a>>
   where
        Self: Sync,
    { ... }
}
Expand description

This trait allows reading a value of an implementing type from an async or sync stream, as well as writing one to an async or sync sink.

Required Methods

Reads a value of this type from an async stream.

Cancellation safety

Implementations of this method are generally not cancellation safe.

Writes a value of this type to an async sink.

Cancellation safety

Implementations of this method are generally not cancellation safe.

Reads a value of this type from a sync stream.

Writes a value of this type to a sync sink.

Provided Methods

Takes ownership of an async stream, reads a value of this type from it, then returns it along with the stream.

This can be used to get around drop glue issues that might arise with read.

Attempts to read a value of this type from a prefix in a buffer and a suffix in a sync stream.

If io::ErrorKind::WouldBlock is encountered, Ok(None) is returned and the portion read successfully is appended to buf. Otherwise, the prefix representing the returned value is removed from buf.

Callers, not implementations, should ensure that stream is non-blocking if desired.

Example
use {
    std::net::TcpStream,
    async_proto::Protocol,
};

struct Client {
    tcp_stream: TcpStream,
    buf: Vec<u8>,
}

impl Client {
    fn new(tcp_stream: TcpStream) -> Self {
        Self {
            tcp_stream,
            buf: Vec::default(),
        }
    }

    fn try_read<T: Protocol>(&mut self) -> Result<Option<T>, async_proto::ReadError> {
        self.tcp_stream.set_nonblocking(true)?;
        T::try_read(&mut self.tcp_stream, &mut self.buf)
    }

    fn write<T: Protocol>(&mut self, msg: &T) -> Result<(), async_proto::WriteError> {
        self.tcp_stream.set_nonblocking(false)?;
        msg.write_sync(&mut self.tcp_stream)
    }
}
Available on crate feature tokio-tungstenite only.

Reads a value of this type from a tokio-tungstenite websocket.

Cancellation safety

The default implementation of this method is cancellation safe.

Available on crate feature tokio-tungstenite only.

Writes a value of this type to a tokio-tungstenite websocket.

Cancellation safety

The default implementation of this method is not cancellation safe.

Available on crate feature warp only.

Reads a value of this type from a warp websocket.

Cancellation safety

The default implementation of this method is cancellation safe.

Available on crate feature warp only.

Writes a value of this type to a warp websocket.

Cancellation safety

The default implementation of this method is not cancellation safe.

Implementations on Foreign Types

A Bytes is prefixed with the length as a u64.

Using Bytes is recommended for sending large amounts of data, since the Protocol implementation for Vec<u8> reads and writes each byte individually.

A timezone is represented as an IANA timezone identifier.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

Represented as one byte, with 0 for false and 1 for true.

A vector is prefixed with the length as a u64.

Note that due to Rust’s lack of specialization, this implementation is inefficient for Vec<u8>. Prefer Bytes if possible.

A set is prefixed with the length as a u64.

A set is prefixed with the length as a u64.

A string is encoded in UTF-8 and prefixed with the length in bytes as a u64.

A map is prefixed with the length as a u64.

A map is prefixed with the length as a u64.

A cow is represented like its owned variant.

Note that due to a restriction in the type system, writing a borrowed cow requires cloning it.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

A nonzero integer is represented like its value.

Primitive number types are encoded in big-endian format.

Primitive number types are encoded in big-endian format.

A duration is represented as the number of whole seconds as a u64 followed by the number of subsecond nanoseconds as a u32.

Implementors