Crate futures_copy 

futures-copy

Copy data from an AsyncRead to an AsyncWrite, or between a pair of AsyncRead + AsyncWrite streams.

(If you’re using tokio only, you probably don’t need this; you can probably use one of the tokio::io::copy functions instead.)

Differences from other copys

This crate works with the AsyncRead and AsyncWrite traits from the futures crate.

Unlike futures::io::copy and some of the copy methods in tokio, the code in this crate flushes the writer whenever the reader returns Pending, and so is suitable for use in more cases: this behavior ensures that data does not wait forever on writers with internal buffering.

futures-copy ensures that the writer is flushed whenever the reader has returned Pending.

futures-copy doesn’t require reader and writer types to be Unpin, and allows readers and writers to be given either by value or by mutable reference.

futures-copy lets you control the way in which an EOF received on one stream is copied to the other (e.g., via AsyncWriteExt::close, TcpStream::shutdown, or some other means.)

Limitations

The io::Error that’s returned by the functions in futures-copy is not exactly the same io::Error that caused the copy operation to fail. Instead, it wraps the source error in an Arc, We do this because, in Rust, std::io::Error doesn’t implement Clone.

Although futures-copy returns the amount of data transferred on success, it does not report this information on error.

If an error occurs while reading data, futures_copy tries to ensure that the writer is flushed before it returns that error. This may delay receipt of the error message.

Example

use futures_copy::{copy_bidirectional, eof};

// Copy data between stream_a and stream_b, in both directions,
// flushing as appropriate.
// As soon as we reach EOF on either stream, close the other.
copy_bidirectional(
   stream_a, stream_b,
   eof::Close, eof::Close
).await?;

Acknowledgments

The API is loosely based on the API of tokio’s io::copy* functions, (copy_buf, copy, and copy_bidirectional), ported for use outside tokio. The implementation strategy is loosely based on the implementation strategy of futures’s io::copy methods (copy and copy_buf). It should be mostly usable as a drop-in replacement for those functions.

License: MIT OR Apache-2.0

Re-exports

pub use eof::EofStrategy;

Modules

eof

Support for defining behavior when encountering an EOF during a bidirectional copy.

Structs

Copy

A future returned by copy.

CopyBidirectional

A future returned by copy_bidirectional.

CopyBuf

A future returned by copy_buf.

CopyBufBidirectional

A future returned by copy_buf_bidirectional.

Functions

copy

Return a future to copy bytes from reader to writer.

copy_bidirectional

Return a future to copies bytes from stream_a to stream_b, and from stream_b to stream_a.

copy_buf

Return a future to copy all bytes interactively from reader to writer.

copy_buf_bidirectional

Return a future to copies bytes from stream_a to stream_b, and from stream_b to stream_a.