added TcpListener::bind_with_backlog to both sys_common and std::net

Also added TcpListener::DEFAULT_BACKLOG to document the default
backlog (currently 128).

Author: BartMassey

library/std/src/net/tcp.rs

@@ -707,10 +707,52 @@ impl fmt::Debug for TcpStream {
 }
 
 impl TcpListener {
+    /// Default "backlog" for [`TcpListener::bind`]. See
+    /// [`TcpListener::bind_with_backlog`] for an explanation of backlog
+    /// values.
+    #[unstable(feature = "bind_with_backlog", issue = "none")]
+    pub const DEFAULT_BACKLOG: usize = 128;
+
     /// Creates a new `TcpListener` which will be bound to the specified
     /// address.
     ///
-    /// The returned listener is ready for accepting connections.
+    /// The given backlog specifies the maximum number of outstanding
+    /// connections that will be buffered in the OS waiting to be accepted by
+    /// [`TcpListener::accept`]. The backlog argument overrides the default
+    /// specified by [`TcpListener::DEFAULT_BACKLOG`]; that default is
+    /// reasonable for most use cases.
+    ///
+    /// This function is otherwise [`TcpListener::bind`]: see that
+    /// documentation for full details of operation.
+    ///
+    /// # Examples
+    ///
+    /// Creates a TCP listener bound to `127.0.0.1:80` with a backlog of 1000:
+    ///
+    /// ```no_run
+    /// use std::net::TcpListener;
+    ///
+    /// let listener = TcpListener::bind_with_backlog("127.0.0.1:80", 1000).unwrap();
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// The specified backlog may be larger than supported by the underlying
+    /// system. In this case an [`io::Error`] with
+    /// [`io::ErrorKind::InvalidData`] will be returned.
+    #[unstable(feature = "bind_with_backlog", issue = "none")]
+    pub fn bind_with_backlog<A: ToSocketAddrs>(addr: A, backlog: usize) -> io::Result<TcpListener> {
+        super::each_addr(addr, move |a| net_imp::TcpListener::bind_with_backlog(a, backlog))
+            .map(TcpListener)
+    }
+
+    /// Creates a new `TcpListener` which will be bound to the specified
+    /// address. The returned listener is ready for accepting
+    /// connections.
+    ///
+    /// The listener will have a backlog given by
+    /// [`TcpListener::DEFAULT_BACKLOG`]. See the documentation for
+    /// [`TcpListener::bind_with_backlog`] for further information.
     ///
     /// Binding with a port number of 0 will request that the OS assigns a port
     /// to this listener. The port allocated can be queried via the
@@ -748,7 +790,7 @@ impl TcpListener {
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener> {
-        super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener)
+        Self::bind_with_backlog(addr, TcpListener::DEFAULT_BACKLOG)
     }
 
     /// Returns the local socket address of this listener.

library/std/src/sys_common/net.rs

@@ -363,9 +363,17 @@ pub struct TcpListener {
 }
 
 impl TcpListener {
-    pub fn bind(addr: io::Result<&SocketAddr>) -> io::Result<TcpListener> {
+    pub fn bind_with_backlog(
+        addr: io::Result<&SocketAddr>,
+        backlog: usize,
+    ) -> io::Result<TcpListener> {
         let addr = addr?;
 
+        // Type-convert the backlog
+        let backlog = backlog
+            .try_into()
+            .map_err(|e| crate::io::Error::new(crate::io::ErrorKind::InvalidData, e))?;
+
         init();
 
         let sock = Socket::new(addr, c::SOCK_STREAM)?;
@@ -385,7 +393,7 @@ impl TcpListener {
         cvt(unsafe { c::bind(sock.as_raw(), addrp, len as _) })?;
 
         // Start listening
-        cvt(unsafe { c::listen(sock.as_raw(), 128) })?;
+        cvt(unsafe { c::listen(sock.as_raw(), backlog) })?;
         Ok(TcpListener { inner: sock })
     }