Add `core::stream::Stream` by yoshuawuyts · Pull Request #79023 · rust-lang/rust...

yoshuawuyts commented on Nov 14 •

[Tracking issue: #79024]

This patch adds the core::stream submodule and implements core::stream::Stream in accordance with RFC2996. The RFC hasn't been merged yet, but as requested by the libs team in rust-lang/rfcs#2996 (comment) I'm filing this PR to get the ball rolling.

Documentatation

The docs in this PR have been adapted from std::iter, async_std::stream, and futures::stream::Stream. Once this PR lands my plan is to follow this up with PRs to add helper methods such as stream::repeat which can be used to document more of the concepts that are currently missing. That will allow us to cover concepts such as "infinite streams" and "laziness" in more depth.

Feature gate

The feature gate for Stream is stream_trait. This matches the #[lang = "future_trait"] attribute name. The intention is that only the APIs defined in RFC2996 will use this feature gate, with future additions such as stream::repeat using their own feature gates. This is so we can ensure a smooth path towards stabilizing the Stream trait without needing to stabilize all the APIs in core::stream at once. But also don't start expanding the API until after stabilization, as was the case with std::future.

edit: the feature gate has been changed to async_stream to match the feature gate proposed in the RFC.

Conclusion

This PR introduces core::stream::{Stream, Next} and re-exports it from std as std::stream::{Stream, Next}. Landing Stream in the stdlib has been a mult-year process; and it's incredibly exciting for this to finally happen!

r? @KodrAus
cc/ @rust-lang/wg-async-foundations @rust-lang/libs