nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-10-31 14:31:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove Stream::next

Browse Source 
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:
Yoshua Wuyts 2021-01-15 15:54:09 +01:00
parent 0c8db16a67
commit a1b11321fb
3 changed files with 9 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
library/core/src/stream/mod.rs
View File

@ -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;

19
library/core/src/stream/stream/mod.rs
View File

@ -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")]

30
library/core/src/stream/stream/next.rs
View File

@ -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)
}
}