docs(fs,net): comments on close (#821)

* feat(fs,win): close for named pipe

* docs(fs): comments on `close`

* docs(net): comments on `close`

* fix(net): typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Berrysoft

compio-fs/src/file.rs

@@ -83,6 +83,14 @@ impl File {
 
     /// Close the file. If the returned future is dropped before polling, the
     /// file won't be closed.
+    ///
+    /// As [`File`] is clonable, users can call `close` on a clone, but the
+    /// future will never complete until all clones are dropped. Some
+    /// operations may keep a strong reference to the file, so the future
+    /// may never complete if there are pending operations.
+    ///
+    /// It's OK to drop the [`File`] directly without calling `close`, but the
+    /// file may not be closed immediately.
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         // Make sure that fd won't be dropped after `close` called.
         // Users may call this method and drop the future immediately. In that way

compio-fs/src/named_pipe.rs

@@ -12,7 +12,7 @@ use compio_io::{
     AsyncRead, AsyncReadAt, AsyncReadManaged, AsyncReadManagedAt, AsyncWrite, AsyncWriteAt,
     util::Splittable,
 };
-use compio_runtime::{BorrowedBuffer, BufferPool, fd::AsyncFd};
+use compio_runtime::{BorrowedBuffer, BufferPool};
 use widestring::U16CString;
 use windows_sys::Win32::{
     Storage::FileSystem::{
@@ -91,7 +91,7 @@ use crate::{File, OpenOptions};
 /// [Windows named pipe]: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
 #[derive(Debug, Clone)]
 pub struct NamedPipeServer {
-    handle: AsyncFd<std::fs::File>,
+    handle: File,
 }
 
 impl NamedPipeServer {
@@ -180,6 +180,14 @@ impl NamedPipeServer {
         syscall!(BOOL, DisconnectNamedPipe(self.as_raw_fd() as _))?;
         Ok(())
     }
+
+    /// Close the server. If the returned future is dropped before polling, the
+    /// server won't be closed.
+    ///
+    /// See [`File::close`] for more details.
+    pub fn close(self) -> impl Future<Output = io::Result<()>> {
+        self.handle.close()
+    }
 }
 
 impl AsyncRead for NamedPipeServer {
@@ -192,7 +200,7 @@ impl AsyncRead for NamedPipeServer {
 impl AsyncRead for &NamedPipeServer {
     #[inline]
     async fn read<B: IoBufMut>(&mut self, buffer: B) -> BufResult<usize, B> {
-        (&self.handle).read(buffer).await
+        self.handle.read_at(buffer, 0).await
     }
 }
 
@@ -219,7 +227,7 @@ impl AsyncReadManaged for &NamedPipeServer {
         len: usize,
     ) -> io::Result<Self::Buffer<'a>> {
         // The position is ignored.
-        (&self.handle).read_managed(buffer_pool, len).await
+        self.handle.read_managed_at(buffer_pool, len, 0).await
     }
 }
 
@@ -243,7 +251,7 @@ impl AsyncWrite for NamedPipeServer {
 impl AsyncWrite for &NamedPipeServer {
     #[inline]
     async fn write<T: IoBuf>(&mut self, buffer: T) -> BufResult<usize, T> {
-        (&self.handle).write(buffer).await
+        (&self.handle).write_at(buffer, 0).await
     }
 
     #[inline]
@@ -344,6 +352,14 @@ impl NamedPipeClient {
         // SAFETY: we're ensuring the lifetime of the named pipe.
         unsafe { named_pipe_info(self.as_raw_fd()) }
     }
+
+    /// Close the client. If the returned future is dropped before polling, the
+    /// client won't be closed.
+    ///
+    /// See [`File::close`] for more details.
+    pub fn close(self) -> impl Future<Output = io::Result<()>> {
+        self.handle.close()
+    }
 }
 
 impl AsyncRead for NamedPipeClient {
@@ -1065,7 +1081,7 @@ impl ServerOptions {
         )?;
 
         Ok(NamedPipeServer {
-            handle: AsyncFd::new(unsafe { std::fs::File::from_raw_handle(h as _) })?,
+            handle: File::from_std(unsafe { std::fs::File::from_raw_handle(h as _) })?,
         })
     }
 }

compio-fs/src/pipe/mod.rs

@@ -342,6 +342,8 @@ impl Sender {
 
     /// Close the pipe. If the returned future is dropped before polling, the
     /// pipe won't be closed.
+    ///
+    /// See [`File::close`] for more details.
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.file.close()
     }
@@ -477,6 +479,8 @@ impl Receiver {
 
     /// Close the pipe. If the returned future is dropped before polling, the
     /// pipe won't be closed.
+    ///
+    /// See [`File::close`] for more details.
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.file.close()
     }

compio-net/src/tcp.rs

@@ -104,6 +104,10 @@ impl TcpListener {
 
     /// Close the socket. If the returned future is dropped before polling, the
     /// socket won't be closed.
+    ///
+    /// See [`TcpStream::close`] for more details.
+    ///
+    /// [`TcpStream::close`]: crate::tcp::TcpStream::close
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.inner.close()
     }
@@ -303,6 +307,14 @@ impl TcpStream {
 
     /// Close the socket. If the returned future is dropped before polling, the
     /// socket won't be closed.
+    ///
+    /// As the socket is clonable, users can call `close` on a clone, but the
+    /// future will never complete until all clones are dropped. Some
+    /// operations may keep a strong reference to the socket, so the future
+    /// may never complete if there are pending operations.
+    ///
+    /// It's OK to drop the socket directly without calling `close`, but the
+    /// socket may not be closed immediately.
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.inner.close()
     }

compio-net/src/udp.rs

@@ -136,6 +136,10 @@ impl UdpSocket {
 
     /// Close the socket. If the returned future is dropped before polling, the
     /// socket won't be closed.
+    ///
+    /// See [`TcpStream::close`] for more details.
+    ///
+    /// [`TcpStream::close`]: crate::tcp::TcpStream::close
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.inner.close()
     }

compio-net/src/unix.rs

@@ -97,6 +97,10 @@ impl UnixListener {
 
     /// Close the socket. If the returned future is dropped before polling, the
     /// socket won't be closed.
+    ///
+    /// See [`TcpStream::close`] for more details.
+    ///
+    /// [`TcpStream::close`]: crate::tcp::TcpStream::close
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.inner.close()
     }
@@ -248,6 +252,10 @@ impl UnixStream {
 
     /// Close the socket. If the returned future is dropped before polling, the
     /// socket won't be closed.
+    ///
+    /// See [`TcpStream::close`] for more details.
+    ///
+    /// [`TcpStream::close`]: crate::tcp::TcpStream::close
     pub fn close(self) -> impl Future<Output = io::Result<()>> {
         self.inner.close()
     }