Add core::stream::from_iter

[yoshuawuyts]

Tracking issue: #81798

This_ PR implements std::stream::from_iter, as outlined in the "Converting an Iterator to a Stream" section of the Stream RFC. This function enables converting an Iterator to a Stream by wrapping each item in the iterator with a Poll::Ready instance.

r? @tmandry

cc/ @rust-lang/libs @rust-lang/wg-async-foundations

Example

Being able to convert from an iterator into a stream is useful when refactoring from iterative loops into a more functional adapter-based style. This is fairly common when using more complex filter / map / find chains. In its basic form this conversion looks like this:

before

let mut output = vec![];
for item in my_vec {
    let out = do_io(item).await?;
    output.push(out);
}

after

use std::stream;

let output = stream::from_iter(my_vec.iter())
    .map(async |item| do_io(item).await)
    .collect()?;

Having a way to convert an Iterator to a Stream is essential in enabling this flow.

Implementation Notes

This PR makes use of unsafe {} to pin an item. Currently we're having conversations on the libs stream in Zulip how to bring pin-project in as a dependency to core so we can omit the unsafe {}.

This PR also includes a documentation block which references Stream::next which currently doesn't exist in the stdlib (originally included in the RFC and PR, but later omitted because of an unresolved issue). stream::from_iter can't stabilize before Stream does, and there's still a chance we may stabilize Stream with a next method. So this PR includes documentation referencing that method, which we can remove as part of stabilization if by any chance we don't have Stream::next.

Alternatives Considered

impl IntoStream for T: IntoIterator

An obvious question would be whether we could make it so every iterator can automatically be converted into a stream by calling into_stream on it. The answer is: "perhaps, but it could cause type issues". Types like std::collections may want to opt to create manual implementations for IntoStream and IntoIter, which wouldn't be possible if it was implemented through a catch-all trait.

Possibly an alternative such as impl IntoStream for T: Iterator could work, but it feels somewhat restrictive. In the end, converting an iterator to a stream is likely to be a bit of a niche case. And even then, adding a standalone function to convert an Iterator into a Stream would not be mutually exclusive with a blanket implementation.

Naming

The exact name can be debated in the period before stabilization. But I've chosen stream::from_iter rather than stream::iter because we are creating a stream from an iterator rather than iterating a stream. We also expect to add a stream counterpart to iter::from_fn later on (blocked on async closures), and having stream::from_fn and stream::from_iter would feel like a consistent pair. It also has prior art in async_std::stream::from_iter.

Future Directions

Stream conversions for collections

This is a building block towards implementing stream/stream_mut/into_stream methods for std::collections, std::vec, and more. This would allow even quicker refactorings from using loops to using iterator adapters by omitting the import altogether:

before

use std::stream;

let output = stream::from_iter(my_vec.iter())
    .map(async |item| do_io(item).await)
    .collect()?;

after

let output = my_vec
    .stream()
    .map(async |item| do_io(item).await)
    .collect()?;

[taiki-e]

I recommend seeing how the same function is implemented in futures. (that is the most widely used in the ecosystem.)

As for prior art, the same functions in futures, tokio, and futures-lite are called iter.

EDIT: This PR's implementation seems to be based on async-std and I opened an issue in async-std repo about it: async-rs/async-std#953

[JohnCSimon]

failing build
@rustbot label: -S-waiting-on-review +S-waiting-on-author

[crlf0710]

@yoshuawuyts Ping from triage! CI is still red here. Would you mind fixing that? Thanks!

[yoshuawuyts]

Hey! Yeah I'm on vacation right now. I'll make sure to get around to this either next week or the week after!

I have a few outstanding PRs — just need to find a day to update them all 😅

[crlf0710]

@yoshuawuyts Ping from triage! Any updates?

[JohnCSimon]

@yoshuawuyts Are you back from vacation?

[yoshuawuyts]

@JohnCSimon heya, I've been busy with a move among other things. I'll be back to work starting July 15th!

edit: found some free time today, and repaired my local setup. I've updated the PR with all feedback provided, and it should be good again for review!

[dtolnay]

@bors r+

[bors]

📌 Commit 660f585 has been approved by dtolnay

[bors]

⌛ Testing commit 660f585 with merge b75dbad85bade79beb9f5c73b11dd9c463958c7f...

[bors]

💔 Test failed - checks-actions

[rust-log-analyzer]

A job failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

[dtolnay]

@bors retry

[bors]

⌛ Testing commit 660f585 with merge 669248f5fc704c5d7e527bc889c1f49937a6d5f3...

[JohnTitor]

@bors retry rolled-up

[rust-log-analyzer]

A job failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

[bors]

⌛ Testing commit 660f585 with merge 2b8de6f...

[bors]

☔ The latest upstream changes (presumably #87746) made this pull request unmergeable. Please resolve the merge conflicts.