Struct io_streams::BufDuplexer

pub struct BufDuplexer<Inner: HalfDuplex> { /* private fields */ }

Wraps a reader and writer and buffers their output.

It can be excessively inefficient to work directly with something that implements Write. For example, every call to write on TcpStream results in a system call. A BufDuplexer<Inner> keeps an in-memory buffer of data and writes it to an underlying writer in large, infrequent batches.

It can be excessively inefficient to work directly with a Read instance. For example, every call to read on TcpStream results in a system call. A BufDuplexer<Inner> performs large, infrequent reads on the underlying Read and maintains an in-memory buffer of the results.

BufDuplexer<Inner> can improve the speed of programs that make small and repeated write calls to the same file or network socket. It does not help when writing very large amounts at once, or writing just one or a few times. It also provides no advantage when writing to a destination that is in memory, like a Vec<u8>.

BufDuplexer<Inner> can improve the speed of programs that make small and repeated read calls to the same file or network socket. It does not help when reading very large amounts at once, or reading just one or a few times. It also provides no advantage when reading from a source that is already in memory, like a Vec<u8>.

It is critical to call flush before BufDuplexer<Inner> is dropped. Though dropping will attempt to flush the contents of the writer buffer, any errors that happen in the process of dropping will be ignored. Calling flush ensures that the writer buffer is empty and thus dropping will not even attempt file operations.

When the BufDuplexer<Inner> is dropped, the contents of its reader buffer will be discarded. Creating multiple instances of a BufDuplexer<Inner> on the same stream can cause data loss. Reading from the underlying reader after unwrapping the BufDuplexer<Inner> with BufDuplexer::into_inner can also cause data loss.

Examples

Let’s write the numbers one through ten to a TcpStream:

use std::io::prelude::*;
use std::net::TcpStream;

let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

for i in 0..10 {
    stream.write(&[i + 1]).unwrap();
}

Because we’re not buffering, we write each one in turn, incurring the overhead of a system call per byte written. We can fix this with a BufDuplexer<Inner>:

use io_streams::BufDuplexer;
use std::io::prelude::*;
use std::net::TcpStream;

let mut stream = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

for i in 0..10 {
    stream.write(&[i + 1]).unwrap();
}
stream.flush().unwrap();

By wrapping the stream with a BufDuplexer<Inner>, these ten writes are all grouped together by the buffer and will all be written out in one system call when the stream is flushed.

use io_streams::BufDuplexer;
use std::io::prelude::*;
use std::net::TcpStream;

fn main() -> std::io::Result<()> {
    let mut stream = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

    let mut line = String::new();
    let len = stream.read_line(&mut line)?;
    println!("First line is {} bytes long", len);
    Ok(())
}

Implementations

impl<Inner: HalfDuplex> BufDuplexer<Inner>

pub fn new(inner: Inner) -> Self

Creates a new BufDuplexer<Inner> with default buffer capacities. The default is currently 8 KB, but may change in the future.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let mut buffer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

pub fn with_capacities( reader_capacity: usize, writer_capacity: usize, inner: Inner ) -> Self

Creates a new BufDuplexer<Inner> with the specified buffer capacities.

Examples

Creating a buffer with ten bytes of reader capacity and a writer buffer of a hundered bytes:

use io_streams::BufDuplexer;
use std::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
let mut buffer = BufDuplexer::with_capacities(10, 100, stream);

pub fn get_ref(&self) -> &Inner

Gets a reference to the underlying reader/writer.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let mut buffer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// we can use reference just like buffer
let reference = buffer.get_ref();

pub fn get_mut(&mut self) -> &mut Inner

Gets a mutable reference to the underlying reader/writer.

It is inadvisable to directly write to the underlying reader/writer.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let mut buffer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// we can use reference just like buffer
let reference = buffer.get_mut();

pub fn writer_buffer(&self) -> &[u8]

Returns a reference to the internally buffered writer data.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let buf_writer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// See how many bytes are currently buffered
let bytes_buffered = buf_writer.writer_buffer().len();

pub fn reader_buffer(&self) -> &[u8]

Returns a reference to the internally buffered reader data.

Unlike fill_buf, this will not attempt to fill the buffer if it is empty.

Examples

use char_device::CharDevice;
use io_streams::BufDuplexer;
use std::fs::File;
use std::io::BufRead;

fn main() -> std::io::Result<()> {
    let f = CharDevice::new(File::open("/dev/ttyS0")?)?;
    let mut reader = BufDuplexer::new(f);
    assert!(reader.reader_buffer().is_empty());

    if reader.fill_buf()?.len() > 0 {
        assert!(!reader.reader_buffer().is_empty());
    }
    Ok(())
}

pub fn writer_capacity(&self) -> usize

Returns the number of bytes the internal writer buffer can hold without flushing.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let buf_duplexer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// Check the capacity of the inner buffer
let capacity = buf_duplexer.writer_capacity();
// Calculate how many bytes can be written without flushing
let without_flush = capacity - buf_duplexer.writer_buffer().len();

pub fn reader_capacity(&self) -> usize

Returns the number of bytes the internal reader buffer can hold at once.

Examples

use char_device::CharDevice;
use io_streams::BufDuplexer;
use std::fs::File;
use std::io::BufRead;

fn main() -> std::io::Result<()> {
    let f = CharDevice::new(File::open("/dev/tty")?)?;
    let mut reader = BufDuplexer::new(f);

    let capacity = reader.reader_capacity();
    let buffer = reader.fill_buf()?;
    assert!(buffer.len() <= capacity);
    Ok(())
}

pub fn into_inner(self) -> Result<Inner, IntoInnerError<Self>>

Unwraps this BufDuplexer<Inner>, returning the underlying reader/writer.

The buffer is written out before returning the reader/writer.

Errors

An Err will be returned if an error occurs while flushing the buffer.

Examples

use io_streams::BufDuplexer;
use std::net::TcpStream;

let mut buffer = BufDuplexer::new(TcpStream::connect("127.0.0.1:34254").unwrap());

// unwrap the TcpStream and flush the buffer
let stream = buffer.into_inner().unwrap();

Trait Implementations

impl<Inner: HalfDuplex + AsFd> AsFd for BufDuplexer<Inner>

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl<Inner: HalfDuplex + AsRawFd> AsRawFd for BufDuplexer<Inner>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<Inner: HalfDuplex> BufRead for BufDuplexer<Inner>

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(&mut self, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes into buf until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Check if the underlying Read has any data left to be read.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

🔬This is a nightly-only experimental API. (bufread_skip_until)

Skip all bytes until the delimiter byte or EOF is reached.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<Inner> Debug for BufDuplexer<Inner>

where Inner: Debug + HalfDuplex,

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

Formats the value using the given formatter.

impl<Inner: HalfDuplex> Read for BufDuplexer<Inner>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<Inner: HalfDuplex> Write for BufDuplexer<Inner>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.