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