From 09f02c471522c07c766c7b6e01c2da1e5b975887 Mon Sep 17 00:00:00 2001 From: Isaac Sikkema Date: Tue, 23 Aug 2022 20:47:51 -0400 Subject: [PATCH 01/11] net: add documentation for `try_read()` The previous documentation falsely implied that a return value of `Ok(0)` from `try_read()` always meant that the stream's read half had closed. However, `Ok(0)` can be returned while the stream's read half is still open if the specified buffer has a length of 0. --- tokio/src/net/tcp/stream.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 19e3ead80fb..1f61f625f94 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -547,8 +547,12 @@ impl TcpStream { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The buffer specified was 0 bytes in length. + /// + /// If the stream is not ready to read data /// `Err(io::ErrorKind::WouldBlock)` is returned. /// /// # Examples From 32ce71ddcd5cd73f276a2f0a20944dfbc0224cbb Mon Sep 17 00:00:00 2001 From: Isaac Sikkema Date: Tue, 23 Aug 2022 20:49:25 -0400 Subject: [PATCH 02/11] net: add missing comma to `try_read()` docs --- tokio/src/net/tcp/stream.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 1f61f625f94..ecb9b7e623c 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -552,7 +552,7 @@ impl TcpStream { /// 1. The stream's read half is closed and will no longer yield data. /// 2. The buffer specified was 0 bytes in length. /// - /// If the stream is not ready to read data + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. /// /// # Examples From e2a827ac032e45b204b2ebd1b931d1fcf4abe318 Mon Sep 17 00:00:00 2001 From: Isaac Sikkema Date: Tue, 23 Aug 2022 20:57:05 -0400 Subject: [PATCH 03/11] net: rustfmt --- tokio/src/net/tcp/stream.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index ecb9b7e623c..17eb7b91e78 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -551,7 +551,7 @@ impl TcpStream { /// /// 1. The stream's read half is closed and will no longer yield data. /// 2. The buffer specified was 0 bytes in length. - /// + /// /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. /// From a0591bfec1a70ab445501625974e83d38bfb8153 Mon Sep 17 00:00:00 2001 From: Isaac Sikkema Date: Wed, 24 Aug 2022 10:07:01 -0400 Subject: [PATCH 04/11] net: commit suggested language change Co-authored-by: Alice Ryhl --- tokio/src/net/tcp/stream.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 17eb7b91e78..48033fc5f42 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -550,7 +550,7 @@ impl TcpStream { /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: /// /// 1. The stream's read half is closed and will no longer yield data. - /// 2. The buffer specified was 0 bytes in length. + /// 2. The specified buffer was 0 bytes in length. /// /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. From 00c3620447d7bb5ba260b374c78996d39598228b Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:12:07 -0400 Subject: [PATCH 05/11] net: update `try_read()` doc in `split_owned.rs` --- tokio/src/net/tcp/split_owned.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/tcp/split_owned.rs b/tokio/src/net/tcp/split_owned.rs index ef4e7b53611..e2cfdefe1a3 100644 --- a/tokio/src/net/tcp/split_owned.rs +++ b/tokio/src/net/tcp/split_owned.rs @@ -245,8 +245,12 @@ impl OwnedReadHalf { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. pub fn try_read(&self, buf: &mut [u8]) -> io::Result { self.inner.try_read(buf) From 3b91039f13ebd761c0a4ed5872ba5509e80afadc Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:12:57 -0400 Subject: [PATCH 06/11] net: update `try_read()` doc in `split.rs` --- tokio/src/net/tcp/split.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/tcp/split.rs b/tokio/src/net/tcp/split.rs index 0e02928495f..2ea08b3dc32 100644 --- a/tokio/src/net/tcp/split.rs +++ b/tokio/src/net/tcp/split.rs @@ -190,8 +190,12 @@ impl ReadHalf<'_> { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. pub fn try_read(&self, buf: &mut [u8]) -> io::Result { self.0.try_read(buf) From d29a1336f0fac120ebe8d70f7828dcf3a939ae2e Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:14:56 -0400 Subject: [PATCH 07/11] net: fix `try_read()` doc in `unix/split_owned.rs` --- tokio/src/net/unix/split_owned.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/unix/split_owned.rs b/tokio/src/net/unix/split_owned.rs index 9c3a2a41777..3dce2a86aa8 100644 --- a/tokio/src/net/unix/split_owned.rs +++ b/tokio/src/net/unix/split_owned.rs @@ -155,8 +155,12 @@ impl OwnedReadHalf { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. pub fn try_read(&self, buf: &mut [u8]) -> io::Result { self.inner.try_read(buf) From 2063aba27ce64a16b2525bf28dc8a6661ba786e2 Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:15:51 -0400 Subject: [PATCH 08/11] net: fix `try_read()` doc in `unix/split.rs` --- tokio/src/net/unix/split.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/unix/split.rs b/tokio/src/net/unix/split.rs index d4686c22d78..f9664d53254 100644 --- a/tokio/src/net/unix/split.rs +++ b/tokio/src/net/unix/split.rs @@ -100,8 +100,12 @@ impl ReadHalf<'_> { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. pub fn try_read(&self, buf: &mut [u8]) -> io::Result { self.0.try_read(buf) From f6fc38f7d433bba09e759782d79a27774e25e10e Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:17:10 -0400 Subject: [PATCH 09/11] net: fix `try_read()` doc in `unix/stream.rs` --- tokio/src/net/unix/stream.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/unix/stream.rs b/tokio/src/net/unix/stream.rs index 82cec77fa87..e0a70721630 100644 --- a/tokio/src/net/unix/stream.rs +++ b/tokio/src/net/unix/stream.rs @@ -239,8 +239,12 @@ impl UnixStream { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the stream's read half is closed - /// and will no longer yield data. If the stream is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The stream's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the stream is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. /// /// # Examples From 870f767775ab67ab9d18f071bdc8aa21e83f9f1c Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:22:41 -0400 Subject: [PATCH 10/11] net: fix `try_read()` doc in `NamedPipeServer` --- tokio/src/net/windows/named_pipe.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index 34606d2a251..f24980c8213 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -403,8 +403,12 @@ impl NamedPipeServer { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the pipe's read half is closed - /// and will no longer yield data. If the pipe is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The pipe's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the pipe is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. /// /// # Examples From be13b477a045c9297e99fa9991258066dd27ebd0 Mon Sep 17 00:00:00 2001 From: "Sikkema, Isaac" Date: Wed, 24 Aug 2022 10:23:49 -0400 Subject: [PATCH 11/11] net: fix `try_read()` doc in `NamedPipeClient` --- tokio/src/net/windows/named_pipe.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index f24980c8213..c895dabacc8 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/tokio/src/net/windows/named_pipe.rs @@ -1147,8 +1147,12 @@ impl NamedPipeClient { /// # Return /// /// If data is successfully read, `Ok(n)` is returned, where `n` is the - /// number of bytes read. `Ok(0)` indicates the pipe's read half is closed - /// and will no longer yield data. If the pipe is not ready to read data + /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios: + /// + /// 1. The pipe's read half is closed and will no longer yield data. + /// 2. The specified buffer was 0 bytes in length. + /// + /// If the pipe is not ready to read data, /// `Err(io::ErrorKind::WouldBlock)` is returned. /// /// # Examples