#thread-safe #pipe #io #async-io #io-write #reader-writer #single-reader

io-pipe

A fast and thread-safe library for creating multi-writer and single-reader pipelines in Rust

14 releases (5 breaking)

0.6.2 Aug 15, 2024
0.6.1 Aug 15, 2024
0.5.2 Aug 15, 2024
0.4.0 Aug 9, 2024
0.1.2 Aug 7, 2024

#567 in Asynchronous

Download history 479/week @ 2024-08-05 629/week @ 2024-08-12 7/week @ 2024-08-26 13/week @ 2024-09-16 20/week @ 2024-09-23 3/week @ 2024-09-30

510 downloads per month

MIT license

32KB
558 lines

IO Pipe Library

Crates.io Version GitHub Actions Workflow Status docs.rs Crates.io License

IO Pipe is a thread-safe Rust library for creating multi-writer and single-reader pipelines. It's ideal for scenarios where you need to write bytes from multiple threads and read them from a single thread.

Features

  • Thread-safe communication between writers and readers
  • Support for both synchronous and asynchronous operations (via feature flags)
  • Easy-to-use API for creating pipes

Installation

Add this to your Cargo.toml:

[dependencies]
io-pipe = "0.x.x"

For async support, enable the async feature:

[dependencies]
io-pipe = { version = "0.x.x", features = ["async"] }

Usage

Synchronous API

Single-thread example:

use std::io::{read_to_string, Write};
use io_pipe::pipe;

fn main() {
    let (mut writer, reader) = pipe();
    writer.write_all("hello".as_bytes()).unwrap();
    drop(writer);

    assert_eq!("hello".to_string(), read_to_string(reader).unwrap());
}

Multi-thread example:

use std::io::{read_to_string, Write};
use std::thread::spawn;
use io_pipe::pipe;

fn main() {
    let (mut writer, reader) = pipe();
    spawn(move || {
        writer.write_all("hello".as_bytes()).unwrap();
    });

    assert_eq!("hello".len(), read_to_string(reader).unwrap().len());
}

Asynchronous API

use io_pipe::async_pipe;
use futures::io::{AsyncWriteExt, AsyncReadExt};
use futures::executor::block_on;

fn main() {
    block_on(async {
        let (mut writer, mut reader) = async_pipe();

        writer.write_all(b"hello").await.unwrap();
        drop(writer);

        let mut buffer = String::new();
        reader.read_to_string(&mut buffer).await.unwrap();
        assert_eq!("hello", buffer);
    });
}

Sync to Async Example

use io_pipe::async_reader_pipe;
use std::io::Write;
use futures::io::AsyncReadExt;
use futures::executor::block_on;

fn main() {
    let (mut writer, mut reader) = async_reader_pipe();
    writer.write_all(b"hello").unwrap();
    drop(writer);

    block_on(async {
        let mut buffer = String::new();
        reader.read_to_string(&mut buffer).await.unwrap();
        assert_eq!("hello", buffer);
    })
}

Async to Sync Example

use io_pipe::async_writer_pipe;
use std::io::Read;
use futures::io::AsyncWriteExt;
use futures::executor::block_on;

fn main() {
    let (mut writer, mut reader) = async_writer_pipe();

    block_on(async {
        writer.write_all(b"hello").await.unwrap();
        drop(writer);
    });

    let mut buffer = String::new();
    reader.read_to_string(&mut buffer).unwrap();
    assert_eq!("hello", buffer);
}

Documentation

For detailed API documentation, please refer to docs.rs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines:

  1. Use rustfmt to format your code.
  2. Run clippy and address any lints before submitting your PR.
  3. Write tests for new functionality.
  4. Update documentation as necessary.

License

This project is licensed under MIT - see the LICENSE file for details.

Dependencies

~61KB