1# blocking
2
3[![Build](https://github.com/stjepang/blocking/workflows/Build%20and%20test/badge.svg)](
4https://github.com/stjepang/blocking/actions)
5![Rustc version](https://img.shields.io/badge/rustc-1.40+-lightgray.svg)
6[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](
7https://github.com/stjepang/blocking)
8[![Cargo](https://img.shields.io/crates/v/blocking.svg)](
9https://crates.io/crates/blocking)
10[![Documentation](https://docs.rs/blocking/badge.svg)](
11https://docs.rs/blocking)
12
13A thread pool for isolating blocking I/O in async programs.
14
15Sometimes there's no way to avoid blocking I/O. Consider files or stdin, which have weak async
16support on modern operating systems. While [IOCP], [AIO], and [io_uring] are possible
17solutions, they're not always available or ideal.
18
19Since blocking is not allowed inside futures, we must move blocking I/O onto a special thread
20pool provided by this crate. The pool dynamically spawns and stops threads depending on the
21current number of running I/O jobs.
22
23Note that there is a limit on the number of active threads. Once that limit is hit, a running
24job has to finish before others get a chance to run. When a thread is idle, it waits for the
25next job or shuts down after a certain timeout.
26
27[IOCP]: https://en.wikipedia.org/wiki/Input/output_completion_port
28[AIO]: http://man7.org/linux/man-pages/man2/io_submit.2.html
29[io_uring]: https://lwn.net/Articles/776703
30
31## Examples
32
33Read the contents of a file:
34
35```rust
36use blocking::unblock;
37use futures_lite::*;
38use std::fs;
39
40let contents = unblock(|| fs::read_to_string("file.txt")).await?;
41println!("{}", contents);
42```
43
44Read a file and pipe its contents to stdout:
45
46```rust
47use blocking::{unblock, Unblock};
48use futures_lite::*;
49use std::fs::File;
50
51let input = unblock(|| File::open("file.txt")).await?;
52let input = Unblock::new(input);
53let mut output = Unblock::new(std::io::stdout());
54
55io::copy(input, &mut output).await?;
56```
57
58Iterate over the contents of a directory:
59
60```rust
61use blocking::Unblock;
62use futures_lite::*;
63use std::fs;
64
65let mut dir = Unblock::new(fs::read_dir(".")?);
66while let Some(item) = dir.next().await {
67    println!("{}", item?.file_name().to_string_lossy());
68}
69```
70
71Spawn a process:
72
73```rust
74use blocking::unblock;
75use std::process::Command;
76
77let out = unblock(|| Command::new("dir").output()).await?;
78```
79
80## License
81
82Licensed under either of
83
84 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
85 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
86
87at your option.
88
89#### Contribution
90
91Unless you explicitly state otherwise, any contribution intentionally submitted
92for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
93dual licensed as above, without any additional terms or conditions.
94