futures-async-stream
Async stream for Rust and the futures crate.
This crate provides useful features for streams, using async_await
and
unstable generators
.
Usage
Add this to your Cargo.toml
:
[]
= "0.2"
= "0.3"
Compiler support: requires rustc nightly-2021-10-11+
#[for_await]
Processes streams using a for loop.
This is a reimplement of futures-await's #[async]
for loops for
futures 0.3 and is an experimental implementation of the idea listed as the
next step of async/await.
use Stream;
use for_await;
async
value
has the Item
type of the stream passed in. Note that async for
loops can only be used inside of async
functions, closures, blocks,
#[stream]
functions and stream_block!
macros.
#[stream]
Creates streams via generators.
This is a reimplement of futures-await's #[stream]
for futures 0.3 and
is an experimental implementation of the idea listed as the next step of
async/await.
use Stream;
use stream;
// Returns a stream of i32
async
To early exit from a #[stream]
function or block, use return
.
#[stream]
on async fn must have an item type specified via
item = some::Path
and the values output from the stream must be yielded
via the yield
expression.
#[stream]
can also be used on async blocks:
use Stream;
use stream;
Note that #[stream]
on async block does not require the item
argument,
but it may require additional type annotations.
Using async stream functions in traits
You can use async stream functions in traits by passing boxed
or
boxed_local
as an argument.
use stream;
;
A async stream function that received a boxed
argument is converted to a
function that returns Pin<Box<dyn Stream<Item = item> + Send + 'lifetime>>
.
If you passed boxed_local
instead of boxed
, async stream function
returns a non-thread-safe stream (Pin<Box<dyn Stream<Item = item> + 'lifetime>>
).
use Pin;
use Stream;
use stream;
// The trait itself can be defined without unstable features.
;
#[try_stream]
?
operator can be used with the #[try_stream]
. The Item
of the
returned stream is Result
with Ok
being the value yielded and Err
the
error type returned by ?
operator or return Err(...)
.
use Stream;
use try_stream;
async
#[try_stream]
can be used wherever #[stream]
can be used.
To early exit from a #[try_stream]
function or block, use return Ok(())
.
How to write the equivalent code without this API?
#[for_await]
You can write this by combining while let
loop, .await
, pin!
macro,
and StreamExt::next()
method:
use pin;
use ;
async
#[stream]
You can write this by manually implementing the combinator:
use ;
use Stream;
use pin_project;
License
Licensed under either of Apache License, Version 2.0 or MIT license 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.