Rollup merge of #158074 - valentynkt:docs/accept-transient-errors, r=Darksonn

Document transient connection errors from TcpListener::accept

`TcpListener::accept` can return an error that belongs to a single incoming
connection, not to the listener, for example a connection aborted by the peer
before it could be accepted (`ConnectionAborted`). The listener stays usable, so
a server looping over connections usually wants to log the error and keep
accepting rather than treat it as fatal. This was not documented, and the
`incoming` example treated every error as a failed connection.

This implements the libs-team decision in #142557: document these transient
errors instead of changing `accept` to retry them, since retrying would hide
errors that some callers want to observe.

Changes:
- Add an `# Errors` section to `accept` describing this behavior, without
  listing specific error codes since some may be more permanent than others.
- Note that `Interrupted` errors are retried internally on Unix.
- Add the same pointer to `incoming` and `into_incoming`, which are `accept`
  in a loop.

Addresses #142557.

r? rust-lang/libs

Author: JonathanBrouwer

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