# Async Iterators

Features:

- "[Async iterator item](#Async-iterator-item)": function-like item that let's us
- "[Async iterator trait](#Async-iterator-trait)": `AsyncIterator` (the trait formerly known as `Stream`)
- "[Async iterator expression](#Async-iterator-expression)": `for await x in foo {}`

These three features are independent of each other and can be advanced on their own. All three are needed to consider "async iteration" a "solved problem".

## Milestones

- Update wg-async-foundations repo to link to [async-iteration](https://github.com/estebank/async-iterators) repo - estebank
- Author evaluation doc for async iteration item - estebank
- RFC for async iteration trait - nell [DONE](https://github.com/rust-lang/rfcs/pull/2996)
- Coordinate with stake-holders about current state of `trait AsyncIterator`
- Author evaluation doc for async iteration expression 💤
- Merge basic async iteration item support in `rustc`💤
- Resolve questions around `size_hint` for async iteration item 💤
- Update RFC for async iterator item to reflect the current state 💤
- Feature complete for async iterator item 💤
- Feature complete for async iterator trait 💤
- Feature complete for async iterator expression 💤

## Async iterator item

### Impact

Able to write custom sync and async iterators and combinators without creating a new `struct` and `impl`, and reducing the need to understand `Pin`.

async generator zip<A, B>(
    mut a: impl AsyncIterator<Item = A>,
    mut b: impl AsyncIterator<Item = B>,
) yields (A, B) {
    while let (Some(a), Some(b)) = (a.next().await, b.next().await) {
        yield (a, b);
    }
}

### Status

- Draft RFCs written: [syntax](https://github.com/estebank/rfcs/blob/stable-generators/text/0000-stable-generator-syntax.md), [semantics](https://github.com/estebank/rfcs/blob/stable-generators/text/0000-generators.md)
- [Proposed to T-lang](https://hackmd.io/9v81TQSgQcaAiqvHQtzN8w)
- Need to update to the current ["iniciative process"](https://github.com/rust-lang/lang-team/blob/master/src/initiatives.md)
- Syntax: bikeshedding needed, but it's not a blocker for exploration of semantics
- Need to write a draft with some alternatives and open a conversation (independent of semantics) with people in the WG (to limit bikeshedding)
- Semantics:

## Async iterator trait

### Impact

Having a single `AsyncIterator` trait in `std::` that can be used by the entire async ecosystem.

### Status

[Tracking issue #79024](https://github.com/rust-lang/rust/issues/79024).

## Async iterator expression

### Impact

Allowing easy consumption of `AsyncIterator`s by providing a new expression syntax for these.

async fn foo<I: Display>(x: impl AsyncIterator<Item = I> {
    for await i in x {
        println!("{}", i);
    }
}

Potentially, enable syntactic sugar for "rayon-like" parallel iteration.

async fn foo<I: Display>(x: impl AsyncIterator<Item = I> {
    for await (i, j, k) in x.chunks(3) {
        println!("{} {} {}", i, j, k);
    }
}

### Status

Not started.