From acc26a076a44c4c64b960e259bb516a9bd636dfd Mon Sep 17 00:00:00 2001 From: dvdsk Date: Fri, 23 Aug 2024 15:04:00 +0200 Subject: [PATCH 1/2] embassy-net/read document return value Ok(0) --- embassy-net/src/tcp.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/embassy-net/src/tcp.rs b/embassy-net/src/tcp.rs index 18200287e..62ee5cb66 100644 --- a/embassy-net/src/tcp.rs +++ b/embassy-net/src/tcp.rs @@ -79,6 +79,9 @@ impl<'a> TcpReader<'a> { /// /// Returns how many bytes were read, or an error. If no data is available, it waits /// until there is at least one byte available. + /// + /// A return value of Ok(0) means that the socket was closed and is longer able to + /// accept bytes or that the buffer provided is empty. pub async fn read(&mut self, buf: &mut [u8]) -> Result { self.io.read(buf).await } @@ -273,6 +276,9 @@ impl<'a> TcpSocket<'a> { /// /// Returns how many bytes were read, or an error. If no data is available, it waits /// until there is at least one byte available. + /// + /// A return value of Ok(0) means that the socket was closed and is longer able to + /// accept bytes or that the buffer provided is empty. pub async fn read(&mut self, buf: &mut [u8]) -> Result { self.io.read(buf).await } From 5479647962477a794dfcde19d8e865eb47150caf Mon Sep 17 00:00:00 2001 From: dvdsk Date: Fri, 23 Aug 2024 19:16:33 +0200 Subject: [PATCH 2/2] embassy-net: fix/clearify TcpReader docs. Expand docs on timeouts --- embassy-net/src/tcp.rs | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/embassy-net/src/tcp.rs b/embassy-net/src/tcp.rs index 62ee5cb66..b2e3279cc 100644 --- a/embassy-net/src/tcp.rs +++ b/embassy-net/src/tcp.rs @@ -80,8 +80,14 @@ impl<'a> TcpReader<'a> { /// Returns how many bytes were read, or an error. If no data is available, it waits /// until there is at least one byte available. /// - /// A return value of Ok(0) means that the socket was closed and is longer able to - /// accept bytes or that the buffer provided is empty. + /// # Note + /// A return value of Ok(0) means that we have read all data and the remote + /// side has closed our receive half of the socket. The remote can no longer + /// send bytes. + /// + /// The send half of the socket is still open. If you want to reconnect using + /// the socket you split this reader off the send half needs to be closed using + /// [`abort()`](TcpSocket::abort). pub async fn read(&mut self, buf: &mut [u8]) -> Result { self.io.read(buf).await } @@ -277,8 +283,8 @@ impl<'a> TcpSocket<'a> { /// Returns how many bytes were read, or an error. If no data is available, it waits /// until there is at least one byte available. /// - /// A return value of Ok(0) means that the socket was closed and is longer able to - /// accept bytes or that the buffer provided is empty. + /// A return value of Ok(0) means that the socket was closed and is longer + /// able to receive any data. pub async fn read(&mut self, buf: &mut [u8]) -> Result { self.io.read(buf).await } @@ -303,6 +309,10 @@ impl<'a> TcpSocket<'a> { /// /// If the timeout is set, the socket will be closed if no data is received for the /// specified duration. + /// + /// # Note: + /// Set a keep alive interval ([`set_keep_alive`] to prevent timeouts when + /// the remote could still respond. pub fn set_timeout(&mut self, duration: Option) { self.io .with_mut(|s, _| s.set_timeout(duration.map(duration_to_smoltcp))) @@ -314,6 +324,9 @@ impl<'a> TcpSocket<'a> { /// the specified duration of inactivity. /// /// If not set, the socket will not send keep-alive packets. + /// + /// By setting a [`timeout`](Self::timeout) larger then the keep alive you + /// can detect a remote endpoint that no longer answers. pub fn set_keep_alive(&mut self, interval: Option) { self.io .with_mut(|s, _| s.set_keep_alive(interval.map(duration_to_smoltcp)))