pub struct Unblock<T> { /* private fields */ }
Expand description

Runs blocking I/O on a thread pool.

Blocking I/O must be isolated from async code. This type moves blocking I/O operations onto a special thread pool while exposing a familiar async interface.

This type implements traits Stream, AsyncRead, AsyncWrite, or AsyncSeek if the inner type implements Iterator, Read, Write, or Seek, respectively.

Caveats

Unblock is a low-level primitive, and as such it comes with some caveats.

For higher-level primitives built on top of Unblock, look into async-fs or async-process (on Windows).

Unblock communicates with I/O operations on the thread pool through a pipe. That means an async read/write operation simply receives/sends some bytes from/into the pipe. When in reading mode, the thread pool reads bytes from the I/O handle and forwards them into the pipe until it becomes full. When in writing mode, the thread pool reads bytes from the pipe and forwards them into the I/O handle.

Use Unblock::with_capacity() to configure the capacity of the pipe.

Reading

If you create an Unblock<Stdin>, read some bytes from it, and then drop it, a blocked read operation may keep hanging on the thread pool. The next attempt to read from stdin will lose bytes read by the hanging operation. This is a difficult problem to solve, so make sure you only use a single stdin handle for the duration of the entire program.

Writing

If writing data through the AsyncWrite trait, make sure to flush before dropping the Unblock handle or some buffered data might get lost.

Seeking

Because of buffering in the pipe, if Unblock wraps a File, a single read operation may move the file cursor farther than is the span of the operation. In fact, reading just keeps going in the background until the pipe gets full. Keep this mind when using AsyncSeek with relative offsets.

Examples

use blocking::Unblock;
use futures_lite::prelude::*;

let mut stdout = Unblock::new(std::io::stdout());
stdout.write_all(b"Hello world!").await?;
stdout.flush().await?;

Implementations

Wraps a blocking I/O handle into the async Unblock interface.

Examples
use blocking::Unblock;

let stdin = Unblock::new(std::io::stdin());

Wraps a blocking I/O handle into the async Unblock interface with a custom buffer capacity.

When communicating with the inner Stream/Read/Write type from async code, data transferred between blocking and async code goes through a buffer of limited capacity. This constructor configures that capacity.

The default capacity is:

Examples
use blocking::Unblock;

let stdout = Unblock::with_capacity(64 * 1024, std::io::stdout());

Gets a mutable reference to the blocking I/O handle.

This is an async method because the I/O handle might be on the thread pool and needs to be moved onto the current thread before we can get a reference to it.

Examples
use blocking::{unblock, Unblock};
use std::fs::File;

let file = unblock(|| File::create("file.txt")).await?;
let mut file = Unblock::new(file);

let metadata = file.get_mut().await.metadata()?;

Performs a blocking operation on the I/O handle.

Examples
use blocking::{unblock, Unblock};
use std::fs::File;

let file = unblock(|| File::create("file.txt")).await?;
let mut file = Unblock::new(file);

let metadata = file.with_mut(|f| f.metadata()).await?;

Extracts the inner blocking I/O handle.

This is an async method because the I/O handle might be on the thread pool and needs to be moved onto the current thread before we can extract it.

Examples
use blocking::{unblock, Unblock};
use futures_lite::prelude::*;
use std::fs::File;

let file = unblock(|| File::create("file.txt")).await?;
let file = Unblock::new(file);

let file = file.into_inner().await;

Trait Implementations

Attempt to read from the AsyncRead into buf. Read more

Attempt to read from the AsyncRead into bufs using vectored IO operations. Read more

Attempt to seek to an offset, in bytes, in a stream. Read more

Attempt to write bytes from buf into the object. Read more

Attempt to flush the object, ensuring that any buffered data reach their destination. Read more

Attempt to close the object. Read more

Attempt to write bytes from bufs into the object using vectored IO operations. Read more

Formats the value using the given formatter. Read more

Values yielded by the stream.

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more

Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Reads some bytes from the byte stream. Read more

Like read(), except it reads into a slice of buffers. Read more

Reads the entire contents and appends them to a Vec. Read more

Reads the entire contents and appends them to a String. Read more

Reads the exact number of bytes required to fill buf. Read more

Creates an adapter which will read at most limit bytes from it. Read more

Converts this AsyncRead into a Stream of bytes. Read more

Creates an adapter which will chain this stream with another. Read more

Boxes the reader and changes its type to dyn AsyncRead + Send + 'a. Read more

Seeks to a new position in a byte stream. Read more

Writes some bytes into the byte stream. Read more

Like write(), except that it writes a slice of buffers. Read more

Writes an entire buffer into the byte stream. Read more

Flushes the stream to ensure that all buffered contents reach their destination. Read more

Closes the writer. Read more

Boxes the writer and changes its type to dyn AsyncWrite + Send + 'a. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

A convenience for calling Stream::poll_next() on !Unpin types.

Retrieves the next item in the stream. Read more

Retrieves the next item in the stream. Read more

Counts the number of items in the stream. Read more

Maps items of the stream to new values using a closure. Read more

Maps items to streams and then concatenates them. Read more

Concatenates inner streams. Read more

Maps items of the stream to new values using an async closure. Read more

Keeps items of the stream for which predicate returns true. Read more

Filters and maps items of the stream using a closure. Read more

Takes only the first n items of the stream. Read more

Takes items while predicate returns true. Read more

Skips the first n items of the stream. Read more

Skips items while predicate returns true. Read more

Yields every stepth item. Read more

Appends another stream to the end of this one. Read more

Clones all items. Read more

Copies all items. Read more

Collects all items in the stream into a collection. Read more

Collects all items in the fallible stream into a collection. Read more

Partitions items into those for which predicate is true and those for which it is false, and then collects them into two collections. Read more

Accumulates a computation over the stream. Read more

Accumulates a fallible computation over the stream. Read more

Maps items of the stream to new values using a state value and a closure. Read more

Fuses the stream so that it stops yielding items after the first None. Read more

Repeats the stream from beginning to end, forever. Read more

Enumerates items, mapping them to (index, item). Read more

Calls a closure on each item and passes it on. Read more

Gets the nth item of the stream. Read more

Returns the last item in the stream. Read more

Finds the first item of the stream for which predicate returns true. Read more

Applies a closure to items in the stream and returns the first Some result. Read more

Finds the index of the first item of the stream for which predicate returns true. Read more

Tests if predicate returns true for all items in the stream. Read more

Tests if predicate returns true for any item in the stream. Read more

Calls a closure on each item of the stream. Read more

Calls a fallible closure on each item of the stream, stopping on first error. Read more

Zips up two streams into a single stream of pairs. Read more

Collects a stream of pairs into a pair of collections. Read more

Merges with other stream, preferring items from self whenever both streams are ready. Read more

Merges with other stream, with no preference for either stream when both are ready. Read more

Boxes the stream and changes its type to dyn Stream + Send + 'a. Read more

Boxes the stream and changes its type to dyn Stream + 'a. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type of successful values yielded by this future

The type of failures yielded by this future

Poll this TryStream as if it were a Stream. Read more