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 std::fs; 38 39let contents = unblock(|| fs::read_to_string("file.txt")).await?; 40println!("{}", contents); 41``` 42 43Read a file and pipe its contents to stdout: 44 45```rust 46use blocking::{unblock, Unblock}; 47use futures_lite::io; 48use std::fs::File; 49 50let input = unblock(|| File::open("file.txt")).await?; 51let input = Unblock::new(input); 52let mut output = Unblock::new(std::io::stdout()); 53 54io::copy(input, &mut output).await?; 55``` 56 57Iterate over the contents of a directory: 58 59```rust 60use blocking::Unblock; 61use futures_lite::prelude::*; 62use std::fs; 63 64let mut dir = Unblock::new(fs::read_dir(".")?); 65while let Some(item) = dir.next().await { 66 println!("{}", item?.file_name().to_string_lossy()); 67} 68``` 69 70Spawn a process: 71 72```rust 73use blocking::unblock; 74use std::process::Command; 75 76let out = unblock(|| Command::new("dir").output()).await?; 77``` 78 79## License 80 81Licensed under either of 82 83 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) 84 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) 85 86at your option. 87 88#### Contribution 89 90Unless you explicitly state otherwise, any contribution intentionally submitted 91for inclusion in the work by you, as defined in the Apache-2.0 license, shall be 92dual licensed as above, without any additional terms or conditions. 93