Define a dedicated error type for HandleOrNull and HandleOrInvalid.

Define a `NotHandle` type, that implements `std::error::Error`, and use
it as the error type in `HandleOrNull` and `HandleOrInvalid`.

Author: sunfishcode

library/std/src/error.rs

@@ -604,6 +604,10 @@ impl Error for alloc::collections::TryReserveError {}
 #[unstable(feature = "duration_checked_float", issue = "83400")]
 impl Error for time::FromFloatSecsError {}
 
+#[cfg(windows)]
+#[unstable(feature = "io_safety", issue = "87074")]
+impl Error for crate::os::windows::io::NotHandle {}
+
 // Copied from `any.rs`.
 impl dyn Error + 'static {
     /// Returns `true` if the inner type is the same as `T`.

library/std/src/os/windows/io/handle.rs

@@ -142,17 +142,17 @@ impl BorrowedHandle<'_> {
 }
 
 impl TryFrom<HandleOrNull> for OwnedHandle {
-    type Error = ();
+    type Error = NotHandle;
 
     #[inline]
-    fn try_from(handle_or_null: HandleOrNull) -> Result<Self, ()> {
+    fn try_from(handle_or_null: HandleOrNull) -> Result<Self, NotHandle> {
         let owned_handle = handle_or_null.0;
         if owned_handle.handle.is_null() {
             // Don't call `CloseHandle`; it'd be harmless, except that it could
             // overwrite the `GetLastError` error.
             forget(owned_handle);
 
-            Err(())
+            Err(NotHandle(()))
         } else {
             Ok(owned_handle)
         }
@@ -200,23 +200,37 @@ impl OwnedHandle {
 }
 
 impl TryFrom<HandleOrInvalid> for OwnedHandle {
-    type Error = ();
+    type Error = NotHandle;
 
     #[inline]
-    fn try_from(handle_or_invalid: HandleOrInvalid) -> Result<Self, ()> {
+    fn try_from(handle_or_invalid: HandleOrInvalid) -> Result<Self, NotHandle> {
         let owned_handle = handle_or_invalid.0;
         if owned_handle.handle == c::INVALID_HANDLE_VALUE {
             // Don't call `CloseHandle`; it'd be harmless, except that it could
             // overwrite the `GetLastError` error.
             forget(owned_handle);
 
-            Err(())
+            Err(NotHandle(()))
         } else {
             Ok(owned_handle)
         }
     }
 }
 
+/// This is the error type used by [`HandleOrInvalid`] and
+/// [`HandleOrNull`] when attempting to convert into a handle,
+/// to indicate that the value is not a handle.
+#[unstable(feature = "io_safety", issue = "87074")]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct NotHandle(());
+
+#[unstable(feature = "io_safety", issue = "87074")]
+impl fmt::Display for NotHandle {
+    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+        "the return value of a Windows API call indicated an error".fmt(fmt)
+    }
+}
+
 impl AsRawHandle for BorrowedHandle<'_> {
     #[inline]
     fn as_raw_handle(&self) -> RawHandle {