Struct io_streams::BufDuplexer[−][src]

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

Expand description

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::*, 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::*, 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::*, 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>[src]

pub fn new(inner: Inner) -> Self[src]

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

Struct io_streams::BufDuplexer[−][src]

Implementations

Trait Implementations

Auto Trait Implementations

Blanket Implementations