Creates a bounded single-producer single-consumer pipe.

A pipe is a ring buffer of cap bytes that implements traits AsyncRead and AsyncWrite.

When the sender is dropped, remaining bytes in the pipe can still be read. After that, attempts to read will result in Ok(0), i.e. they will always 'successfully' read 0 bytes.

When the receiver is dropped, the pipe is closed and no more bytes and be written into it. Further writes will result in Ok(0), i.e. they will always 'successfully' write 0 bytes.

Panics

If the capacity is 0, a panic will be thrown.

Examples

use futures::prelude::*;

// Write a message into the pipe.
let (mut r, mut w) = piper::pipe(1024);
w.write_all(b"hello").await?;

// Close the pipe so that the read below doesn't run forever.
drop(w);

// Read the message.
let mut msg = String::new();
r.read_to_string(&mut msg).await?;
assert_eq!(msg, "hello");