From 91169992b2ed0cf8844dbaa0b4024f9db588a629 Mon Sep 17 00:00:00 2001
From: Alice Ryhl <aliceryhl@google.com>
Date: Fri, 6 Sep 2024 09:52:08 +0200
Subject: [PATCH] io: recommend `OwnedFd` with `AsyncFd` (#6821)

Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
 spellcheck.dic           | 3 ++-
 tokio/src/io/async_fd.rs | 7 +++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/spellcheck.dic b/spellcheck.dic
index 238e24f7dc3..83b9d684dcb 100644
--- a/spellcheck.dic
+++ b/spellcheck.dic
@@ -1,4 +1,4 @@
-285
+286
 &
 +
 <
@@ -99,6 +99,7 @@ errored
 EWMA
 expirations
 fcntl
+fd
 fd's
 FIFOs
 filename
diff --git a/tokio/src/io/async_fd.rs b/tokio/src/io/async_fd.rs
index 33829367473..9a511441d66 100644
--- a/tokio/src/io/async_fd.rs
+++ b/tokio/src/io/async_fd.rs
@@ -21,11 +21,13 @@ use std::task::{ready, Context, Poll};
 /// the [`AsyncFd`] is dropped.
 ///
 /// The [`AsyncFd`] takes ownership of an arbitrary object to represent the IO
-/// object. It is intended that this object will handle closing the file
+/// object. It is intended that the inner object will handle closing the file
 /// descriptor when it is dropped, avoiding resource leaks and ensuring that the
 /// [`AsyncFd`] can clean up the registration before closing the file descriptor.
 /// The [`AsyncFd::into_inner`] function can be used to extract the inner object
-/// to retake control from the tokio IO reactor.
+/// to retake control from the tokio IO reactor. The [`OwnedFd`] type is often
+/// used as the inner object, as it is the simplest type that closes the fd on
+/// drop.
 ///
 /// The inner object is required to implement [`AsRawFd`]. This file descriptor
 /// must not change while [`AsyncFd`] owns the inner object, i.e. the
@@ -175,6 +177,7 @@ use std::task::{ready, Context, Poll};
 /// [`TcpStream::poll_read_ready`]: struct@crate::net::TcpStream
 /// [`AsyncRead`]: trait@crate::io::AsyncRead
 /// [`AsyncWrite`]: trait@crate::io::AsyncWrite
+/// [`OwnedFd`]: struct@std::os::fd::OwnedFd
 pub struct AsyncFd<T: AsRawFd> {
     registration: Registration,
     // The inner value is always present. the Option is required for `drop` and `into_inner`.