https://github.com/sunfishcode/io-streams

Unbuffered and unlocked I/O streams
https://github.com/sunfishcode/io-streams

descriptor pipes rust sockets streams

Last synced: 14 days ago
JSON representation

Unbuffered and unlocked I/O streams

• Host: GitHub
• URL: https://github.com/sunfishcode/io-streams
• Owner: sunfishcode
• License: other
• Created: 2020-12-15T15:24:31.000Z (almost 4 years ago)
• Default Branch: main
• Last Pushed: 2024-08-24T01:48:48.000Z (3 months ago)
• Last Synced: 2024-10-25T00:18:47.230Z (20 days ago)
• Topics: descriptor, pipes, rust, sockets, streams
• Language: Rust
• Homepage:
• Size: 188 KB
• Stars: 39
• Watchers: 6
• Forks: 4
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md

Awesome Lists containing this project

README

        


  
io-streams


  


    Unbuffered and unlocked I/O streams

  


  


    

    

    

  



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` or `Box` 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.

Support for async-std and tokio in char-device and socketpair is temporarily

disabled until those crates contain the needed implementations of the

I/O safety traits.

[`StreamReader`]: https://docs.rs/io-streams/latest/io_streams/struct.StreamReader.html

[`StreamWriter`]: https://docs.rs/io-streams/latest/io_streams/struct.StreamWriter.html

[`StreamDuplexer`]: https://docs.rs/io-streams/latest/io_streams/struct.StreamDuplexer.html

[`AsyncStreamReader`]: https://docs.rs/io-streams/latest/io_streams/struct.AsyncStreamReader.html

[`AsyncStreamWriter`]: https://docs.rs/io-streams/latest/io_streams/struct.AsyncStreamWriter.html

[`AsyncStreamDuplexer`]: https://docs.rs/io-streams/latest/io_streams/struct.AsyncStreamDuplexer.html

[`TokioStreamReader`]: https://docs.rs/io-streams/latest/io_streams/struct.TokioStreamReader.html

[`TokioStreamWriter`]: https://docs.rs/io-streams/latest/io_streams/struct.TokioStreamWriter.html

[`TokioStreamDuplexer`]: https://docs.rs/io-streams/latest/io_streams/struct.TokioStreamDuplexer.html

[`io_streams::BufDuplexer`]: https://docs.rs/io-streams/latest/io_streams/struct.BufDuplexer.html

[`io_streams::BufReaderLineWriter`]: https://docs.rs/io-streams/latest/io_streams/struct.BufReaderLineWriter.html

[`std::io::Stdin`]: https://doc.rust-lang.org/std/io/struct.Stdin.html

[`std::io::Stdout`]: https://doc.rust-lang.org/std/io/struct.Stdout.html

[`std::io::BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html

[`std::io::BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html

[`std::io::LineWriter`]: https://doc.rust-lang.org/std/io/struct.LineWriter.html

[`AsFd`]: https://docs.rs/io-lifetimes/0.2.0/io_lifetimes/trait.AsFd.html

[pipe]: https://crates.io/crates/os_pipe

[`std::fs::File`]: https://doc.rust-lang.org/std/fs/struct.File.html

[`std::net::TcpStream`]: https://doc.rust-lang.org/std/net/struct.TcpStream.html