#async #file #stdio #stdin #process

blocking

A thread pool for isolating blocking I/O in async programs

21 releases (3 stable)

1.0.2 Oct 9, 2020
1.0.0 Sep 7, 2020
0.6.1 Aug 28, 2020
0.5.0 Jul 21, 2020
0.1.0 Jun 15, 2019

#8 in Asynchronous

Download history 20490/week @ 2020-06-28 23463/week @ 2020-07-05 25782/week @ 2020-07-12 32607/week @ 2020-07-19 33136/week @ 2020-07-26 34870/week @ 2020-08-02 35858/week @ 2020-08-09 36773/week @ 2020-08-16 38270/week @ 2020-08-23 33363/week @ 2020-08-30 37961/week @ 2020-09-06 47646/week @ 2020-09-13 42049/week @ 2020-09-20 44266/week @ 2020-09-27 48103/week @ 2020-10-04 48218/week @ 2020-10-11

160,548 downloads per month
Used in 707 crates (20 directly)

Apache-2.0 OR MIT

48KB
609 lines

blocking

Build Rustc version License Cargo Documentation

A thread pool for isolating blocking I/O in async programs.

Sometimes there's no way to avoid blocking I/O. Consider files or stdin, which have weak async support on modern operating systems. While IOCP, AIO, and io_uring are possible solutions, they're not always available or ideal.

Since blocking is not allowed inside futures, we must move blocking I/O onto a special thread pool provided by this crate. The pool dynamically spawns and stops threads depending on the current number of running I/O jobs.

Note that there is a limit on the number of active threads. Once that limit is hit, a running job has to finish before others get a chance to run. When a thread is idle, it waits for the next job or shuts down after a certain timeout.

Examples

Read the contents of a file:

use blocking::unblock;
use std::fs;

let contents = unblock(|| fs::read_to_string("file.txt")).await?;
println!("{}", contents);

Read a file and pipe its contents to stdout:

use blocking::{unblock, Unblock};
use futures_lite::io;
use std::fs::File;

let input = unblock(|| File::open("file.txt")).await?;
let input = Unblock::new(input);
let mut output = Unblock::new(std::io::stdout());

io::copy(input, &mut output).await?;

Iterate over the contents of a directory:

use blocking::Unblock;
use futures_lite::prelude::*;
use std::fs;

let mut dir = Unblock::new(fs::read_dir(".")?);
while let Some(item) = dir.next().await {
    println!("{}", item?.file_name().to_string_lossy());
}

Spawn a process:

use blocking::unblock;
use std::process::Command;

let out = unblock(|| Command::new("dir").output()).await?;

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~595KB