async_io_stream

IntoAsyncRead on steroids

Provides a similar functionality as futures-util::IntoAsyncRead. This crate handles both AsyncRead and AsyncWrite for an underlying type that implements Stream and Sink. The stream needs to be a TryStream over I: AsRef<u8> and std::io::Error. The Sink must be over I: From< Vec<u8> > with the same error.

The main other difference is that we will always try to use the complete buffer(s) provided by clients. That is for poll_read, if more items are available on the Stream, we try to fill the entire buffer by using several messages. Implementations are provided for vectored io in order to use all buffers maximally, compared to the default implementation which would only take into account the first buffer.

For the Sink all data passed in is made into one item of the Sink.

AsyncBufRead is also implemented, which can be used to avoid a copy of the data when reading.

Care is taken when polling the underlying Stream several times, to send a dummy waker so the underlying Stream doesn't try to wake up the task when we didn't return Poll::Pending. This is, if we already have data to return, we can't return Poll::Pending. If the underlying Stream returns an error, we will buffer it for the next poll.

Table of Contents

• Install

  • Upgrade
  • Dependencies
  • Security

• Usage

  • Basic Example
  • API

• Contributing

  • Code of Conduct

• License

Install

With cargo add: cargo add async_io_stream

With cargo yaml:

dependencies:

   async_io_stream: ^0.3

With Cargo.toml

[dependencies]

    async_io_stream = "0.3"

Upgrade

Please check out the changelog when upgrading.

Dependencies

This crate has few dependencies. Cargo will automatically handle it's dependencies for you.

Optionally with the map_pharos feature, the Observable trait is re-implemented and forwarded to the inner type. This allows out of band error handling, as AsyncRead/AsyncWrite can only return std::io::Error and codecs will usually stop processing the transport as soon as any error is returned. This allows notifying clients of non-fatal errors or events.

When the tokio_io feature is enabled, implementation for the traits AsyncRead/AsyncWrite from tokio are provided.

Security

This crate uses #![ forbid(unsafe_code) ]. There is no maximum size protection for the buffers. The crate has not been fuzz tested as we never interprete any of the data that passes through.

Usage

Basic example

use
{
   async_io_stream :: { IoStream              } ,
   futures::io     :: { AsyncWrite, AsyncRead } ,
   futures         :: { Stream, Sink          } ,
   std             :: { io                    } ,
};

fn usage( transport: impl Stream< Item=Result<Vec<u8>, io::Error> > + Sink< Vec<u8>, Error=io::Error > + Unpin )

   -> impl AsyncRead + AsyncWrite + Unpin
{
	IoStream::new( transport )
}

API

API documentation can be found on docs.rs.

Contributing

Please check out the contribution guidelines.

Testing

Code of conduct

Any of the behaviors described in point 4 "Unacceptable Behavior" of the Citizens Code of Conduct are not welcome here and might get you banned. If anyone including maintainers and moderators of the project fail to respect these/your limits, you are entitled to call them out.

License

Unlicence