From 316742edb73a81edc231b1c8dc086fae1f3142d9 Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Sun, 22 Jan 2023 15:46:53 +0100 Subject: [PATCH 1/4] =?UTF-8?q?io:=20soften=20=E2=80=98at=20most=20one=20w?= =?UTF-8?q?rite=20attempt=E2=80=99=20requirement=20in=20io::Write::write?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit At the moment, documentation of std::io::Write::write indicates that call to it ‘represents at most one attempt to write to any wrapped object’. It seems that such wording was put there to contrast it with pre-1.0 interface which attempted to write all the data (it has since been changed in [RFC 517]). However, the requirement puts unnecessary constraints and may complicate adaptors which perform non-trivial transformations on the data. For example, they may maintain an internal buffer which needs to be written out before the write method accepts more data. It might be natural to code the method such that it flushes the buffer and then grabs another chunk of user data. With the current wording in the documentation, the adaptor would be forced to return Ok(0). This commit softens the wording such that implementations can choose code structure which makes most sense for their particular use case. While at it, elaborate on the meaning of `Ok(0)` return pointing out that the write_all methods interprets it as an error. [RFC 517]: https://rust-lang.github.io/rfcs/0517-io-os-reform.html --- library/std/src/io/mod.rs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index de528e85368cb..aa34d4be19242 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -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. /// /// 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 the return value is [`Ok(n)`] then it must be guaranteed that `n <= + /// buf.len()`. Unless `input` is empty, this function shouldn’t return `0` + /// since caller may interpret that as an error (the default implementation + /// of [`Write::write_all`] does exactly that). To indicate lack of space + /// function should return [`ErrorKind::StorageFull`] error instead. /// /// # Errors /// From 8654669ed4569216fde2c16edb49d05cd373f038 Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Fri, 3 Feb 2023 18:38:51 +0100 Subject: [PATCH 2/4] Update library/std/src/io/mod.rs --- library/std/src/io/mod.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index aa34d4be19242..d4f8c3123b287 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -1392,10 +1392,10 @@ pub trait Write { /// 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()`. Unless `input` is empty, this function shouldn’t return `0` - /// since caller may interpret that as an error (the default implementation - /// of [`Write::write_all`] does exactly that). To indicate lack of space + /// If this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`]. + /// If the return value is `Ok(n)` it must hold than `n <= buf.len()`. + /// Unless `input` is empty, this function shouldn’t return `Ok(0)` since + /// caller may interpret that as an error. To indicate lack of space /// function should return [`ErrorKind::StorageFull`] error instead. /// /// # Errors From 5451dfe6c0c841c0a01d812eebb62e60576dbf89 Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Wed, 1 Mar 2023 00:48:22 +0100 Subject: [PATCH 3/4] Update library/std/src/io/mod.rs Co-authored-by: Andrew Gallant --- library/std/src/io/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index d4f8c3123b287..8e8fa147c0d57 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -1394,9 +1394,9 @@ pub trait Write { /// /// If this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`]. /// If the return value is `Ok(n)` it must hold than `n <= buf.len()`. - /// Unless `input` is empty, this function shouldn’t return `Ok(0)` since - /// caller may interpret that as an error. To indicate lack of space - /// function should return [`ErrorKind::StorageFull`] error instead. + /// 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 /// From 7d57cd524a33179be58287737b7fd603a9d4a759 Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Fri, 3 Mar 2023 03:16:56 +0100 Subject: [PATCH 4/4] Update library/std/src/io/mod.rs Co-authored-by: Jacob Lifshay --- library/std/src/io/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index 8e8fa147c0d57..b2fcb966032a1 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -1393,7 +1393,7 @@ pub trait Write { /// an [`Err`] variant. /// /// If this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`]. - /// If the return value is `Ok(n)` it must hold than `n <= buf.len()`. + /// 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.