Block on async code or await blocking code.
To convert async to blocking, block on async code with block_on(), block_on!, or
BlockOn.
To convert blocking to async, unblock blocking code with unblock(), unblock!, or
Unblock.
Sometimes there's no way to avoid blocking I/O in async programs. 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.
Await a blocking file read with unblock!:
```rust use blocking::{block_on, unblock}; use std::{fs, io};
blockon(async { let contents = unblock!(fs::readto_string("file.txt"))?; println!("{}", contents); io::Result::Ok(()) }); ```
Read a file and pipe its contents to stdout:
```rust use blocking::{blockon, Unblock}; use futureslite::*; use std::fs::File;
block_on(async { let input = Unblock::new(File::open("file.txt")?); let mut output = Unblock::new(std::io::stdout());
io::copy(input, &mut output).await?;
io::Result::Ok(())
}); ```
Iterate over the contents of a directory:
```rust use blocking::{blockon, Unblock}; use futureslite::*; use std::fs;
blockon(async { let mut dir = Unblock::new(fs::readdir(".")?); while let Some(item) = dir.next().await { println!("{}", item?.filename().tostring_lossy()); } io::Result::Ok(()) }); ```
Convert a stream into an iterator:
```rust use blocking::BlockOn; use futures_lite::*;
let stream = stream::once(7); let mut iter = BlockOn::new(Box::pin(stream));
asserteq!(iter.next(), Some(7)); asserteq!(iter.next(), None); ```
Licensed under either of
at your option.
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.