Struct Unblock

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

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

impl<T> Unblock<T>

pub fn new(io: T) -> Unblock<T>

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

Examples

use blocking::Unblock;

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

pub fn with_capacity(cap: usize, io: T) -> Unblock<T>

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:

• For Iterator types: 8192 items.
• For Read/Write types: 8 MB.

Examples

use blocking::Unblock;

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

pub async fn get_mut(&mut self) -> &mut T

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()?;

pub async fn with_mut<R, F>(&mut self, op: F) -> R

where F: FnOnce(&mut T) -> R + Send + 'static, R: Send + 'static, T: Send + 'static,

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?;

pub async fn into_inner(self) -> T

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

impl<T: Read + Send + 'static> AsyncRead for Unblock<T>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

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

impl<T: Seek + Send + 'static> AsyncSeek for Unblock<T>

fn poll_seek( self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom, ) -> Poll<Result<u64>>

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

impl<T: Write + Send + 'static> AsyncWrite for Unblock<T>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

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

impl<T: Debug> Debug for Unblock<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Iterator + Send + 'static> Stream for Unblock<T>

where T::Item: Send + 'static,

type Item = <T as Iterator>::Item

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<T::Item>>

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.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.