document that we do not support EPOLLONESHOT and advise the use of EPOLLET, and add debug assert to check for EPOLLONESHOT

tokio/src/io/async_fd.rs

@@ -247,8 +247,13 @@ impl<T: AsRawFd> AsyncFd<T> {
     ///
     /// These flags replace any epoll flags would normally set when registering the fd.
     ///
-    ///  **Note**: This is an [unstable API][unstable]. The public API of this may break in 1.x
-    /// releases.
+    /// # Note
+    /// This API does not support the use of `EPOLLONESHOT`.
+    /// Users are strongly advised to use `EPOLLET` to prevent the tokio IO driver from receiving
+    /// spurious wakes.
+    ///
+    /// # Stability
+    /// This is an [unstable API][unstable]. The public API of this may break in 1.x releases.
     /// See [the documentation on unstable features][unstable] for details.
     ///
     ///  [unstable]: crate#unstable-features

tokio/src/net/tcp/listener.rs

@@ -244,8 +244,13 @@ impl TcpListener {
     ///
     /// These flags replace any epoll flags would normally set when registering the fd.
     ///
-    ///  **Note**: This is an [unstable API][unstable]. The public API of this may break in 1.x
-    /// releases.
+    /// # Note
+    /// This API does not support the use of `EPOLLONESHOT`.
+    /// Users are strongly advised to use `EPOLLET` to prevent the tokio IO driver from receiving
+    /// spurious wakes.
+    ///
+    /// # Stability
+    /// This is an [unstable API][unstable]. The public API of this may break in 1.x releases.
     /// See [the documentation on unstable features][unstable] for details.
     ///
     ///  [unstable]: crate#unstable-features

tokio/src/net/unix/listener.rs

@@ -118,8 +118,13 @@ impl UnixListener {
     ///
     /// These flags replace any epoll flags would normally set when registering the fd.
     ///
-    ///  **Note**: This is an [unstable API][unstable]. The public API of this may break in 1.x
-    /// releases.
+    /// # Note
+    /// This API does not support the use of `EPOLLONESHOT`.
+    /// Users are strongly advised to use `EPOLLET` to prevent the tokio IO driver from receiving
+    /// spurious wakes.
+    ///
+    /// # Stability
+    /// This is an [unstable API][unstable]. The public API of this may break in 1.x releases.
     /// See [the documentation on unstable features][unstable] for details.
     ///
     ///  [unstable]: crate#unstable-features

tokio/src/runtime/io/registration.rs

@@ -95,6 +95,11 @@ impl Registration {
         flags: u32,
         handle: scheduler::Handle,
     ) -> io::Result<Registration> {
+        debug_assert!(
+            (flags & libc::EPOLLONESHOT as u32) == 0,
+            "Tokio does not support using EPOLLONESHOT in user-specified epoll flags"
+        );
+
         let shared = handle.driver().io().add_source_raw(io, flags)?;
 
         Ok(Registration { handle, shared })