From a1b11321fb2d6ce00af9c8957c98df76432b1b78 Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Fri, 15 Jan 2021 15:54:09 +0100 Subject: [PATCH] Remove `Stream::next` This is a temporary change only, as we wait to resolve dynamic dispatch issues. The `Stream::next` method and corresponding documentation are expected to be fully restored once we have a path to proceed. Ref: https://github.com/rust-lang/rfcs/pull/2996#issuecomment-757386206 update docs --- library/core/src/stream/mod.rs | 45 ++++++-------------------- library/core/src/stream/stream/mod.rs | 19 ----------- library/core/src/stream/stream/next.rs | 30 ----------------- 3 files changed, 9 insertions(+), 85 deletions(-) delete mode 100644 library/core/src/stream/stream/next.rs diff --git a/library/core/src/stream/mod.rs b/library/core/src/stream/mod.rs index 48cca497292..0df18af65eb 100644 --- a/library/core/src/stream/mod.rs +++ b/library/core/src/stream/mod.rs @@ -16,13 +16,12 @@ //! exist and what you can do with them. The methods of these traits are worth //! putting some extra study time into. //! * Functions provide some helpful ways to create some basic streams. -//! * [Structs] are often the return types of the various methods on this +//! * Structs are often the return types of the various methods on this //! module's traits. You'll usually want to look at the method that creates //! the `struct`, rather than the `struct` itself. For more detail about why, //! see '[Implementing Stream](#implementing-stream)'. //! //! [Traits]: #traits -//! [Structs]: #structs //! //! That's it! Let's dig into streams. //! @@ -41,17 +40,17 @@ //! ``` //! //! Unlike `Iterator`, `Stream` makes a distinction between the [`poll_next`] -//! method which is used when implementing a `Stream`, and the [`next`] method -//! which is used when consuming a stream. Consumers of `Stream` only need to -//! consider [`next`], which when called, returns a future which yields -//! yields [`Option`][``]. +//! method which is used when implementing a `Stream`, and a (to-be-implemented) +//! `next` method which is used when consuming a stream. Consumers of `Stream` +//! only need to consider `next`, which when called, returns a future which +//! yields `Option`. //! -//! The future returned by [`next`] will yield `Some(Item)` as long as there are +//! The future returned by `next` will yield `Some(Item)` as long as there are //! elements, and once they've all been exhausted, will yield `None` to indicate //! that iteration is finished. If we're waiting on something asynchronous to //! resolve, the future will wait until the stream is ready to yield again. //! -//! Individual streams may choose to resume iteration, and so calling [`next`] +//! Individual streams may choose to resume iteration, and so calling `next` //! again may or may not eventually yield `Some(Item)` again at some point. //! //! [`Stream`]'s full definition includes a number of other methods as well, @@ -60,8 +59,6 @@ //! //! [`Poll`]: super::task::Poll //! [`poll_next`]: Stream::poll_next -//! [`next`]: Stream::next -//! [``]: Stream::Item //! //! # Implementing Stream //! @@ -112,36 +109,12 @@ //! } //! } //! } -//! -//! // And now we can use it! -//! # async fn run() { -//! # -//! let mut counter = Counter::new(); -//! -//! let x = counter.next().await.unwrap(); -//! println!("{}", x); -//! -//! let x = counter.next().await.unwrap(); -//! println!("{}", x); -//! -//! let x = counter.next().await.unwrap(); -//! println!("{}", x); -//! -//! let x = counter.next().await.unwrap(); -//! println!("{}", x); -//! -//! let x = counter.next().await.unwrap(); -//! println!("{}", x); -//! # -//! } //! ``` //! -//! This will print `1` through `5`, each on their own line. -//! //! # Laziness //! //! Streams are *lazy*. This means that just creating a stream doesn't _do_ a -//! whole lot. Nothing really happens until you call [`next`]. This is sometimes a +//! whole lot. Nothing really happens until you call `next`. This is sometimes a //! source of confusion when creating a stream solely for its side effects. The //! compiler will warn us about this kind of behavior: //! @@ -151,4 +124,4 @@ mod stream; -pub use stream::{Next, Stream}; +pub use stream::Stream; diff --git a/library/core/src/stream/stream/mod.rs b/library/core/src/stream/stream/mod.rs index 3f92c2e8c1c..e37902dae1f 100644 --- a/library/core/src/stream/stream/mod.rs +++ b/library/core/src/stream/stream/mod.rs @@ -1,7 +1,3 @@ -mod next; - -pub use next::Next; - use crate::ops::DerefMut; use crate::pin::Pin; use crate::task::{Context, Poll}; @@ -81,21 +77,6 @@ pub trait Stream { fn size_hint(&self) -> (usize, Option) { (0, None) } - - /// Advances the stream and returns a future which yields the next value. - /// - /// The returned future yields [`None`] when iteration is finished. - /// Individual stream implementations may choose to resume iteration, and so - /// calling `next()` again may or may not eventually start yielding - /// [`Some(Item)`] again at some point. - /// - /// [`Some(Item)`]: Some - fn next(&mut self) -> Next<'_, Self> - where - Self: Unpin, - { - Next::new(self) - } } #[unstable(feature = "async_stream", issue = "79024")] diff --git a/library/core/src/stream/stream/next.rs b/library/core/src/stream/stream/next.rs deleted file mode 100644 index e25d44228e7..00000000000 --- a/library/core/src/stream/stream/next.rs +++ /dev/null @@ -1,30 +0,0 @@ -use crate::future::Future; -use crate::pin::Pin; -use crate::stream::Stream; -use crate::task::{Context, Poll}; - -/// A future which advances the stream and returns the next value. -/// -/// This `struct` is created by [`Stream::next`]. See its documentation for more. -#[unstable(feature = "async_stream", issue = "79024")] -#[derive(Debug)] -#[must_use = "futures do nothing unless you `.await` or poll them"] -pub struct Next<'a, S: ?Sized> { - stream: &'a mut S, -} - -impl<'a, S: ?Sized> Next<'a, S> { - /// Create a new instance of `Next`. - pub(crate) fn new(stream: &'a mut S) -> Self { - Self { stream } - } -} - -#[unstable(feature = "async_stream", issue = "79024")] -impl Future for Next<'_, S> { - type Output = Option; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - Pin::new(&mut *self.stream).poll_next(cx) - } -}