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

io: soften ‘at most one write attempt’ requirement in io::Write::write #107200

Merged
merged 4 commits into from
Jun 18, 2023
Merged

io: soften ‘at most one write attempt’ requirement in io::Write::write #107200

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
316742e
io: soften ‘at most one write attempt’ requirement in io::Write::write
mina86 Jan 22, 2023
8654669
Update library/std/src/io/mod.rs
mina86 Feb 3, 2023
5451dfe
Update library/std/src/io/mod.rs
mina86 Feb 28, 2023
7d57cd5
Update library/std/src/io/mod.rs
mina86 Mar 3, 2023
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
11 changes: 6 additions & 5 deletions library/std/src/io/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1385,17 +1385,18 @@ pub trait Write {
///
/// This function will attempt to write the entire contents of `buf`, but
/// the entire write might not succeed, or the write may also generate an
/// error. A call to `write` represents *at most one* attempt to write to
/// error. Typically, a call to `write` represents one attempt to write to
/// any wrapped object.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
/// any wrapped object.
/// any wrapped object. At most one underlying write operation
/// (whether successful or failed) can occur involving the new
/// bytes supplied by the caller, since once that operation
/// occurs, the return value would need to reflect that success
/// or error.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I dunno if using strong language here is needed. Current wording around Ok(n) and Ok(0) should steer all sane implementations towards doing at most one write for new bytes already. Meanwhile, what if I implement a struct MultiplexWrite<U: Write, V: Write>(U, V); which sends single write to two underlying writers? Or an AutoReconnectWriter(TCPStream) which automatically re-establishes connection on connection closed errors?

///
/// Calls to `write` are not guaranteed to block waiting for data to be
/// written, and a write which would otherwise block can be indicated through
/// an [`Err`] variant.
///
/// If the return value is [`Ok(n)`] then it must be guaranteed that
/// `n <= buf.len()`. A return value of `0` typically means that the
/// underlying object is no longer able to accept bytes and will likely not
/// be able to in the future as well, or that the buffer provided is empty.
/// If this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`].
/// If the return value is `Ok(n)` then `n` must satisfy `n <= buf.len()`.
/// Unless `buf` is empty, this function shouldn’t return `Ok(0)` since the
/// caller may interpret that as an error. To indicate lack of space,
/// implementors should return [`ErrorKind::StorageFull`] error instead.
///
/// # Errors
///
Expand Down