Unbuffered and unlocked I/O streams

19 releases (8 breaking)

0.8.0 Nov 12, 2021
0.7.0 Sep 15, 2021
0.5.0 Jul 27, 2021
0.3.0 Mar 5, 2021

#1182 in Rust patterns

Download history 82/week @ 2021-08-16 10/week @ 2021-08-23 2/week @ 2021-08-30 5/week @ 2021-09-06 34/week @ 2021-09-13 5/week @ 2021-09-20 15/week @ 2021-09-27 47/week @ 2021-10-04 41/week @ 2021-10-11 4/week @ 2021-10-18 3/week @ 2021-10-25 4/week @ 2021-11-01 44/week @ 2021-11-08 11/week @ 2021-11-15 3/week @ 2021-11-22 31/week @ 2021-11-29

90 downloads per month
Used in 2 crates

Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT



Unbuffered and unlocked I/O streams

Github Actions CI Status crates.io page docs.rs docs

This crate defines StreamReader, StreamWriter, and StreamDuplexer types which provide safe, owning, unbuffered, and unlocked access to a raw I/O stream, such as standard input, standard output, files, sockets, pipes, or character devices. It also supports a "piped thread" concept, where an arbitrary Box<dyn Read + Send> or Box<dyn Write + Send> can be provided, and the I/O is performed on a thread and connecting to the StreamReader or StreamWriter with a pipe, and a "socketed thread" concept, where a provided function is called on a thread and connected to the main thread via a bidirectional socket.

This crate also defines AsyncStreamReader, AsyncStreamWriter, and AsyncStreamDuplexer, which are async functions that work with async-std. And TokioStreamReader, TokioStreamWriter, and TokioStreamDuplexer, which are async functions that work with tokio. Not all features are supported yet, and they aren't fully optimized yet, but basic file and socket support is in place.

On Posix-ish platforms, including limited support for WASI, these types just contain a single file descriptor (and implement AsFd), plus any resources needed to safely hold the file descriptor live. On Windows, they contain an enum holding either RawHandle or RawSocket.

Since these types are unbuffered, it's advisable for most use cases to wrap them in buffering types such as std::io::BufReader, std::io::BufWriter, std::io::LineWriter, io_streams::BufDuplexer, or io_streams::BufReaderLineWriter.

Rust's std::io::Stdin and std::io::Stdout are always buffered, while its std::fs::File and std::net::TcpStream are unbuffered. A key purpose of the io_streams crate is to abstract over the underlying inputs and outputs without adding buffering, so that buffering can be applied without redundancy.

This crate locks stdio::io::Stdin and std::io::Stdout while it has their corresponding streams open, to prevent accidental mixing of buffered and unbuffered output on the same stream. Attempts to use the buffered streams when they are locked will block indefinitely.


~99K SLoC