Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document cancel-safety of StreamExt::next #2896

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document cancel-safety of StreamExt::next #2896

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions futures-util/src/stream/stream/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,12 @@ pub trait StreamExt: Stream {
/// pinning it to the stack using the `pin_mut!` macro from the `pin_utils`
/// crate.
///
/// # Cancel safety
///
/// The returned future only holds a reference to the underlying stream, and
/// so is cancel safe (assuming the stream is also cancel-safe). If it is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

assuming the stream is also cancel-safe

AFAIK, in the term "cancel-safe" used in tokio, cancel-safe is a property of Future and StreamExt::next is always cancel-safe. What is the definition of cancel-safe you are referring to?

https://docs.rs/tokio-stream/latest/tokio_stream/trait.StreamExt.html#method.next

Copy link
Author

@akonradi-signal akonradi-signal Feb 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. I'm drawing an analogy between Future::poll and Stream::poll_next, where calling the latter once but not until it returns Poll::Ready could lead to bad behavior.

The example I'm imagining is the result of calling StreamExt::chunks_timeout on a &mut impl Stream. Calling poll_once on that ChunksTimeout, then dropping it, then polling the wrapped stream could result in values from the input stream being dropped without ever being yielded. Given that possibility, I'd label ChunksTimeout not "cancel-safe".

/// dropped before it resolves, no item from the stream will be dropped.
///
/// # Examples
///
/// ```
Expand Down