Clarify .pollNval and add test reading from an invalid descriptor

Author: glessard

Sources/System/IORing/IOCompletion.swift

@@ -54,6 +54,13 @@ public extension IORing.Completion {
         }
     }
 
+    /// The result of the completed operation.
+    ///
+    /// A non-negative value is the operation's success result: a byte count
+    /// for a read or a write, an event mask for a poll, and so on.
+    ///
+    /// A negative value is an `errno` code multiplied by -1. Recover the error
+    /// by negating it again: `Errno(rawValue: -completion.result)`.
     @inlinable var result: Int32 {
         get {
             rawValue.res

Sources/System/IORing/PollEvents.swift

@@ -97,9 +97,15 @@ extension IORing.Request {
         @_alwaysEmitIntoClient
         public static var pollHup: PollEvents { PollEvents(.pollHup) }
 
-        /// An event indicating the file descriptor is not open.
+        /// An event indicating that the object a descriptor refers to is no
+        /// longer valid.
         ///
-        /// This usually means the descriptor was closed, or was never valid.
+        /// This arises when the descriptor itself resolves, but the thing it
+        /// refers to has since become invalid. For example, the disconnection
+        /// of a sound device could cause this event.
+        ///
+        /// Note that a descriptor which simply does not resolve would
+        /// return the EBADF error code (Errno.badFileDescriptor).
         ///
         /// The kernel reports this event whether or not it was requested, and
         /// requesting it explicitly has no effect. Corresponds to the POSIX

Tests/SystemTests/IORingTests.swift

@@ -577,6 +577,38 @@ final class IORingTests: XCTestCase {
             XCTFail("expected POLLERR, got 0x\(String(result, radix: 16))")
         }
     }
+
+    // A completion's `result` is two things in one field: a non-negative
+    // value is an event mask, and a negative value is a negated errno. The
+    // sign is the only thing distinguishing them, so it has to be checked
+    // before the value is treated as anything else.
+    func testPollAddOnInvalidDescriptor() throws {
+        try XCTSkipIf(!uringEnabled, failureMessage)
+        var ring = try IORing(queueDepth: 8)
+
+        let request = IORing.Request.pollAdd(
+            FileDescriptor(rawValue: -1), pollEvents: .pollIn,
+            isMultiShot: false, context: 99
+        )
+        let success = try ring.submit(linkedRequests: request)
+        XCTAssertEqual(success, true)
+
+        guard let completion = ring.tryConsumeCompletion() else {
+            XCTFail("expected a completion for the failed poll")
+            return
+        }
+        XCTAssertEqual(completion.context, 99)
+
+        // A negative value for `result` marks the completion a a failure.
+        XCTAssertLessThan(completion.result, 0, "expected a failure")
+        // The negative value is the error code multiplied by -1.
+        XCTAssertEqual(Errno(rawValue: -completion.result), .badFileDescriptor)
+
+        // A negative result may look like another result code.
+        // Checking for the error must happen first.
+        let pollNval = Int32(IORing.Request.PollEvents.pollNval.rawValue)
+        XCTAssertNotEqual(completion.result & pollNval, 0)
+    }
 }
 #endif // os(Linux)
 #endif // compiler(>=6.2) && $Lifetimes