net: add track_caller to public APIs (#4805)

Functions that may panic can be annotated with #[track_caller] so that
in the event of a panic, the function where the user called the
panicking function is shown instead of the file and line within Tokio
source.

This change adds #[track_caller] to all the non-unstable public net APIs
in the main tokio crate where the documentation describes how the
function may panic due to incorrect context or inputs.  Not all panic
cases can have #[track_caller] applied fully as the callstack passes
through a closure which isn't yet supported by the annotation (e.g. net
functions called from outside a tokio runtime).

Additionally, the documentation was updated to indicate additional cases
in which the public net functions may panic (the same as the io
functions).

Tests are included to cover each potentially panicking function.

Refs: #4413

Author: hds

tokio/src/io/poll_evented.rs

@@ -77,6 +77,7 @@ impl<E: Source> PollEvented<E> {
     /// 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]
     #[cfg_attr(feature = "signal", allow(unused))]
     pub(crate) fn new(io: E) -> io::Result<Self> {
         PollEvented::new_with_interest(io, Interest::READABLE | Interest::WRITABLE)
@@ -97,6 +98,7 @@ impl<E: Source> PollEvented<E> {
     /// a future driven by a tokio runtime, otherwise runtime can be set
     /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter)
     /// function.
+    #[track_caller]
     #[cfg_attr(feature = "signal", allow(unused))]
     pub(crate) fn new_with_interest(io: E, interest: Interest) -> io::Result<Self> {
         Self::new_with_interest_and_handle(io, interest, Handle::current())

tokio/src/net/tcp/listener.rs

@@ -221,11 +221,13 @@ impl TcpListener {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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_std(listener: net::TcpListener) -> io::Result<TcpListener> {
         let io = mio::net::TcpListener::from_std(listener);
         let io = PollEvented::new(io)?;

tokio/src/net/tcp/stream.rs

@@ -186,11 +186,13 @@ impl TcpStream {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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_std(stream: std::net::TcpStream) -> io::Result<TcpStream> {
         let io = mio::net::TcpStream::from_std(stream);
         let io = PollEvented::new(io)?;

tokio/src/net/udp.rs

@@ -170,6 +170,7 @@ impl UdpSocket {
         UdpSocket::new(sys)
     }
 
+    #[track_caller]
     fn new(socket: mio::net::UdpSocket) -> io::Result<UdpSocket> {
         let io = PollEvented::new(socket)?;
         Ok(UdpSocket { io })
@@ -210,6 +211,7 @@ impl UdpSocket {
     /// # Ok(())
     /// # }
     /// ```
+    #[track_caller]
     pub fn from_std(socket: net::UdpSocket) -> io::Result<UdpSocket> {
         let io = mio::net::UdpSocket::from_std(socket);
         UdpSocket::new(io)

tokio/src/net/unix/datagram/socket.rs

@@ -430,7 +430,8 @@ impl UnixDatagram {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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
@@ -457,6 +458,7 @@ impl UnixDatagram {
     /// # Ok(())
     /// # }
     /// ```
+    #[track_caller]
     pub fn from_std(datagram: net::UnixDatagram) -> io::Result<UnixDatagram> {
         let socket = mio::net::UnixDatagram::from_std(datagram);
         let io = PollEvented::new(socket)?;

tokio/src/net/unix/listener.rs

@@ -54,11 +54,13 @@ impl UnixListener {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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 bind<P>(path: P) -> io::Result<UnixListener>
     where
         P: AsRef<Path>,
@@ -77,11 +79,13 @@ impl UnixListener {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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_std(listener: net::UnixListener) -> io::Result<UnixListener> {
         let listener = mio::net::UnixListener::from_std(listener);
         let io = PollEvented::new(listener)?;

tokio/src/net/unix/stream.rs

@@ -699,11 +699,13 @@ impl UnixStream {
     ///
     /// # Panics
     ///
-    /// This function panics if thread-local runtime is not set.
+    /// 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_std(stream: net::UnixStream) -> io::Result<UnixStream> {
         let stream = mio::net::UnixStream::from_std(stream);
         let io = PollEvented::new(stream)?;

tokio/src/net/windows/named_pipe.rs

@@ -2020,6 +2020,7 @@ impl ServerOptions {
     /// let builder = ServerOptions::new().max_instances(255);
     /// # Ok(()) }
     /// ```
+    #[track_caller]
     pub fn max_instances(&mut self, instances: usize) -> &mut Self {
         assert!(instances < 255, "cannot specify more than 254 instances");
         self.max_instances = instances as DWORD;

tokio/src/runtime/context.rs

@@ -24,6 +24,7 @@ pub(crate) fn current() -> Handle {
 }
 
 cfg_io_driver! {
+    #[track_caller]
     pub(crate) fn io_handle() -> crate::runtime::driver::IoHandle {
         match CONTEXT.try_with(|ctx| {
             let ctx = ctx.borrow();

tokio/tests/net_panic.rs

@@ -0,0 +1,188 @@
+#![warn(rust_2018_idioms)]
+#![cfg(all(feature = "full", not(target_os = "wasi")))]
+
+use std::error::Error;
+use tokio::net::{TcpListener, TcpStream};
+use tokio::runtime::{Builder, Runtime};
+
+mod support {
+    pub mod panic;
+}
+use support::panic::test_panic;
+
+#[test]
+fn udp_socket_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    use std::net::SocketAddr;
+    use tokio::net::UdpSocket;
+
+    let addr = "127.0.0.1:8080".parse::<SocketAddr>().unwrap();
+    let std_sock = std::net::UdpSocket::bind(addr).unwrap();
+    std_sock.set_nonblocking(true).unwrap();
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _sock = UdpSocket::from_std(std_sock);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+fn tcp_listener_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    let std_listener = std::net::TcpListener::bind("127.0.0.1:8080").unwrap();
+    std_listener.set_nonblocking(true).unwrap();
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = TcpListener::from_std(std_listener);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+fn tcp_stream_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    let std_listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+
+    let std_stream = std::net::TcpStream::connect(std_listener.local_addr().unwrap()).unwrap();
+    std_stream.set_nonblocking(true).unwrap();
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = TcpStream::from_std(std_stream);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+#[cfg(unix)]
+fn unix_listener_bind_panic_caller() -> Result<(), Box<dyn Error>> {
+    use tokio::net::UnixListener;
+
+    let dir = tempfile::tempdir().unwrap();
+    let sock_path = dir.path().join("socket");
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = UnixListener::bind(&sock_path);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+#[cfg(unix)]
+fn unix_listener_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    use tokio::net::UnixListener;
+
+    let dir = tempfile::tempdir().unwrap();
+    let sock_path = dir.path().join("socket");
+    let std_listener = std::os::unix::net::UnixListener::bind(&sock_path).unwrap();
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = UnixListener::from_std(std_listener);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+#[cfg(unix)]
+fn unix_stream_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    use tokio::net::UnixStream;
+
+    let dir = tempfile::tempdir().unwrap();
+    let sock_path = dir.path().join("socket");
+    let _std_listener = std::os::unix::net::UnixListener::bind(&sock_path).unwrap();
+    let std_stream = std::os::unix::net::UnixStream::connect(&sock_path).unwrap();
+
+    let panic_location_file = test_panic(|| {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = UnixStream::from_std(std_stream);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+#[cfg(unix)]
+fn unix_datagram_from_std_panic_caller() -> Result<(), Box<dyn Error>> {
+    use std::os::unix::net::UnixDatagram as StdUDS;
+    use tokio::net::UnixDatagram;
+
+    let dir = tempfile::tempdir().unwrap();
+    let sock_path = dir.path().join("socket");
+
+    // Bind the socket to a filesystem path
+    // /let socket_path = tmp.path().join("socket");
+    let std_socket = StdUDS::bind(&sock_path).unwrap();
+    std_socket.set_nonblocking(true).unwrap();
+
+    let panic_location_file = test_panic(move || {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let _ = UnixDatagram::from_std(std_socket);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+#[test]
+#[cfg(windows)]
+fn server_options_max_instances_panic_caller() -> Result<(), Box<dyn Error>> {
+    use tokio::net::windows::named_pipe::ServerOptions;
+
+    let panic_location_file = test_panic(move || {
+        let rt = runtime_without_io();
+        rt.block_on(async {
+            let mut options = ServerOptions::new();
+            options.max_instances(255);
+        });
+    });
+
+    // The panic location should be in this file
+    assert_eq!(&panic_location_file.unwrap(), file!());
+
+    Ok(())
+}
+
+// Runtime without `enable_io` so it has no IO driver set.
+fn runtime_without_io() -> Runtime {
+    Builder::new_current_thread().build().unwrap()
+}