Repository: tokio-rs/tokio
File: tokio-stream/src/stream_close.rs (Rust)

Code before:
    /// Stream that returns None when the stream is exhausted. To be used with StreamMap to know when a stream ends.
    /// # Example
    /// Using `StreamNotifyClose` to handle closed streams with `StreamMap`
    /// ```no_run
    /// use tokio_stream::{Stream, StreamExt, StreamMap, StreamNotifyClose};

    /// struct Test {
    ///     state: i32,
    /// }

    /// impl Stream for Test {
    ///     type Item = i32;

    ///     fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<i32>> {
    ///         let val = self.state;
    ///         let res = match val {
    ///             0 => Poll::Ready(Some(0)),
    ///             1 => Poll::Ready(Some(1)),
    ///             2 => Poll::Ready(None),
    ///             _ => unreachable!("shouldn't get here"),
    ///         };

    ///         self.state += 1;
    ///         res
    ///     }
    /// }

    /// #[tokio::main]
    /// async fn main() {
    ///     let mut map = StreamMap::new();
    ///     let mut stream = StreamNotifyClose::new(Test { state: 0 });
    ///     let mut stream2 = StreamNotifyClose::new(Test { state: 0 });
    ///     map.insert(0, stream);
    ///     map.insert(1, stream2);
    ///     loop {
    ///         tokio::select! {
    ///           Some((key, val)) = map.next() => {
    ///              match val {
    ///                 Some(val) => println!("got {val:?} from stream {key:?}"),
    ///                 None => println!("stream {key:?} closed")
    ///              }
    ///             }
    ///         }
    ///     }
    /// }
    /// ```
    #[must_use = "streams do nothing unless polled"]
    pub struct StreamNotifyClose<S> {
        #[pin]
        inner: Option<S>,
    }

Review comment (suggestion):
This is fine for the test, but too complicated to be an example. You should use a simpler `Stream` instead. For example, you could use `tokio_stream::iter(vec![0, 1])`.

Code after:
    /// A `Stream` that wraps the values in an `Option`.
    ///
    /// Whenever the wrapped stream yields an item, this stream yields that item
    /// wrapped in `Some`. When the inner stream ends, then this stream first
    /// yields a `None` item, and then this stream will also end.
    ///
    /// # Example
    ///
    /// Using `StreamNotifyClose` to handle closed streams with `StreamMap`.
    ///
    /// ```
    /// use tokio_stream::{StreamExt, StreamMap, StreamNotifyClose};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let mut map = StreamMap::new();
    ///     let stream = StreamNotifyClose::new(tokio_stream::iter(vec![0, 1]));
    ///     let stream2 = StreamNotifyClose::new(tokio_stream::iter(vec![0, 1]));
    ///     map.insert(0, stream);
    ///     map.insert(1, stream2);
    ///     while let Some((key, val)) = map.next().await {
    ///         match val {
    ///             Some(val) => println!("got {val:?} from stream {key:?}"),
    ///             None => println!("stream {key:?} closed"),
    ///         }
    ///     }
    /// }
    /// ```
    #[must_use = "streams do nothing unless polled"]
    pub struct StreamNotifyClose<S> {
        #[pin]
        inner: Option<S>,
    }
}

impl<S> StreamNotifyClose<S> {
    /// Create a new `StreamNotifyClose`.
    pub fn new(stream: S) -> Self {
        Self {
            inner: Some(stream),
        }
    }

    /// Get back the inner `Stream`.
    ///
    /// Returns `None` if the stream has reached its end.
    pub fn into_inner(self) -> Option<S> {
        self.inner
    }
}