I/O-free filesystem client library written in Rust
This library provides an I/O-agnostic abstraction over filesystem operations — reading, writing, copying, renaming, and removing files and directories — based on three concepts:
A coroutine is an I/O-free, resumable and composable state machine. It emits I/O requests without performing any I/O itself, and receives I/O responses to make progress. A coroutine is terminated when it stops emitting I/O requests.
See available coroutines at ./src/coroutines.
A runtime contains all the I/O logic. It is responsible for processing I/O requests and returning the corresponding I/O responses. A runtime targets a specific execution model (blocking std, async Tokio).
See available runtimes at ./src/runtimes.
The loop is the glue between coroutines and runtimes. It drives the coroutine forward by feeding each FsOutput back as the next argument, until the coroutine terminates.
use io_fs::{
coroutines::dir_read::{FsDirRead, FsDirReadResult},
runtimes::std::handle,
};
let mut arg = None;
let mut read = FsDirRead::new(["/tmp"]);
let entries = loop {
match read.resume(arg.take()) {
FsDirReadResult::Ok(entries) => break entries,
FsDirReadResult::Io(input) => arg = Some(handle(input).unwrap()),
FsDirReadResult::Err(err) => panic!("{err}"),
}
};
for (dir, children) in &entries {
for path in children {
println!("{path}");
}
}use io_fs::{
coroutines::file_create::{FsFileCreate, FsFileCreateResult},
runtimes::tokio::handle,
};
let mut arg = None;
let mut create = FsFileCreate::new([("/tmp/hello.txt", *b"Hello, world!")]);
loop {
match create.resume(arg.take()) {
FsFileCreateResult::Ok => break,
FsFileCreateResult::Io(input) => arg = Some(handle(input).await.unwrap()),
FsFileCreateResult::Err(err) => panic!("{err}"),
}
}See complete examples at ./examples.
Have a look at projects built on top of this library:
- io-vdir: I/O-free coroutines to manage Vdir filesystems
- io-addressbook: I/O-free coroutines to manage contacts
- io-maildir: I/O-free coroutines to manage Maildir folders
- Cardamum: CLI to manage contacts
This project is licensed under either of:
at your option.
- Chat on Matrix
- News on Mastodon or RSS
- Mail at pimalaya.org@posteo.net
Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:
- 2022: NGI Assure
- 2023: NGI Zero Entrust
- 2024: NGI Zero Core (still ongoing in 2026)
If you appreciate the project, feel free to donate using one of the following providers:
