Struct blocking::Unblock [−][src]
pub struct Unblock<T> { /* fields omitted */ }
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 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 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
Auto Trait Implementations
impl<T> !RefUnwindSafe for Unblock<T>
impl<T> !UnwindSafe for Unblock<T>
Blanket Implementations
Reads some bytes from the byte stream. Read more
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
fn read_vectored(
&'a mut self,
bufs: &'a mut [IoSliceMut<'a>]
) -> ReadVectoredFuture<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
fn read_to_end(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEndFuture<'a, Self> where
Self: Unpin,
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
fn read_to_string(
&'a mut self,
buf: &'a mut String
) -> ReadToStringFuture<'a, Self> where
Self: Unpin,
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
Creates an adapter which will chain this stream with another. Read more
Writes some bytes into the byte stream. Read more
fn write_vectored(
&'a mut self,
bufs: &'a [IoSlice<'a>]
) -> WriteVectoredFuture<'a, Self> where
Self: Unpin,
fn write_vectored(
&'a mut self,
bufs: &'a [IoSlice<'a>]
) -> WriteVectoredFuture<'a, Self> where
Self: Unpin,
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
Mutably borrows from an owned value. Read more
A convenience for calling [Stream::poll_next()
] on !
Unpin
types.
Retrieves the next item in the stream. Read more
fn try_next<T, E>(&mut self) -> TryNextFuture<'_, Self> where
Self: Stream<Item = Result<T, E>> + Unpin,
fn try_next<T, E>(&mut self) -> TryNextFuture<'_, Self> where
Self: Stream<Item = Result<T, E>> + Unpin,
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
fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where
P: FnMut(&Self::Item) -> bool,
fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where
P: FnMut(&Self::Item) -> bool,
Takes items while predicate
returns true
. Read more
fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where
P: FnMut(&Self::Item) -> bool,
fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where
P: FnMut(&Self::Item) -> bool,
Skips items while predicate
returns true
. 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
fn try_collect<T, E, C>(self) -> TryCollectFuture<Self, C> where
Self: Stream<Item = Result<T, E>>,
C: Default + Extend<T>,
fn try_collect<T, E, C>(self) -> TryCollectFuture<Self, C> where
Self: Stream<Item = Result<T, E>>,
C: Default + Extend<T>,
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
fn fold<T, F>(self, init: T, f: F) -> FoldFuture<Self, F, T> where
F: FnMut(T, Self::Item) -> T,
fn fold<T, F>(self, init: T, f: F) -> FoldFuture<Self, F, T> where
F: FnMut(T, Self::Item) -> T,
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
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 n
th 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
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
fn try_for_each<F, E>(&mut self, f: F) -> TryForEachFuture<'_, Self, F> where
Self: Unpin,
F: FnMut(Self::Item) -> Result<(), E>,
fn try_for_each<F, E>(&mut self, f: F) -> TryForEachFuture<'_, Self, F> where
Self: Unpin,
F: FnMut(Self::Item) -> Result<(), E>,
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