From 47aaf79554744162601f6cdc5fabd6fd05acb2db Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 26 Jan 2022 15:58:45 -0800 Subject: [PATCH] Add documentation about `BorrowedFd::to_owned`. Following up on #88564, this adds documentation explaining why `BorrowedFd::to_owned` returns another `BorrowedFd` rather than an `OwnedFd`. And similar for `BorrowedHandle` and `BorrowedSocket`. --- library/std/src/os/fd/owned.rs | 4 ++++ library/std/src/os/windows/io/handle.rs | 4 ++++ library/std/src/os/windows/io/socket.rs | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/library/std/src/os/fd/owned.rs b/library/std/src/os/fd/owned.rs index 0b6588db92c83..6a2f804551df6 100644 --- a/library/std/src/os/fd/owned.rs +++ b/library/std/src/os/fd/owned.rs @@ -21,6 +21,10 @@ use crate::sys_common::{AsInner, FromInner, IntoInner}; /// descriptor, so it can be used in FFI in places where a file descriptor is /// passed as an argument, it is not captured or consumed, and it never has the /// value `-1`. +/// +/// This type's `.to_owned()` implementation returns another `BorrowedFd` +/// rather than an `OwnedFd`. It just makes a trivial copy of the raw file +/// descriptor, which is then borrowed under the same lifetime. #[derive(Copy, Clone)] #[repr(transparent)] #[rustc_layout_scalar_valid_range_start(0)] diff --git a/library/std/src/os/windows/io/handle.rs b/library/std/src/os/windows/io/handle.rs index e37ce633a129a..f7a67a54a1d7b 100644 --- a/library/std/src/os/windows/io/handle.rs +++ b/library/std/src/os/windows/io/handle.rs @@ -28,6 +28,10 @@ use crate::sys_common::{AsInner, FromInner, IntoInner}; /// And, it *may* have the value `NULL` (0), which can occur when consoles are /// detached from processes, or when `windows_subsystem` is used. /// +/// This type's `.to_owned()` implementation returns another `BorrowedHandle` +/// rather than an `OwnedHandle`. It just makes a trivial copy of the raw +/// handle, which is then borrowed under the same lifetime. +/// /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 #[derive(Copy, Clone)] #[repr(transparent)] diff --git a/library/std/src/os/windows/io/socket.rs b/library/std/src/os/windows/io/socket.rs index 26b569bcdd362..a7c8eef93d891 100644 --- a/library/std/src/os/windows/io/socket.rs +++ b/library/std/src/os/windows/io/socket.rs @@ -21,6 +21,10 @@ use crate::sys::cvt; /// so it can be used in FFI in places where a socket is passed as an argument, /// it is not captured or consumed, and it never has the value /// `INVALID_SOCKET`. +/// +/// This type's `.to_owned()` implementation returns another `BorrowedSocket` +/// rather than an `OwnedSocket`. It just makes a trivial copy of the raw +/// socket, which is then borrowed under the same lifetime. #[derive(Copy, Clone)] #[repr(transparent)] #[rustc_layout_scalar_valid_range_start(0)]