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"
The current futures-async-stream requires Rust nightly 2020-02-14 or later.
#[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
#[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-threadsafe stream (Pin<Box<dyn Stream<Item = item> + 'lifetime>>
).
use Stream;
use stream;
use Pin;
// 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.
How to write the equivalent code without this API?
#[for_await]
You can write this by combining while let
loop, .await
, pin_mut
macro, and StreamExt::next()
method:
use ;
async
#[stream]
You can write this by manually implementing the combinator:
use ;
use pin_project;
use Pin;
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
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.