From 709304d9f514cdd982b079cf28c6e1df1210e06d Mon Sep 17 00:00:00 2001 From: Carl Lerche Date: Tue, 26 Nov 2019 20:57:46 -0800 Subject: [PATCH] doc: fix and improve `incoming()` API doc This fixes the API docs for both `TcpListener::incoming` and `UnixListener::incoming`. The function now takes `&mut self` instead of `self`. Adds an example for both function. --- tokio/src/net/tcp/listener.rs | 40 +++++++++++++++++++++++++++------- tokio/src/net/unix/listener.rs | 39 +++++++++++++++++++++++++++++---- 2 files changed, 67 insertions(+), 12 deletions(-) diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 59762b13443..5a3acd9c196 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/tokio/src/net/tcp/listener.rs @@ -229,18 +229,42 @@ impl TcpListener { self.io.get_ref().local_addr() } - /// Consumes this listener, returning a stream of the sockets this listener - /// accepts. + /// Returns a stream over the connections being received on this listener. /// - /// This method returns an implementation of the `Stream` trait which - /// resolves to the sockets the are accepted on this listener. + /// The returned stream will never return `None` and will also not yield the + /// peer's `SocketAddr` structure. Iterating over it is equivalent to + /// calling accept in a loop. /// /// # Errors /// - /// Note that accepting a connection can lead to various errors and not all of them are - /// necessarily fatal ‒ for example having too many open file descriptors or the other side - /// closing the connection while it waits in an accept queue. These would terminate the stream - /// if not handled in any way. + /// Note that accepting a connection can lead to various errors and not all + /// of them are necessarily fatal ‒ for example having too many open file + /// descriptors or the other side closing the connection while it waits in + /// an accept queue. These would terminate the stream if not handled in any + /// way. + /// + /// # Examples + /// + /// ```no_run + /// use tokio::net::TcpListener; + /// + /// use futures::StreamExt; + /// + /// #[tokio::main] + /// async fn main() { + /// let mut listener = TcpListener::bind("127.0.0.1:8080").await.unwrap(); + /// let mut incoming = listener.incoming(); + /// + /// while let Some(stream) = incoming.next().await { + /// match stream { + /// Ok(stream) => { + /// println!("new client!"); + /// } + /// Err(e) => { /* connection failed */ } + /// } + /// } + /// } + /// ``` pub fn incoming(&mut self) -> Incoming<'_> { Incoming::new(self) } diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index 5f4787ecd3a..311bae2c70d 100644 --- a/tokio/src/net/unix/listener.rs +++ b/tokio/src/net/unix/listener.rs @@ -86,11 +86,42 @@ impl UnixListener { } } - /// Consumes this listener, returning a stream of the sockets this listener - /// accepts. + /// Returns a stream over the connections being received on this listener. /// - /// This method returns an implementation of the `Stream` trait which - /// resolves to the sockets the are accepted on this listener. + /// The returned stream will never return `None` and will also not yield the + /// peer's `SocketAddr` structure. Iterating over it is equivalent to + /// calling accept in a loop. + /// + /// # Errors + /// + /// Note that accepting a connection can lead to various errors and not all + /// of them are necessarily fatal ‒ for example having too many open file + /// descriptors or the other side closing the connection while it waits in + /// an accept queue. These would terminate the stream if not handled in any + /// way. + /// + /// # Examples + /// + /// ```no_run + /// use tokio::net::UnixListener; + /// + /// use futures::StreamExt; + /// + /// #[tokio::main] + /// async fn main() { + /// let mut listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// let mut incoming = listener.incoming(); + /// + /// while let Some(stream) = incoming.next().await { + /// match stream { + /// Ok(stream) => { + /// println!("new client!"); + /// } + /// Err(e) => { /* connection failed */ } + /// } + /// } + /// } + /// ``` pub fn incoming(&mut self) -> Incoming<'_> { Incoming::new(self) }