Add Looper.Handle.pollOnce()

Author: colemancda

Sources/AndroidLooper/Looper.swift

@@ -112,7 +112,7 @@ public extension Looper {
 public extension Looper {
 
     /// Access the underlying opaque pointer.
-    func withUnsafePointer<E, Result>(_ body: (OpaquePointer) throws(E) -> Result) throws(E) -> Result where E: Error {
+    func withUnsafePointer<E, Result>(_ body: (OpaquePointer) throws(E) -> Result) throws(E) -> Result where E: Swift.Error {
         try body(handle.pointer)
     }
 
@@ -125,13 +125,82 @@ public extension Looper {
     func wake() {
         handle.wake()
     }
+    
+    /**
+     * Removes a previously added file descriptor from the looper.
+     *
+     * When this method returns, it is safe to close the file descriptor since the looper
+     * will no longer have a reference to it.  However, it is possible for the callback to
+     * already be running or for it to run one last time if the file descriptor was already
+     * signalled.  Calling code is responsible for ensuring that this case is safely handled.
+     * For example, if the callback takes care of removing itself during its own execution either
+     * by returning 0 or by calling this method, then it can be guaranteed to not be invoked
+     * again at any later time unless registered anew.
+     *
+     * Returns 1 if the file descriptor was removed, 0 if none was previously registered
+     * or -1 if an error occurred.
+     *
+     * This method can be called on any thread.
+     * This method may block briefly if it needs to wake the poll.
+     */
+    func remove(fileDescriptor: FileDescriptor) throws(AndroidLooperError) {
+        try handle.remove(fileDescriptor: fileDescriptor).map(fileDescriptor).get()
+    }
 }
 
 // MARK: - Supporting Types
 
 public extension Looper {
 
+    
+}
+
+internal extension Looper.Handle {
+    
     typealias Callback = @convention(c) (CInt, CInt, UnsafeMutableRawPointer?) -> CInt
+    
+    /// 1 if the file descriptor was removed, 0 if none was previously registered or -1 if an error occurred.
+    enum RemoveFileDescriptorResult: CInt, Sendable, CaseIterable {
+        
+        /// File descriptor was not previously registered.
+        case invalid = 0
+        
+        /// File descriptor was removed.
+        case removed = 1
+        
+        /// Error ocurred
+        case error = -1
+    }
+    
+    struct PollResult: Identifiable {
+        public let id: CInt
+        public let fd: FileDescriptor
+        public let events: Looper.Events
+        public let data: UnsafeRawPointer?
+    }
+}
+
+internal extension Looper.Handle.RemoveFileDescriptorResult {
+    
+    init(_ raw: RawValue) {
+        guard let value = Self.init(rawValue: raw) else {
+            assertionFailure("Invalid \(Self.self): \(raw)")
+            self = .error
+            return
+        }
+        self = value
+    }
+    
+    func map(_ value: FileDescriptor) -> Result<Void, AndroidLooperError> {
+        switch self {
+        case .removed:
+            return .success(())
+        case .invalid:
+            return .failure(.fileDescriptorNotRegistered(value))
+        case .error:
+            return .failure(.removeFileDescriptor(value))
+        }
+    }
 }
 
 internal extension Looper {
@@ -223,15 +292,24 @@ internal extension Looper.Handle {
      * This method may block briefly if it needs to wake the poll.
      */
     func add(
-        fileDescriptor fd: FileDescriptor,
+        fileDescriptor: FileDescriptor,
         id: CInt = CInt(ALOOPER_POLL_CALLBACK),
         events: Looper.Events = .input,
-        callback: Looper.Callback? = nil,
+        callback: Callback? = nil,
         data: UnsafeMutableRawPointer? = nil
-    ) -> Bool {
+    ) -> Result<Void, AndroidLooperError> {
         let id = callback != nil ? CInt(ALOOPER_POLL_CALLBACK) : id
-        let result = ALooper_addFd(pointer, fd.rawValue, id, Int32(events.rawValue), callback, data)
-        return result == 1
+        let result = ALooper_addFd(
+            pointer, fileDescriptor.rawValue,
+            id,
+            Int32(events.rawValue),
+            callback,
+            data
+        )
+        guard result == 1 else {
+            return .failure(.addFileDescriptor(fileDescriptor))
+        }
+        return .success(())
     }
 
     /**
@@ -251,7 +329,74 @@ internal extension Looper.Handle {
      * This method can be called on any thread.
      * This method may block briefly if it needs to wake the poll.
      */
-    func remove(fileDescriptor: FileDescriptor) -> CInt { // TODO: Create Looper.RemoveResult
-        ALooper_removeFd(pointer, fileDescriptor.rawValue)
+    func remove(fileDescriptor: FileDescriptor) -> RemoveFileDescriptorResult {
+        let result = ALooper_removeFd(pointer, fileDescriptor.rawValue)
+        return .init(result)
+    }
+    
+    /// Waits for events to be available, with optional timeout in milliseconds.
+    @available(macOS 13.0, *)
+    func pollOnce(duration: Duration? = nil) -> Result<PollResult?, AndroidLooperError> {
+        pollOnce(milliseconds: duration?.milliseconds)
+    }
+    
+    /**
+     * Waits for events to be available, with optional timeout in milliseconds.
+     * Invokes callbacks for all file descriptors on which an event occurred.
+     *
+     * If the timeout is zero, returns immediately without blocking.
+     * If the timeout is negative, waits indefinitely until an event appears.
+     *
+     * Returns ALOOPER_POLL_WAKE if the poll was awoken using ALooper_wake() before
+     * the timeout expired and no callbacks were invoked and no other file
+     * descriptors were ready. **All return values may also imply
+     * ALOOPER_POLL_WAKE.**
+     *
+     * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked. The poll
+     * may also have been explicitly woken by ALooper_wake.
+     *
+     * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given timeout
+     * expired. The poll may also have been explicitly woken by ALooper_wake.
+     *
+     * Returns ALOOPER_POLL_ERROR if the calling thread has no associated Looper or
+     * for unrecoverable internal errors. The poll may also have been explicitly
+     * woken by ALooper_wake.
+     *
+     * Returns a value >= 0 containing an identifier (the same identifier `ident`
+     * passed to ALooper_addFd()) if its file descriptor has data and it has no
+     * callback function (requiring the caller here to handle it).  In this (and
+     * only this) case outFd, outEvents and outData will contain the poll events and
+     * data associated with the fd, otherwise they will be set to NULL. The poll may
+     * also have been explicitly woken by ALooper_wake.
+     *
+     * This method does not return until it has finished invoking the appropriate callbacks
+     * for all file descriptors that were signalled.
+     */
+    func pollOnce(milliseconds: Double? = nil) -> Result<PollResult?, AndroidLooperError> {
+        var outFd: CInt = -1
+        var outEvents: CInt = 0
+        var outData: UnsafeMutableRawPointer?
+        let timeoutMillis: CInt = milliseconds.map { CInt($0) } ?? 0
+        
+        let err = ALooper_pollOnce(timeoutMillis, &outFd, &outEvents, &outData)
+        switch Int(err) {
+        case ALOOPER_POLL_WAKE:
+            fallthrough
+        case ALOOPER_POLL_CALLBACK:
+            return .success(nil)
+        case ALOOPER_POLL_TIMEOUT:
+            return .failure(.pollTimeout)
+        case ALOOPER_POLL_ERROR:
+            return .failure(.pollError)
+        default:
+            return .success(
+                PollResult(
+                    id: err,
+                    fd: .init(rawValue: outFd),
+                    events: Looper.Events(rawValue: Int(outEvents)),
+                    data: outData
+                )
+            )
+        }
     }
 }