From 20ae4dafbbf176fcc74188642003c5fd709a2652 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 2 Feb 2022 16:17:17 -0800 Subject: [PATCH] Update the documentation for {As,Into,From}Raw{Fd,Handle,Socket} This ports the changes proposed in rust-lang/rust#93562 to io-lifetimes. Specifically, remove the redundant comments on `OwnedHandle::from_raw_handle` and `OwnedSocket::from_raw_socket`, and remove the `FromRawHandle` impls for `HandleOrInvalid` and `HandleOrNull`. --- src/types.rs | 34 +++++++++++----------------------- 1 file changed, 11 insertions(+), 23 deletions(-) diff --git a/src/types.rs b/src/types.rs index 0703941..881171b 100644 --- a/src/types.rs +++ b/src/types.rs @@ -399,12 +399,6 @@ impl FromRawFd for OwnedFd { #[cfg(windows)] impl FromRawHandle for OwnedHandle { - /// Constructs a new instance of `Self` from the given raw handle. - /// - /// # Safety - /// - /// The resource pointed to by `raw` must be open and suitable for assuming - /// ownership. #[inline] unsafe fn from_raw_handle(handle: RawHandle) -> Self { Self { handle } @@ -413,12 +407,6 @@ impl FromRawHandle for OwnedHandle { #[cfg(windows)] impl FromRawSocket for OwnedSocket { - /// Constructs a new instance of `Self` from the given raw socket. - /// - /// # Safety - /// - /// The resource pointed to by `raw` must be open and suitable for assuming - /// ownership. #[inline] unsafe fn from_raw_socket(socket: RawSocket) -> Self { debug_assert_ne!(socket, INVALID_SOCKET as RawSocket); @@ -427,7 +415,7 @@ impl FromRawSocket for OwnedSocket { } #[cfg(windows)] -impl FromRawHandle for HandleOrInvalid { +impl HandleOrInvalid { /// Constructs a new instance of `Self` from the given `RawHandle` returned /// from a Windows API that uses `INVALID_HANDLE_VALUE` to indicate /// failure, such as `CreateFileW`. @@ -437,20 +425,20 @@ impl FromRawHandle for HandleOrInvalid { /// /// # Safety /// - /// The resource pointed to by `handle` must be either open and otherwise - /// unowned, null, or equal to `INVALID_HANDLE_VALUE` (-1). Note that not - /// all Windows APIs use `INVALID_HANDLE_VALUE` for errors; see [here] for - /// the full story. + /// The passed `handle` value must either satisfy the safety requirements + /// of [`FromRawHandle::from_raw_handle`], or be + /// `INVALID_HANDLE_VALUE` (-1). Note that not all Windows APIs use + /// `INVALID_HANDLE_VALUE` for errors; see [here] for the full story. /// /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 #[inline] - unsafe fn from_raw_handle(handle: RawHandle) -> Self { + pub unsafe fn from_raw_handle(handle: RawHandle) -> Self { Self(handle) } } #[cfg(windows)] -impl FromRawHandle for HandleOrNull { +impl HandleOrNull { /// Constructs a new instance of `Self` from the given `RawHandle` returned /// from a Windows API that uses null to indicate failure, such as /// `CreateThread`. @@ -460,13 +448,13 @@ impl FromRawHandle for HandleOrNull { /// /// # Safety /// - /// The resource pointed to by `handle` must be either open and otherwise - /// unowned, or null. Note that not all Windows APIs use null for errors; - /// see [here] for the full story. + /// The passed `handle` value must either satisfy the safety requirements + /// of [`FromRawHandle::from_raw_handle`], or be null. Note that not all + /// Windows APIs use null for errors; see [here] for the full story. /// /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 #[inline] - unsafe fn from_raw_handle(handle: RawHandle) -> Self { + pub unsafe fn from_raw_handle(handle: RawHandle) -> Self { Self(handle) } }