Update naming around TcpListener::from_std so that it's harder to misuse

tokio/src/net/tcp/listener.rs

@@ -191,6 +191,50 @@ impl TcpListener {
         }
     }
 
+    /// Creates new `TcpListener` from a `std::net::TcpListener`.
+    ///
+    /// This function is intended to be used to wrap a TCP listener from the
+    /// standard library in the Tokio equivalent.
+    ///
+    /// This API is typically paired with the `socket2` crate and the `Socket`
+    /// type to build up and customize a listener before it's shipped off to the
+    /// backing event loop. This allows configuration of options like
+    /// `SO_REUSEPORT`, binding to multiple addresses, etc.
+    ///
+    /// # Notes
+    ///
+    /// This sets the socket to non-blocking mode if not already done, which
+    /// is necessary for normal operation within Tokio.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use std::error::Error;
+    /// use tokio::net::TcpListener;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> Result<(), Box<dyn Error>> {
+    ///     let std_listener = std::net::TcpListener::bind("127.0.0.1:0")?;
+    ///     std_listener.set_nonblocking(true)?;
+    ///     let listener = TcpListener::from_std(std_listener)?;
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
+    /// # Panics
+    ///
+    /// This function panics if it is not called from within a runtime with
+    /// IO enabled.
+    ///
+    /// The runtime is usually set implicitly when this function is called
+    /// from a future driven by a tokio runtime, otherwise runtime can be set
+    /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter) function.
+    #[track_caller]
+    pub fn from_tcp(listener: net::TcpListener) -> io::Result<TcpListener> {
+        listener.set_nonblocking(true)?;
+        Self::from_tcp_unchecked(listener)
+    }
+
     /// Creates new `TcpListener` from a `std::net::TcpListener`.
     ///
     /// This function is intended to be used to wrap a TCP listener from the
@@ -210,6 +254,9 @@ impl TcpListener {
     ///
     /// [`set_nonblocking`]: std::net::TcpListener::set_nonblocking
     ///
+    /// You may generally prefer using [`from_tcp`](TcpListener::from_tcp),
+    /// which does that for you if not already done.
+    ///
     /// # Examples
     ///
     /// ```rust,no_run
@@ -234,12 +281,26 @@ impl TcpListener {
     /// from a future driven by a tokio runtime, otherwise runtime can be set
     /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter) function.
     #[track_caller]
-    pub fn from_std(listener: net::TcpListener) -> io::Result<TcpListener> {
+    pub fn from_tcp_unchecked(listener: net::TcpListener) -> io::Result<TcpListener> {
         let io = mio::net::TcpListener::from_std(listener);
         let io = PollEvented::new(io)?;
         Ok(TcpListener { io })
     }
 
+    /// Creates new `TcpListener` from a `std::net::TcpListener`.
+    ///
+    /// Deprecated because easy to misuse and naming doesn't warn enough about it
+    /// (you may want to favor using
+    /// [`from_tcp`](TcpListener::from_tcp) instead of
+    /// [`from_tcp_unchecked`](TcpListener::from_tcp_unchecked))
+    ///
+    /// This has the same behavior as [`TcpListener::from_tcp_unchecked`].
+    #[track_caller]
+    #[deprecated = "Easy to misuse - use from_tcp or from_tcp_unchecked instead"]
+    pub fn from_std(listener: net::TcpListener) -> io::Result<TcpListener> {
+        Self::from_tcp_unchecked(listener)
+    }
+
     /// Turns a [`tokio::net::TcpListener`] into a [`std::net::TcpListener`].
     ///
     /// The returned [`std::net::TcpListener`] will have nonblocking mode set as
@@ -384,9 +445,21 @@ impl TryFrom<net::TcpListener> for TcpListener {
     /// Consumes stream, returning the tokio I/O object.
     ///
     /// This is equivalent to
-    /// [`TcpListener::from_std(stream)`](TcpListener::from_std).
+    /// [`TcpListener::from_tcp_unchecked(stream)`](TcpListener::from_tcp_unchecked).
+    ///
+    /// # Notes
+    ///
+    /// The caller is responsible for ensuring that the listener is in
+    /// non-blocking mode. Otherwise all I/O operations on the listener
+    /// will block the thread, which will cause unexpected behavior.
+    /// Non-blocking mode can be set using [`set_nonblocking`].
+    ///
+    /// [`set_nonblocking`]: std::net::TcpListener::set_nonblocking
+    ///
+    /// You may generally prefer using [`TcpListener::from_tcp`],
+    /// which does that for you if not already done.
     fn try_from(stream: net::TcpListener) -> Result<Self, Self::Error> {
-        Self::from_std(stream)
+        Self::from_tcp_unchecked(stream)
     }
 }
 

tokio/tests/io_driver_drop.rs

@@ -12,7 +12,7 @@ fn tcp_doesnt_block() {
     let listener = {
         let _enter = rt.enter();
         let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
-        TcpListener::from_std(listener).unwrap()
+        TcpListener::from_std(listener).unwrap() // Given the name of this test it looks like it hasn't fulfilled its purpose when going from mio 0.6 to mio 0.7 -> TODO investigate why
     };
 
     drop(rt);

tokio/tests/net_panic.rs

@@ -40,7 +40,7 @@ fn tcp_listener_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
     let panic_location_file = test_panic(|| {
         let rt = runtime_without_io();
         rt.block_on(async {
-            let _ = TcpListener::from_std(std_listener);
+            let _ = TcpListener::from_tcp_unchecked(std_listener);
         });
     });
 

tokio/tests/no_rt.rs

@@ -37,5 +37,7 @@ async fn timeout_value() {
     expected = "there is no reactor running, must be called from the context of a Tokio 1.x runtime"
 )]
 fn io_panics_when_no_tokio_context() {
-    let _ = tokio::net::TcpListener::from_std(std::net::TcpListener::bind("127.0.0.1:0").unwrap());
+    let _ = tokio::net::TcpListener::from_tcp_unchecked(
+        std::net::TcpListener::bind("127.0.0.1:0").unwrap(),
+    );
 }