io_pipe/
lib.rs

1//! # IO Pipe Library
2//!
3//! A thread-safe library for creating multi-writer and single-reader pipelines.
4//! This library is ideal for scenarios where you need to write bytes from multiple threads and read them from a single thread.
5//!
6//! ## Features
7//!
8//! - Thread-safe communication between writers and readers
9//! - Support for both synchronous and asynchronous operations (via feature flags)
10//! - Easy-to-use API for creating pipes
11//!
12//! ## Usage
13//!
14//! ### Synchronous API
15//!
16//! Enabled by default. To disable it, disable default features in your `Cargo.toml`:
17//!
18//! ```toml
19//! [dependencies]
20//! io_pipe = { version = "*", default-features = false }
21//! ```
22//!
23//! #### Single-thread Example
24//!
25//! ```rust
26//! use std::io::{read_to_string, Write};
27//! use io_pipe::pipe;
28//!
29//! let (mut writer, reader) = pipe();
30//! writer.write_all("hello".as_bytes()).unwrap();
31//! drop(writer);
32//!
33//! assert_eq!("hello".to_string(), read_to_string(reader).unwrap());
34//! ```
35//!
36//! #### Multi-thread Example
37//!
38//! ```rust
39//! use std::io::{read_to_string, Write};
40//! use std::thread::spawn;
41//! use io_pipe::pipe;
42//!
43//! let (mut writer, reader) = pipe();
44//! spawn(move || {
45//!     writer.write_all("hello".as_bytes()).unwrap();
46//! });
47//!
48//! assert_eq!("hello".len(), read_to_string(reader).unwrap().len());
49//! ```
50//!
51//! ### Asynchronous API
52//!
53//! Enable the `async` feature in your `Cargo.toml`:
54//!
55//! ```toml
56//! [dependencies]
57//! io_pipe = { version = "*", features = ["async"] }
58//! ```
59//!
60//! #### Async Example
61//!
62//! ```rust
63//! use io_pipe::async_pipe;
64//! use futures::io::AsyncWriteExt;
65//! use futures::io::AsyncReadExt;
66//! use futures::executor::block_on;
67//!
68//! block_on(async {
69//!     let (mut writer, mut reader) = async_pipe();
70//!     
71//!     writer.write_all(b"hello").await.unwrap();
72//!     drop(writer);
73//!
74//!     let mut buffer = String::new();
75//!     reader.read_to_string(&mut buffer).await.unwrap();
76//!     assert_eq!("hello", buffer);
77//! })
78//! ```
79//!
80//! #### Sync to Async Example
81//!
82//! ```rust
83//! use io_pipe::async_reader_pipe;
84//! use std::io::Write;
85//! use futures::io::AsyncReadExt;
86//! use futures::executor::block_on;
87//!
88//! let (mut writer, mut reader) = async_reader_pipe();
89//! writer.write_all(b"hello").unwrap();
90//! drop(writer);
91//!
92//! block_on(async {
93//!     let mut buffer = String::new();
94//!     reader.read_to_string(&mut buffer).await.unwrap();
95//!     assert_eq!("hello", buffer);
96//! })
97//! ```
98//!
99//! #### Async to Sync Example
100//!
101//! ```rust
102//! use io_pipe::async_writer_pipe;
103//! use std::io::Read;
104//! use futures::io::AsyncWriteExt;
105//! use futures::executor::block_on;
106//!
107//! let (mut writer, mut reader) = async_writer_pipe();
108//!
109//! block_on(async {
110//!     writer.write_all(b"hello").await.unwrap();
111//!     drop(writer);
112//! });
113//!
114//! let mut buffer = String::new();
115//! reader.read_to_string(&mut buffer).unwrap();
116//! assert_eq!("hello", buffer);
117//! ```
118//!
119//! ## API Documentation
120//!
121//! For detailed API documentation, please refer to the individual module documentation:
122//!
123//! - [`pipe`], [`Writer`], and [`Reader`] for synchronous operations
124//! - [`async_pipe`], [`AsyncWriter`], and [`AsyncReader`] for asynchronous operations
125
126#[cfg(feature = "async")]
127pub use async_pipe::{AsyncReader, AsyncWriter, async_pipe};
128#[cfg(feature = "async")]
129#[cfg(feature = "sync")]
130pub use async_pipe::{async_reader_pipe, async_writer_pipe};
131#[cfg(feature = "sync")]
132pub use sync_pipe::{Reader, Writer, pipe};
133
134#[cfg(feature = "async")]
135mod async_pipe;
136mod state;
137#[cfg(feature = "sync")]
138mod sync_pipe;
io_pipe/lib.rs

io_pipe/
lib.rs
