tag	b9231ff96bee9799bf8d2b19c9b5967ce5155b5d
tagger	The Android Open Source Project <initial-contribution@android.com>	Tue May 24 16:17:36 2022 -0700
object	b8686a09a4c46a6be04e0a5a22faa7144f0f2514

commit	b8686a09a4c46a6be04e0a5a22faa7144f0f2514	[log] [tgz]
author	android-build-team Robot <android-build-team-robot@google.com>	Tue Mar 02 02:05:20 2021 +0000
committer	android-build-team Robot <android-build-team-robot@google.com>	Tue Mar 02 02:05:20 2021 +0000
tree	c7cbe988b0a96fa0391216d9d311bba201d37564
parent	933a786e24ae9749ce6d73dd8c882ce420a6c8db [diff]
parent	8ddcc772e25c4abc919a4b40f5d05ec48cf34ce5 [diff]

tree: c7cbe988b0a96fa0391216d9d311bba201d37564

README.md

Asynchronous streams for Rust

Asynchronous stream of elements.

Provides two macros, stream! and try_stream!, allowing the caller to define asynchronous streams of elements. These are implemented using async & await notation. The stream! macro works without unstable features.

The stream! macro returns an anonymous type implementing the Stream trait. The Item associated type is the type of the values yielded from the stream. The try_stream! also returns an anonymous type implementing the Stream trait, but the Item associated type is Result<T, Error>. The try_stream! macro supports using ? notiation as part of the implementation.

Usage

A basic stream yielding numbers. Values are yielded using the yield keyword. The stream block must return ().

use async_stream::stream;

use futures_util::pin_mut;
use futures_util::stream::StreamExt;

#[tokio::main]
async fn main() {
    let s = stream! {
        for i in 0..3 {
            yield i;
        }
    };

    pin_mut!(s); // needed for iteration

    while let Some(value) = s.next().await {
        println!("got {}", value);
    }
}

Streams may be returned by using impl Stream<Item = T>:

use async_stream::stream;

use futures_core::stream::Stream;
use futures_util::pin_mut;
use futures_util::stream::StreamExt;

fn zero_to_three() -> impl Stream<Item = u32> {
    stream! {
        for i in 0..3 {
            yield i;
        }
    }
}

#[tokio::main]
async fn main() {
    let s = zero_to_three();
    pin_mut!(s); // needed for iteration

    while let Some(value) = s.next().await {
        println!("got {}", value);
    }
}

Streams may be implemented in terms of other streams:

use async_stream::stream;

use futures_core::stream::Stream;
use futures_util::pin_mut;
use futures_util::stream::StreamExt;

fn zero_to_three() -> impl Stream<Item = u32> {
    stream! {
        for i in 0..3 {
            yield i;
        }
    }
}

fn double<S: Stream<Item = u32>>(input: S)
    -> impl Stream<Item = u32>
{
    stream! {
        pin_mut!(input);
        while let Some(value) = input.next().await {
            yield value * 2;
        }
    }
}

#[tokio::main]
async fn main() {
    let s = double(zero_to_three());
    pin_mut!(s); // needed for iteration

    while let Some(value) = s.next().await {
        println!("got {}", value);
    }
}

Rust try notation (?) can be used with the try_stream! macro. The Item of the returned stream is Result with Ok being the value yielded and Err the error type returned by ?.

use tokio::net::{TcpListener, TcpStream};

use async_stream::try_stream;
use futures_core::stream::Stream;

use std::io;
use std::net::SocketAddr;

fn bind_and_accept(addr: SocketAddr)
    -> impl Stream<Item = io::Result<TcpStream>>
{
    try_stream! {
        let mut listener = TcpListener::bind(&addr)?;

        loop {
            let (stream, addr) = listener.accept().await?;
            println!("received on {:?}", addr);
            yield stream;
        }
    }
}

Implementation

The stream! and try_stream! macros are implemented using proc macros. Given that proc macros in expression position are not supported on stable rust, a hack similar to the one provided by the proc-macro-hack crate is used. The macro searches the syntax tree for instances of sender.send($expr) and transforms them into sender.send($expr).await.

The stream uses a lightweight sender to send values from the stream implementation to the caller. When entering the stream, an Option<T> is stored on the stack. A pointer to the cell is stored in a thread local and poll is called on the async block. When poll returns. sender.send(value) stores the value that cell and yields back to the caller.

Limitations

async-stream suffers from the same limitations as the proc-macro-hack crate. Primarily, nesting support must be implemented using a TT-muncher. If large stream! blocks are used, the caller will be required to add #![recursion_limit = "..."] to their crate.

A stream! macro may only contain up to 64 macro invocations.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in async-stream by you, shall be licensed as MIT, without any additional terms or conditions.