mirror of
https://github.com/rust-lang/rust.git
synced 2024-10-31 14:31:55 +00:00
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
This commit is contained in:
parent
0c8db16a67
commit
a1b11321fb
@ -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`][`<Item>`].
|
||||
//! 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<Stream::Item>`.
|
||||
//!
|
||||
//! 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
|
||||
//! [`<Item>`]: 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;
|
||||
|
@ -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<usize>) {
|
||||
(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")]
|
||||
|
@ -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<S: Stream + Unpin + ?Sized> Future for Next<'_, S> {
|
||||
type Output = Option<S::Item>;
|
||||
|
||||
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
|
||||
Pin::new(&mut *self.stream).poll_next(cx)
|
||||
}
|
||||
}
|
Loading…
Reference in New Issue
Block a user