From e53b92a9939565edb33575fff296804279e5e419 Mon Sep 17 00:00:00 2001
From: "M.Amin Rayej" <m.amin.rayej@gmail.com>
Date: Sun, 28 Jan 2024 00:00:15 +0330
Subject: [PATCH] io: clarify `clear_ready` docs (#6304)

---
 tokio/src/io/async_fd.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs
index b27c60bf6c7..aaf17584198 100644
--- a/tokio/src/io/async_fd.rs
+++ b/tokio/src/io/async_fd.rs
@@ -826,6 +826,10 @@ impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
     /// _actually observes_ that the file descriptor is _not_ ready. Do not call
     /// it simply because, for example, a read succeeded; it should be called
     /// when a read is observed to block.
+    ///
+    /// This method only clears readiness events that happened before the creation of this guard.
+    /// In other words, if the IO resource becomes ready between the creation of the guard and
+    /// this call to `clear_ready`, then the readiness is not actually cleared.
     pub fn clear_ready(&mut self) {
         if let Some(event) = self.event.take() {
             self.async_fd.registration.clear_readiness(event);
@@ -846,6 +850,10 @@ impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
     /// block. For example when a read blocks when using a combined interest,
     /// only clear `Ready::READABLE`.
     ///
+    /// This method only clears readiness events that happened before the creation of this guard.
+    /// In other words, if the IO resource becomes ready between the creation of the guard and
+    /// this call to `clear_ready`, then the readiness is not actually cleared.
+    ///
     /// # Examples
     ///
     /// Concurrently read and write to a [`std::net::TcpStream`] on the same task without
@@ -1042,6 +1050,10 @@ impl<'a, Inner: AsRawFd> AsyncFdReadyMutGuard<'a, Inner> {
     /// _actually observes_ that the file descriptor is _not_ ready. Do not call
     /// it simply because, for example, a read succeeded; it should be called
     /// when a read is observed to block.
+    ///
+    /// This method only clears readiness events that happened before the creation of this guard.
+    /// In other words, if the IO resource becomes ready between the creation of the guard and
+    /// this call to `clear_ready`, then the readiness is not actually cleared.
     pub fn clear_ready(&mut self) {
         if let Some(event) = self.event.take() {
             self.async_fd.registration.clear_readiness(event);
@@ -1062,6 +1074,10 @@ impl<'a, Inner: AsRawFd> AsyncFdReadyMutGuard<'a, Inner> {
     /// block. For example when a read blocks when using a combined interest,
     /// only clear `Ready::READABLE`.
     ///
+    /// This method only clears readiness events that happened before the creation of this guard.
+    /// In other words, if the IO resource becomes ready between the creation of the guard and
+    /// this call to `clear_ready`, then the readiness is not actually cleared.
+    ///
     /// # Examples
     ///
     /// Concurrently read and write to a [`std::net::TcpStream`] on the same task without