Struct blocking::Unblock

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

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.

Notes

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

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. On the other side of the pipe, the inner I/O handle reads bytes in advance until the pipe is full, and it writes all bytes received through the pipe.

This kind of buffering has some interesting consequences. If Unblock wraps a File, note that a single read operation may move the file cursor farther than is the span of the operation! That's because reading happens in the background until the pipe gets full - blocking reads do not follow async reads byte-for-byte.

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

Examples

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

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.

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::*;
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::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.