I/O Stream

Set of I/O-free Rust coroutines and runtimes to manage streams.

This library allows you to manage streams using an I/O-agnostic approach, based on 3 concepts:

Coroutine

A coroutine is an I/O-free, resumable and composable state machine that emits I/O requests. A coroutine is considered terminated when it does not emit I/O requests anymore.

See available coroutines at ./src/coroutines.

Runtime

A runtime contains all the I/O logic, and is responsible for processing I/O requests emitted by coroutines.

See available runtimes at ./src/runtimes.

Loop

The loop is the glue between coroutines and runtimes. It makes the coroutine progress while allowing runtime to process I/O.

Examples

See complete examples at ./examples.

Read stdin synchronously

use io_stream::{coroutines::Read, runtimes::std::handle};

let mut stdin = std::io::stdin();

let mut arg = None;
let mut read = Read::new();

let output = loop {
    match read.resume(arg) {
        Ok(output) => break output,
        Err(io) => arg = Some(handle(&mut stdin, io).unwrap()),
    }
};

// same as &output.buffer[..output.bytes_count]
let bytes = output.bytes();

Write TCP stream asynchronously

use tokio::net::TcpStream;
use io_stream::{coroutines::Write, runtimes::tokio::handle};

let mut tcp = TcpStream::connect("127.0.0.1:1234").await.unwrap();

let mut arg = None;
let mut write = Write::new(b"bytes".iter().cloned());

while let Err(io) = write.resume(arg) {
    arg = Some(handle(&mut tcp, io).await.unwrap());
}

More examples

Have a look at projects built on the top of this library:

io-starttls: I/O-free coroutine to upgrade any plain stream to a secure one
io-timer: Set of I/O-free coroutines to manage timers
io-http: Set of I/O-free Rust coroutines to manage HTTP streams
io-oauth: Set of I/O-free Rust coroutines to manage OAuth flows
io-addressbook: Set of I/O-free coroutines to manage contacts
comodoro: CLI to manage timers
cardamum: CLI to manage contacts
ortie: CLI to manage OAuth access tokens

Sponsoring

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

NGI Assure in 2022
NGI Zero Entrust in 2023
NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers:

io-stream 0.0.1