diff --git a/library/std/src/net/tcp.rs b/library/std/src/net/tcp.rs index 2e8779e05ca76..b673abdff7ba1 100644 --- a/library/std/src/net/tcp.rs +++ b/library/std/src/net/tcp.rs @@ -876,6 +876,29 @@ impl TcpListener { /// is established. When established, the corresponding [`TcpStream`] and the /// remote peer's address will be returned. /// + /// # Errors + /// + /// Some errors this function returns do not indicate a problem with the + /// listener itself, and a program serving a long-lived listener will + /// usually want to handle them and keep accepting connections rather than + /// treat them as fatal. These include, but are not limited to: + /// + /// - An error specific to a single incoming connection that failed before + /// it could be accepted, such as one aborted by the peer + /// ([`ConnectionAborted`]). A later call may succeed immediately. + /// - An error from reaching the per-process or system-wide open file + /// descriptor limit. The call can be retried once other file descriptors + /// have been closed, typically after a short delay. + /// - An error from failing to allocate memory while accepting a connection + /// ([`OutOfMemory`]). + /// + /// Which errors can occur is platform-specific. On Unix, [`Interrupted`] + /// errors are retried internally rather than being returned. + /// + /// [`ConnectionAborted`]: io::ErrorKind::ConnectionAborted + /// [`OutOfMemory`]: io::ErrorKind::OutOfMemory + /// [`Interrupted`]: io::ErrorKind::Interrupted + /// /// # Examples /// /// ```no_run @@ -902,6 +925,11 @@ impl TcpListener { /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to /// calling [`TcpListener::accept`] in a loop. /// + /// # Errors + /// + /// Each connection yielded by the iterator can fail for the same reasons as + /// [`TcpListener::accept`]; see its documentation for details. + /// /// # Examples /// /// ```no_run @@ -937,6 +965,11 @@ impl TcpListener { /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to /// calling [`TcpListener::accept`] in a loop. /// + /// # Errors + /// + /// Each connection yielded by the iterator can fail for the same reasons as + /// [`TcpListener::accept`]; see its documentation for details. + /// /// # Examples /// /// ```no_run