Repository: tokio-rs/tokio
File: tokio/src/io/async_fd.rs (Rust)

Code before:
impl<T: AsRawFd> std::os::unix::io::AsFd for AsyncFd<T> {
    fn as_fd(&self) -> std::os::unix::io::BorrowedFd<'_> {
        unsafe { std::os::unix::io::BorrowedFd::borrow_raw(self.as_raw_fd()) }
    }
}

impl<T: std::fmt::Debug + AsRawFd> std::fmt::Debug for AsyncFd<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AsyncFd")
            .field("inner", &self.inner)
            .finish()
    }
}

impl<T: AsRawFd> Drop for AsyncFd<T> {
    fn drop(&mut self) {
        let _ = self.take_inner();
    }
}

impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
    /// Indicates to tokio that the file descriptor is no longer ready. All
    /// internal readiness flags will be cleared, and tokio will wait for the
    /// next readiness notification after the last operation from the OS. This
    /// implies that if a readiness notification occurs following the last operation
    /// but prior to invoking `clear_ready`, it will not be cleared.
    ///
    /// This function is commonly used with guards returned by [`AsyncFd::readable`] and
    /// [`AsyncFd::writable`].
    ///
    /// It is critical that this function not be called unless your code
    /// _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.
    pub fn clear_ready(&mut self) {
        if let Some(event) = self.event.take() {
            self.async_fd.registration.clear_readiness(event);
        }
    }

    /// Indicates to tokio that the file descriptor no longer has a specific readiness.
    /// The internal readiness flag will be cleared, and tokio will wait for the
    /// next readiness notification after the last operation from the OS. This
    /// implies that if a readiness notification occurs following the last operation
    /// but prior to invoking `clear_ready`, it will not be cleared.
    ///
    /// This function is useful in combination with the [`AsyncFd::ready`] method when a
    /// combined interest like `Interest::READABLE | Interest::WRITABLE` is used.
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready for the provided `Ready`.

Review comment (suggestion):
Instead of modifying the current paragraph, I think it would be more clear to add a new paragraph at the end.

Code after:
impl<T: AsRawFd> std::os::unix::io::AsFd for AsyncFd<T> {
    fn as_fd(&self) -> std::os::unix::io::BorrowedFd<'_> {
        unsafe { std::os::unix::io::BorrowedFd::borrow_raw(self.as_raw_fd()) }
    }
}

impl<T: std::fmt::Debug + AsRawFd> std::fmt::Debug for AsyncFd<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AsyncFd")
            .field("inner", &self.inner)
            .finish()
    }
}

impl<T: AsRawFd> Drop for AsyncFd<T> {
    fn drop(&mut self) {
        let _ = self.take_inner();
    }
}

impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
    /// Indicates to tokio that the file descriptor is no longer ready. All
    /// internal readiness flags will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    ///
    /// This function is commonly used with guards returned by [`AsyncFd::readable`] and
    /// [`AsyncFd::writable`].
    ///
    /// It is critical that this function not be called unless your code
    /// _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);
        }
    }

    /// Indicates to tokio that the file descriptor no longer has a specific readiness.
    /// The internal readiness flag will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    ///
    /// This function is useful in combination with the [`AsyncFd::ready`] method when a
    /// combined interest like `Interest::READABLE | Interest::WRITABLE` is used.
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready for the provided `Ready`.