2020-05-09 19:06:27 +00:00
|
|
|
# blocking
|
|
|
|
|
2020-12-26 14:47:13 +00:00
|
|
|
[![Build](https://github.com/smol-rs/blocking/workflows/Build%20and%20test/badge.svg)](
|
|
|
|
https://github.com/smol-rs/blocking/actions)
|
2021-02-14 04:38:00 +00:00
|
|
|
[![License](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](
|
2020-12-26 14:47:13 +00:00
|
|
|
https://github.com/smol-rs/blocking)
|
2020-05-09 19:06:27 +00:00
|
|
|
[![Cargo](https://img.shields.io/crates/v/blocking.svg)](
|
|
|
|
https://crates.io/crates/blocking)
|
|
|
|
[![Documentation](https://docs.rs/blocking/badge.svg)](
|
|
|
|
https://docs.rs/blocking)
|
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
A thread pool for isolating blocking I/O in async programs.
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
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.
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-05-10 11:19:28 +00:00
|
|
|
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.
|
2020-05-09 19:06:27 +00:00
|
|
|
|
|
|
|
Note that there is a limit on the number of active threads. Once that limit is hit, a running
|
2020-05-10 11:19:28 +00:00
|
|
|
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.
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2021-10-02 10:51:50 +00:00
|
|
|
The default number of threads (set to 500) can be altered by setting BLOCKING_MAX_THREADS environment variable with value between 1 and 10000.
|
|
|
|
|
2020-05-09 19:06:27 +00:00
|
|
|
[IOCP]: https://en.wikipedia.org/wiki/Input/output_completion_port
|
|
|
|
[AIO]: http://man7.org/linux/man-pages/man2/io_submit.2.html
|
2020-07-21 18:41:03 +00:00
|
|
|
[io_uring]: https://lwn.net/Articles/776703
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-05-17 13:09:42 +00:00
|
|
|
## Examples
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
Read the contents of a file:
|
2020-05-09 19:06:27 +00:00
|
|
|
|
|
|
|
```rust
|
2020-07-21 18:41:03 +00:00
|
|
|
use blocking::unblock;
|
|
|
|
use std::fs;
|
|
|
|
|
2020-08-13 18:52:06 +00:00
|
|
|
let contents = unblock(|| fs::read_to_string("file.txt")).await?;
|
2020-07-21 18:41:03 +00:00
|
|
|
println!("{}", contents);
|
2020-05-09 19:06:27 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Read a file and pipe its contents to stdout:
|
|
|
|
|
|
|
|
```rust
|
2020-08-04 20:27:40 +00:00
|
|
|
use blocking::{unblock, Unblock};
|
2020-10-09 12:25:10 +00:00
|
|
|
use futures_lite::io;
|
2020-05-09 19:06:27 +00:00
|
|
|
use std::fs::File;
|
|
|
|
|
2020-08-13 18:52:06 +00:00
|
|
|
let input = unblock(|| File::open("file.txt")).await?;
|
2020-08-04 20:27:40 +00:00
|
|
|
let input = Unblock::new(input);
|
2020-07-21 18:41:03 +00:00
|
|
|
let mut output = Unblock::new(std::io::stdout());
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
io::copy(input, &mut output).await?;
|
2020-05-09 19:06:27 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Iterate over the contents of a directory:
|
|
|
|
|
|
|
|
```rust
|
2020-07-21 18:41:03 +00:00
|
|
|
use blocking::Unblock;
|
2020-10-09 12:25:10 +00:00
|
|
|
use futures_lite::prelude::*;
|
2020-07-19 15:53:46 +00:00
|
|
|
use std::fs;
|
2020-05-17 13:08:26 +00:00
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
let mut dir = Unblock::new(fs::read_dir(".")?);
|
|
|
|
while let Some(item) = dir.next().await {
|
|
|
|
println!("{}", item?.file_name().to_string_lossy());
|
|
|
|
}
|
2020-05-17 13:08:26 +00:00
|
|
|
```
|
|
|
|
|
2020-07-21 18:41:03 +00:00
|
|
|
Spawn a process:
|
2020-05-17 13:08:26 +00:00
|
|
|
|
|
|
|
```rust
|
2020-07-21 18:41:03 +00:00
|
|
|
use blocking::unblock;
|
|
|
|
use std::process::Command;
|
2020-05-09 19:06:27 +00:00
|
|
|
|
2020-08-13 18:52:06 +00:00
|
|
|
let out = unblock(|| Command::new("dir").output()).await?;
|
2020-05-09 19:06:27 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
Licensed under either of
|
|
|
|
|
|
|
|
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
|
|
|
|
|
|
|
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.
|