import ApplicationServices import CoreFoundation public import CoreGraphics import Darwin public import Foundation public import ParcelCore import Synchronization import os public struct AppThreadCreatedWindow: Sendable, Equatable { public let windowID: CGWindowID public let facts: WindowFacts public let frame: CGRect public let isOnScreen: Bool public let parentWindowID: CGWindowID? package var validity: AppThreadOperationValidity? package var placementInitialFrame: CGRect? package var placementTarget: CGRect? public init( windowID: CGWindowID, facts: WindowFacts, frame: CGRect, isOnScreen: Bool, parentWindowID: CGWindowID? = nil ) { self.windowID = windowID self.facts = facts self.frame = frame self.isOnScreen = isOnScreen self.parentWindowID = parentWindowID } } /// Events contain window server IDs rather than AX objects, which stay on the app thread. public enum AppThreadEvent: Sendable, Equatable { indirect case detected(AppThreadEvent, trace: DetectionTrace) case windowCreated(CGWindowID) case windowCreatedWithFacts(AppThreadCreatedWindow) case windowDestroyed(CGWindowID) case windowMoved(CGWindowID, origin: AppThreadEventOrigin) case windowResized(CGWindowID, origin: AppThreadEventOrigin) case windowMovedWithFrame(CGWindowID, frame: CGRect, origin: AppThreadEventOrigin) case windowResizedWithFrame(CGWindowID, frame: CGRect, origin: AppThreadEventOrigin) case windowTitleChanged(CGWindowID) case windowMinimized(CGWindowID) case windowDeminimized(CGWindowID) case focusedWindowChanged case focusedWindowRead(CGWindowID?) case applicationActivated case applicationDeactivated case applicationTerminated case windowList([CGWindowID]) case reconciliation(AppThreadReconciliation) case unresponsive case responsive case failure(AppThreadFailure) } extension AppThreadEvent { static func observing(source: (any DetectionTraceSource)?, _ observation: () -> AppThreadEvent?) -> AppThreadEvent? { guard let trace = source?.begin() else { return observation() } guard let event = observation() else { trace.finish(.dropped) return nil } return .detected(event, trace: trace) } } /// A snapshot, not a claim that every window server entry should have an AX counterpart. public struct AppThreadReconciliation: Sendable, Equatable { public let axWindowIDs: [CGWindowID] public let serverWindows: [WindowServer.Window] public let axOnly: [CGWindowID] public let serverOnly: [CGWindowID] init(pid: pid_t, axWindowIDs: [CGWindowID], serverWindows: [WindowServer.Window]) { let axIDs = Set(axWindowIDs) let windows = serverWindows.filter { $0.pid == pid }.sorted { $0.number < $1.number } let serverIDs = Set(windows.map(\.number)) self.axWindowIDs = axIDs.sorted() self.serverWindows = windows self.axOnly = axIDs.subtracting(serverIDs).sorted() self.serverOnly = serverIDs.subtracting(axIDs).sorted() } } /// AX has no transaction IDs; recent write notifications are attributed provisionally. public enum AppThreadEventOrigin: Sendable, Equatable { case unattributed case possiblySelfGenerated(UUID) } public enum AppThreadFailure: Error, Sendable, Equatable { case accessibility(AXPlatformError) case stopped case runLoopUnavailable case operationOverdue case alreadyOwned(pid_t) case initialization(String) case observerCreation(Int32) case observerRegistration(notification: String, windowID: CGWindowID?, code: Int32) case observerRegistrationExhausted(notifications: [String]) case observerRemoval(notification: String, windowID: CGWindowID, code: Int32) case windowEnumeration(String) case windowServer(String) case windowIdentification(String) case windowFacts(String) case windowFrame(String) case frameWriteCleanup(String) case windowNotFound(CGWindowID) } package struct AppThreadIdentifiedWindow { package let element: AXElement package let windowID: CGWindowID package let validity: AppThreadOperationValidity } /// Owns one application's AX objects and observer on a dedicated run-loop thread. public final class AppThread: Sendable { public let events: AsyncStream private let worker: AppThreadWorker private let executor: AppThreadExecutor private let exitObserver: AppProcessObserver private let assistiveTechnology = AssistiveTechnologyState.shared private let technologySubscription: UUID public init( pid: pid_t, timeout: Float = 0.35, timeoutThreshold: Int = 3, detectionSource: (any DetectionTraceSource)? = nil, factsContext: WindowFactsContext = .init(bundleID: ""), newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? = nil ) throws { precondition(timeout > 0 && timeout.isFinite) precondition(timeoutThreshold > 0) guard AppThreadOwnerRegistry.shared.acquire(pid) else { throw AppThreadFailure.alreadyOwned(pid) } let (events, continuation) = AsyncStream.makeStream() self.events = events let worker = AppThreadWorker( pid: pid, timeout: timeout, timeoutThreshold: timeoutThreshold, events: continuation, detectionSource: detectionSource, factsContext: factsContext, newWindowTarget: newWindowTarget) self.worker = worker let executor = AppThreadExecutor( start: { worker.start() }, stop: { let error = worker.stop() AppThreadOwnerRegistry.shared.release(pid) worker.shutdownResult.complete(error) }, failure: { worker.executorFailed() } ) self.executor = executor self.exitObserver = AppProcessObserver(pid: pid) { [weak executor] in worker.stopWatchdog() continuation.yield(.applicationTerminated) executor?.shutdown() } self.technologySubscription = AssistiveTechnologyState.shared.subscribe { [weak executor] in executor?.submit(run: { worker.assistiveTechnologyChanged() }, cancel: {}) } } /// The closure runs on the owning thread. Neither it nor its result may transfer AX objects. public func perform( _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker let validity = AppThreadOperationValidity() return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in executor.submit( run: { worker.perform(operation, validity: validity, continuation: continuation) }, cancel: { continuation.resume(throwing: AppThreadFailure.stopped) } ) } } onCancel: { validity.invalidate() } } /// Reads windows and repairs their observer registrations on the owning thread. package func performWithWindows( _ operation: @escaping @Sendable ([AppThreadIdentifiedWindow]) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in let candidates = try AppThreadWindowLookup.includingAttachedSheets( in: application.windows, children: { try $0.inventoryChildren() }, role: { element in try optionalWindowFact { try element.role } }, onFailure: { worker.reportWindowIdentificationFailure($0) }) let windows = try worker.repairWindowObservers(candidates, validity: application.operationValidity) return try operation( windows.map { AppThreadIdentifiedWindow( element: $0.window, windowID: $0.id, validity: worker.validity(for: $0.id)) }) } } public func performWindow( windowID: CGWindowID, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { try await performWindow(windowID: windowID, validity: nil, operation) } package func performWindow( windowID: CGWindowID, validity: AppThreadOperationValidity?, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in do { let resolve = { try worker.resolveWindow(windowID, application: application) } if let validity { return try validity.perform(resolve: resolve, operation: operation) } return try operation(resolve()) } catch AXPlatformError.elementInvalid { worker.evictCachedWindow(windowID) throw AXPlatformError.elementInvalid } } } package func retainWindow(windowID: CGWindowID) async throws -> AppThreadWindowRequest { let worker = self.worker return try await perform { application in let window = try worker.resolveWindow(windowID, application: application) return worker.retainedWindows.insert(window.withoutCallTracking(), windowID: windowID) } } package func performWindow( request: AppThreadWindowRequest, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in let window = try worker.retainedWindows.window(for: request) return try operation(window.trackingCalls(of: application)) } } package func releaseWindow(_ request: AppThreadWindowRequest) async { let worker = self.worker await withCheckedContinuation { continuation in executor.submit( run: { worker.retainedWindows.remove(request) continuation.resume() }, cancel: { continuation.resume() }) } } /// Only final receipts prove window geometry; ongoing motion deliberately avoids AX reads. /// Final release preserves ownership; cancellation requires a larger generation before another write. public func writeFrames(_ requests: [AppThreadFrameWrite]) async throws -> AppThreadWriteBatchReceipt { var ids: Set = [] for request in requests where !ids.insert(request.windowID).inserted { throw AppThreadFrameWriteError.duplicateWindow(request.windowID) } let cancellation = AppThreadWriteCancellation() let worker = self.worker let executor = self.executor return try await withTaskCancellationHandler { await assistiveTechnology.prepare() try Task.checkCancellation() return try await executor.performBounded(timeout: 2, onAbort: { cancellation.cancel() }) { try worker.writeFrames(requests, cancellation: cancellation) } } onCancel: { cancellation.cancel() executor.submit(run: { worker.cancelFrameWritesReporting(requests) }, cancel: {}) } } public func cancelFrameWrites( windowIDs: Set? = nil, throughGeneration: UInt64? = nil ) async throws { let worker = self.worker try await perform { application in try worker.cancelFrameWrites( windowIDs: windowIDs, throughGeneration: throughGeneration, application: application) } } /// Tags matching move/resize notifications conservatively; callers must not treat a tag as proof. public func writeFrame(windowID: CGWindowID, target: CGRect, writeID: UUID = UUID()) async throws -> CGRect { await assistiveTechnology.prepare() let worker = self.worker return try await withCheckedThrowingContinuation { continuation in executor.submit( run: { do { continuation.resume( returning: try worker.writeFrame(windowID: windowID, target: target, writeID: writeID)) } catch { continuation.resume(throwing: error) } }, cancel: { continuation.resume(throwing: AppThreadFailure.stopped) }) } } /// Call after handling a frame payload, including on error, to release its latest pending sibling. public func acknowledgeMotion(windowID: CGWindowID) { let worker = self.worker executor.submit(run: { worker.acknowledgeMotion(windowID: windowID) }, cancel: {}) } /// Requests shutdown without waiting for an in-flight AX call to return. public func shutdown() { exitObserver.cancel() assistiveTechnology.unsubscribe(technologySubscription) worker.shutdownRequested.cancel() worker.stopWatchdog() executor.shutdown() } /// Unlike event delivery, this receipt remains available after the event consumer has stopped. public func shutdownRestoringFrameWrites() async throws { shutdown() try await worker.shutdownResult.wait() } deinit { exitObserver.cancel() assistiveTechnology.unsubscribe(technologySubscription) worker.shutdownRequested.cancel() worker.stopWatchdog() executor.shutdown() } } final class AppProcessObserver: @unchecked Sendable { private let source: any DispatchSourceProcess init( pid: pid_t, queue: DispatchQueue = .global(qos: .utility), onRegistration: @escaping @Sendable () -> Void = {}, onExit: @escaping @Sendable () -> Void ) { source = DispatchSource.makeProcessSource(identifier: pid, eventMask: .exit, queue: queue) source.setRegistrationHandler(handler: onRegistration) source.setEventHandler(handler: onExit) source.resume() } func cancel() { source.cancel() } deinit { source.cancel() } } final class AppThreadOwnerRegistry: Sendable { static let shared = AppThreadOwnerRegistry() private let owners = Mutex>([]) func acquire(_ pid: pid_t) -> Bool { owners.withLock { $0.insert(pid).inserted } } func release(_ pid: pid_t) { owners.withLock { _ = $0.remove(pid) } } } // This object is accessed only by its executor's thread, including observer callbacks. private final class AppThreadWorker: @unchecked Sendable { let shutdownResult = AppThreadShutdownResult() let shutdownRequested = AppThreadWriteCancellation() private let pid: pid_t private let timeout: Float private let events: AsyncStream.Continuation private let detectionSource: (any DetectionTraceSource)? private let factsContext: WindowFactsContext private let newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? private let watchdog: AXCallWatchdog private var timeouts: AppThreadTimeoutTracker private var application: AXElement? private var startupFailure: AppThreadFailure? private var observer: AXObserver? private var windows: [(raw: AXUIElement, id: CGWindowID)] = [] private var windowCache = AppThreadWindowCache() var retainedWindows = AppThreadRetainedWindows() private var windowValidities: [CGWindowID: AppThreadOperationValidity] = [:] private let frameWriter = AppThreadFrameWriter() private var frameWrites = AppThreadFrameWriteTracker() private var registrations = AppThreadRegistrationTracker() private var registrationBackoff: AppThreadRegistrationBackoff? private var registrationTimer: CFRunLoopTimer? private var initialWindowsEmitted = false private var createdWindows = AppThreadCreatedWindowTracker() private var motionMailbox = AppThreadMotionMailbox() init( pid: pid_t, timeout: Float, timeoutThreshold: Int, events: AsyncStream.Continuation, detectionSource: (any DetectionTraceSource)?, factsContext: WindowFactsContext, newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? ) { self.pid = pid self.timeout = timeout self.events = events self.detectionSource = detectionSource self.factsContext = factsContext self.newWindowTarget = newWindowTarget let deadline = max(1, Double(timeout) * 2) self.watchdog = AXCallWatchdog( deadline: deadline, overdue: { events.yield(.failure(.operationOverdue)) }) self.timeouts = AppThreadTimeoutTracker(threshold: timeoutThreshold) } func start() { do { let application = try AXElement(applicationPID: pid, timeout: timeout, watchdog: watchdog) self.application = application var observer: AXObserver? let token = watchdog.begin() let result = AXObserverCreate( pid, { _, element, notification, context in guard let context else { return } let worker = Unmanaged.fromOpaque(context).takeUnretainedValue() worker.receive(element: element, notification: notification as String) }, &observer) watchdog.end(token) guard result == .success, let observer else { let failure = AppThreadFailure.observerCreation(result.rawValue) startupFailure = failure events.yield(.failure(failure)) return } self.observer = observer CFRunLoopAddSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(observer), .defaultMode) registrationBackoff = AppThreadRegistrationBackoff() registerApplicationNotifications() } catch { record(error) let failure = AppThreadFailure.initialization(String(describing: error)) startupFailure = failure events.yield(.failure(failure)) } } func executorFailed() { events.yield(.failure(.runLoopUnavailable)) } // Shutdown can cancel deadlines while the owning thread is blocked inside AX. func stopWatchdog() { watchdog.stop() } func stop() -> (any Error)? { stopWatchdog() cancelRegistrationTimer() motionMailbox.removeAll() var cleanupError: (any Error)? if let application { do { try cancelFrameWrites(application: application) } catch { cleanupError = error events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } if let observer { CFRunLoopRemoveSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(observer), .defaultMode) } observer = nil windows.removeAll() windowCache.removeAll() retainedWindows.removeAll() for validity in windowValidities.values { validity.invalidate() } windowValidities.removeAll() application = nil events.finish() return cleanupError } func reportWindowIdentificationFailure(_ error: any Error) { events.yield(.failure(.windowIdentification(String(describing: error)))) } @discardableResult func repairWindowObservers( _ current: [AXElement], validity: AppThreadOperationValidity? = nil ) throws -> [(window: AXElement, id: CGWindowID)] { try validity?.check() let identified = try AppThreadWindowLookup.identified( in: current, identify: AppThreadWindowLookup.windowID, onFailure: { events.yield(.failure(.windowIdentification(String(describing: $0)))) }) try validity?.check() registerApplicationNotifications(initialWindows: identified.map(\.window), validity: validity) for window in identified { try validity?.check() observe(window.window, identifiedID: window.id, validity: validity) } let present = Set(identified.map(\.id)) let missing = windows.filter { !present.contains($0.id) } windows.removeAll { !present.contains($0.id) } for window in missing { forgetWindow(window.id) frameWrites.clear(windowID: window.id) registrations.remove(windowID: window.id) if let observer { for notification in Self.windowNotifications { try validity?.check() let token = watchdog.begin() let result = AXObserverRemoveNotification(observer, window.raw, notification as CFString) watchdog.end(token) if result != .success && result != .notificationNotRegistered { events.yield( .failure( .observerRemoval(notification: notification, windowID: window.id, code: result.rawValue) )) } } } } return identified } func perform( _ operation: @Sendable (AXElement) throws -> Value, validity: AppThreadOperationValidity, continuation: CheckedContinuation ) { if let startupFailure { continuation.resume(throwing: startupFailure) return } guard let application else { continuation.resume(throwing: AppThreadFailure.stopped) return } let activity = AXCallActivity(validity: validity) do { try validity.check() let result = try operation(application.tracking(activity)) try validity.check() for event in timeouts.observe(activity) { events.yield(event) } continuation.resume(returning: result) } catch { for event in timeouts.observe(activity) { events.yield(event) } continuation.resume(throwing: error) } } func evictCachedWindow(_ windowID: CGWindowID) { windowCache[windowID] = nil } func resolveWindow(_ windowID: CGWindowID, application: AXElement) throws -> AXElement { try windowCache.resolve(windowID) { let window = try AppThreadWindowLookup.find( in: application.windows, windowID: windowID, identify: AppThreadWindowLookup.windowID, focused: { try optionalWindowFact { try application.focusedWindow } }, onFailure: { events.yield(.failure(.windowIdentification(String(describing: $0)))) }) guard let window else { throw AppThreadFailure.windowNotFound(windowID) } observe(window) return window }.trackingCalls(of: application) } func writeFrame(windowID: CGWindowID, target: CGRect, writeID: UUID) throws -> CGRect { let request = AppThreadFrameWrite( windowID: windowID, target: target, writeID: writeID, generation: frameWriter.generationForStandaloneWrite(for: windowID), phase: .final) let batch = try writeFrames([request], cancellation: AppThreadWriteCancellation()) let errors = batch.windows.compactMap(\.error) + batch.cleanupErrors if errors.count == 1 { throw errors[0] } if !errors.isEmpty { throw AppThreadWriteBatchFailure(errors: errors) } guard let actual = batch.windows.first?.actual else { throw AppThreadFailure.windowFrame("A final write did not return its readback") } return actual } func writeFrames( _ requests: [AppThreadFrameWrite], cancellation: AppThreadWriteCancellation ) throws -> AppThreadWriteBatchReceipt { if let startupFailure { throw startupFailure } guard let application else { throw AppThreadFailure.stopped } guard AssistiveTechnologyState.shared.current != nil else { throw AppThreadFailure.initialization("Assistive technology observation has not started") } let interval = AppThreadWriteTrace.begin() let started = DispatchTime.now().uptimeNanoseconds let activity = AXCallActivity() let trackedApplication = application.tracking(activity) let result = frameWriter.write( requests, application: trackedApplication, assistiveTechnology: { guard let current = AssistiveTechnologyState.shared.current else { preconditionFailure("Initialized assistive technology state must remain available") } return current }, resolve: { try self.resolveWindow($0, application: trackedApplication) }, isCancelled: { cancellation.isCancelled || self.shutdownRequested.isCancelled }) for (request, receipt) in zip(requests, result.windows) { if receipt.error is AppThreadFrameWriteError { continue } frameWrites.clear(windowID: request.windowID) if let actual = receipt.actual { frameWrites.record( windowID: request.windowID, writeID: request.writeID, before: receipt.before, actual: actual, attempted: request.target) } if receipt.error as? AXPlatformError == .elementInvalid { evictCachedWindow(request.windowID) } } for event in timeouts.observe(activity) { events.yield(event) } let duration = Double(DispatchTime.now().uptimeNanoseconds - started) / 1_000_000_000 AppThreadWriteTrace.end( interval, calls: activity.results.count, duration: duration, windows: requests.count, final: requests.allSatisfy { $0.phase == .final }) return AppThreadWriteBatchReceipt( windows: result.windows, duration: duration, cleanupErrors: result.cleanupErrors, axCallCount: activity.results.count) } func cancelFrameWrites( windowIDs: Set? = nil, throughGeneration: UInt64? = nil, application: AXElement ) throws { let cancelled = try frameWriter.cancel( windowIDs: windowIDs, throughGeneration: throughGeneration, application: application) for id in cancelled { frameWrites.clear(windowID: id) } } func cancelFrameWritesReporting(_ requests: [AppThreadFrameWrite]) { guard let application else { return } for request in requests { do { try cancelFrameWrites( windowIDs: [request.windowID], throughGeneration: request.generation, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } } func assistiveTechnologyChanged() { guard let application, let technology = AssistiveTechnologyState.shared.current else { return } do { try frameWriter.refreshAssistiveTechnology(technology, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } func validity(for id: CGWindowID) -> AppThreadOperationValidity { guard let validity = windowValidities[id] else { preconditionFailure("An observed window must have an owner-thread identity") } return validity } private func forgetWindow(_ id: CGWindowID) { windowValidities.removeValue(forKey: id)?.invalidate() windowCache[id] = nil createdWindows.remove(id) motionMailbox.remove(id) guard let application else { return } do { try frameWriter.forget(id, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } private static let applicationNotifications = [kAXWindowCreatedNotification] + AppThreadFocusReader.notifications + [kAXApplicationActivatedNotification, kAXApplicationDeactivatedNotification] private static let windowNotifications = [ kAXUIElementDestroyedNotification, kAXWindowMovedNotification, kAXWindowResizedNotification, kAXTitleChangedNotification, kAXWindowMiniaturizedNotification, kAXWindowDeminiaturizedNotification, ] private func registerApplicationNotifications( initialWindows: [AXElement]? = nil, validity: AppThreadOperationValidity? = nil ) { guard let application, observer != nil, !shutdownRequested.isCancelled, validity?.isValid != false else { return } registerNotifications(Self.applicationNotifications, on: application.raw, windowID: nil, validity: validity) guard !shutdownRequested.isCancelled else { cancelRegistrationTimer() return } let missing = Self.applicationNotifications.filter { registrations.needs($0, windowID: nil) } guard missing.isEmpty else { guard registrationTimer == nil, registrationBackoff != nil else { return } guard let delay = registrationBackoff?.nextDelay() else { registrationBackoff = nil events.yield(.failure(.observerRegistrationExhausted(notifications: missing))) return } guard let timer = CFRunLoopTimerCreateWithHandler( nil, CFAbsoluteTimeGetCurrent() + delay, 0, 0, 0, { [weak self] timer in if let timer { CFRunLoopTimerInvalidate(timer) } guard let self else { return } self.registrationTimer = nil self.registerApplicationNotifications() }) else { registrationBackoff = nil events.yield(.failure(.runLoopUnavailable)) return } registrationTimer = timer CFRunLoopAddTimer(CFRunLoopGetCurrent(), timer, .defaultMode) return } registrationBackoff = nil cancelRegistrationTimer() guard !initialWindowsEmitted else { return } do { let windows: [AXElement] if let initialWindows { windows = initialWindows } else { windows = try application.windows recordSuccess() } initialWindowsEmitted = true for window in windows { guard validity?.isValid != false else { return } emitCreatedWindow(window, speculate: false) } } catch { record(error) events.yield(.failure(.windowEnumeration(String(describing: error)))) } } private func cancelRegistrationTimer() { if let registrationTimer { CFRunLoopTimerInvalidate(registrationTimer) } registrationTimer = nil } private func registerNotifications( _ notifications: [String], on element: AXUIElement, windowID: CGWindowID?, validity: AppThreadOperationValidity? = nil ) { for notification in notifications where registrations.needs(notification, windowID: windowID) { guard validity?.isValid != false else { return } register(notification, on: element, windowID: windowID) } } private func register(_ notification: String, on element: AXUIElement, windowID: CGWindowID?) { guard let observer else { return } let token = watchdog.begin() defer { watchdog.end(token) } let start = DispatchTime.now().uptimeNanoseconds let result = AXObserverAddNotification( observer, element, notification as CFString, Unmanaged.passUnretained(self).toOpaque()) let elapsed = Double(DispatchTime.now().uptimeNanoseconds - start) / 1_000_000_000 registrations.record(result, notification: notification, windowID: windowID) if result == .success || result == .notificationAlreadyRegistered { if result == .success { recordSuccess() } } else { if result == .cannotComplete && elapsed >= Double(timeout) * 0.9 { if timeouts.timedOut() { events.yield(.unresponsive) } } else { timeouts.otherFailure() } events.yield( .failure(.observerRegistration(notification: notification, windowID: windowID, code: result.rawValue))) } } private func cacheWindow(_ window: AXElement, identifiedID: CGWindowID? = nil) throws -> CGWindowID? { if let known = windows.first(where: { CFEqual($0.raw, window.raw) }) { windowCache[known.id] = window.withoutCallTracking() return known.id } guard let id = try identifiedID ?? AppThreadWindowLookup.windowID(window) else { return nil } if windows.contains(where: { $0.id == id }) { forgetWindow(id) registrations.remove(windowID: id) frameWrites.clear(windowID: id) windows.removeAll { $0.id == id } } windowValidities[id] = AppThreadOperationValidity() recordSuccess() windows.append((window.raw, id)) windowCache[id] = window.withoutCallTracking() return id } private func observe( _ window: AXElement, identifiedID: CGWindowID? = nil, validity: AppThreadOperationValidity? = nil ) { do { guard let id = try cacheWindow(window, identifiedID: identifiedID) else { return } registerNotifications(Self.windowNotifications, on: window.raw, windowID: id, validity: validity) } catch { record(error) events.yield(.failure(.windowIdentification(String(describing: error)))) } } private func createdWindowEvent(_ window: AXElement, speculate: Bool = true) -> AppThreadEvent? { let id: CGWindowID do { guard let identified = try cacheWindow(window) else { return nil } id = identified } catch { record(error) return .failure(.windowIdentification(String(describing: error))) } guard createdWindows.claim(id) else { return nil } let snapshot: AppThreadCreatedWindow do { snapshot = try readCreatedWindow(window, windowID: id) } catch { events.yield(.failure(.callback(error, fallback: AppThreadFailure.windowFacts))) return .windowCreated(id) } do { let maySpeculate = speculate && !shutdownRequested.isCancelled && !frameWriter.suppressesFrameNotification(windowID: id, pointerIsDown: false) && !CGEventSource.buttonState(.combinedSessionState, button: .left) let placed = try AppThreadSpeculativePlacement.place( snapshot, speculate: maySpeculate, assistiveTechnology: AssistiveTechnologyState.shared.current, read: newWindowTarget ) { target in let interval = AppThreadCallbackTrace.beginSpeculativeWrite(windowID: id) defer { AppThreadCallbackTrace.endSpeculativeWrite(interval) } return try writeFrame(windowID: id, target: target, writeID: UUID()) } return .windowCreatedWithFacts(placed) } catch { events.yield(.failure(.callback(error, fallback: AppThreadFailure.windowFrame))) return .windowCreatedWithFacts(snapshot) } } private func readCreatedWindow(_ window: AXElement, windowID: CGWindowID) throws -> AppThreadCreatedWindow { let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } let isOnScreen = try WindowServer().isOnScreen(windowID: windowID) var snapshot = try WindowFactsReader.gatherCreatedWindow( window: window.tracking(activity), windowID: windowID, context: factsContext, isOnScreen: isOnScreen) snapshot.validity = validity(for: windowID) return snapshot } private func emitCreatedWindow(_ window: AXElement, speculate: Bool) { let event = AppThreadEvent.observing(source: detectionSource) { createdWindowEvent(window, speculate: speculate) } if let event { yieldEvent(event) } if let id = windows.first(where: { CFEqual($0.raw, window.raw) })?.id { registerNotifications(Self.windowNotifications, on: window.raw, windowID: id) } } private func receive(element: AXUIElement, notification: String) { let interval = AppThreadCallbackTrace.begin(notification: notification) defer { AppThreadCallbackTrace.end(interval) } if notification != kAXWindowMovedNotification, notification != kAXWindowResizedNotification, let id = windows.first(where: { CFEqual($0.raw, element) })?.id, let pending = motionMailbox.flush(id) { deliver(pending) } let event = AppThreadEvent.observing(source: detectionSource) { notificationEvent(element: element, notification: notification) } if let event { yieldEvent(event) } if notification == kAXWindowCreatedNotification, let id = windows.first(where: { CFEqual($0.raw, element) })?.id { registerNotifications(Self.windowNotifications, on: element, windowID: id) } } private func yieldEvent(_ event: AppThreadEvent) { if let pending = motionMailbox.flushBefore(event) { deliver(pending) } guard let ready = motionMailbox.offer(event) else { return } deliver(ready) } private func deliver(_ marker: AppThreadEvent) { let event = AppThreadMotionMailbox.materialize(marker) { id in guard let window = windowCache[id] else { throw AppThreadFailure.windowNotFound(id) } let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } return try window.tracking(activity).frame } if let id = marker.motionWindowID, event.motionWindowID == nil { motionMailbox.remove(id) } switch events.yield(event) { case .enqueued: break case .dropped(let dropped): dropped.finishDroppedTrace() case .terminated: event.finishDroppedTrace() motionMailbox.removeAll() @unknown default: preconditionFailure("Unknown app event delivery result") } } func acknowledgeMotion(windowID: CGWindowID) { if let event = motionMailbox.acknowledge(windowID) { deliver(event) } } private func notificationEvent(element: AXUIElement, notification: String) -> AppThreadEvent? { switch notification { case kAXWindowCreatedNotification: do { let window = try AXElement(raw: element, timeout: timeout, watchdog: watchdog) return createdWindowEvent(window) } catch { record(error) return .failure(.windowIdentification(String(describing: error))) } case let name where AppThreadFocusReader.notifications.contains(name): guard let application else { return .failure(.stopped) } let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } return AppThreadFocusReader.event(for: name) { try application.tracking(activity).focusedWindowIDForCallback() } case kAXApplicationActivatedNotification: return .applicationActivated case kAXApplicationDeactivatedNotification: return .applicationDeactivated default: guard let index = windows.firstIndex(where: { CFEqual($0.raw, element) }) else { return .failure(.windowIdentification("Notification for an unobserved window: \(notification)")) } let id = windows[index].id switch notification { case kAXUIElementDestroyedNotification: windows.remove(at: index) forgetWindow(id) frameWrites.clear(windowID: id) registrations.remove(windowID: id) return .windowDestroyed(id) case kAXWindowMovedNotification: guard !didSuppressFrameNotification(windowID: id) else { return nil } return frameNotification(windowID: id, axis: .position) case kAXWindowResizedNotification: guard !didSuppressFrameNotification(windowID: id) else { return nil } return frameNotification(windowID: id, axis: .size) case kAXTitleChangedNotification: return .windowTitleChanged(id) case kAXWindowMiniaturizedNotification: return .windowMinimized(id) case kAXWindowDeminiaturizedNotification: return .windowDeminimized(id) default: break } } return nil } private func frameNotification(windowID: CGWindowID, axis: AppThreadFrameWriteTracker.Axis) -> AppThreadEvent { let origin = frameOrigin(windowID: windowID, axis: axis) switch axis { case .position: return .windowMoved(windowID, origin: origin) case .size: return .windowResized(windowID, origin: origin) } } private func didSuppressFrameNotification(windowID: CGWindowID) -> Bool { let pointerIsDown = CGEventSource.buttonState(.combinedSessionState, button: .left) return frameWriter.suppressesFrameNotification(windowID: windowID, pointerIsDown: pointerIsDown) } private func frameOrigin(windowID: CGWindowID, axis: AppThreadFrameWriteTracker.Axis) -> AppThreadEventOrigin { frameWrites.origin( windowID: windowID, axis: axis, pointerIsDown: CGEventSource.buttonState(.combinedSessionState, button: .left)) } private func record(_ error: any Error) { let timedOut: Bool if let axError = error as? AXPlatformError, case .timedOut = axError { timedOut = true } else if let frameError = error as? FrameWriteFailure { timedOut = Self.isTimeout(frameError.writeError) || Self.isTimeout(frameError.restoreError) } else { timedOut = false } if timedOut { if timeouts.timedOut() { events.yield(.unresponsive) } } else { timeouts.otherFailure() } } private static func isTimeout(_ error: any Error) -> Bool { guard let error = error as? AXPlatformError, case .timedOut = error else { return false } return true } private func recordSuccess() { if timeouts.succeeded() { events.yield(.responsive) } } } enum AppThreadWindowReconciler { static func event( pid: pid_t, axWindowIDs: [CGWindowID], read: (CGWindowListOption) throws -> [WindowServer.Window] ) -> AppThreadEvent { do { return .reconciliation( AppThreadReconciliation(pid: pid, axWindowIDs: axWindowIDs, serverWindows: try read(.optionAll))) } catch { return .failure(.windowServer(String(describing: error))) } } } package struct AppThreadWindowRequest: Hashable, Sendable { fileprivate let token: UUID fileprivate let windowID: CGWindowID } struct AppThreadRetainedWindows { private var windows: [AppThreadWindowRequest: Window] = [:] mutating func insert(_ window: Window, windowID: CGWindowID) -> AppThreadWindowRequest { let request = AppThreadWindowRequest(token: UUID(), windowID: windowID) windows[request] = window return request } func window(for request: AppThreadWindowRequest) throws -> Window { guard let window = windows[request] else { throw AppThreadFailure.windowNotFound(request.windowID) } return window } mutating func remove(_ request: AppThreadWindowRequest) { windows[request] = nil } mutating func removeAll() { windows.removeAll() } } enum AppThreadWindowLookup { static func includingAttachedSheets( in windows: [Window], children: (Window) throws -> [Window], role: (Window) throws -> String?, onFailure: (any Error) -> Void ) throws -> [Window] { var result = windows for window in windows { let candidates: [Window] do { candidates = try children(window) } catch { guard isElementLocalFailure(error) else { throw error } onFailure(error) continue } for child in candidates { do { if try role(child) == kAXSheetRole { result.append(child) } } catch { guard isElementLocalFailure(error) else { throw error } onFailure(error) } } } return result } private static func isElementLocalFailure(_ error: any Error) -> Bool { guard let error = error as? AXPlatformError else { return false } return error == .elementInvalid || error == .noValue || error == .attributeUnsupported || error == .other(AXError.illegalArgument.rawValue) } static func windowID(_ window: AXElement) throws -> CGWindowID? { try windowID(identify: { try window.windowID() }, role: { try window.role }) } static func windowID(identify: () throws -> CGWindowID, role: () throws -> String) throws -> CGWindowID? { do { return try identify() } catch let error as AXPlatformError { // Finder includes its desktop scroll area in AXWindows; it has no window identity. if error == .other(AXError.illegalArgument.rawValue), try role() == kAXScrollAreaRole { return nil } throw error } } static func identified( in windows: [Window], identify: (Window) throws -> CGWindowID?, onFailure: (any Error) -> Void ) throws -> [(window: Window, id: CGWindowID)] { var identified: [(window: Window, id: CGWindowID)] = [] var present: Set = [] for window in windows { do { guard let id = try identify(window) else { continue } guard id != 0 else { throw AXPlatformError.noValue } guard present.insert(id).inserted else { continue } identified.append((window: window, id: id)) } catch let error as AXPlatformError { // Element-local identity failures must not hide the app's other real windows. guard error == .elementInvalid || error == .noValue || error == .attributeUnsupported || error == .other(AXError.illegalArgument.rawValue) else { throw error } onFailure(error) } } return identified } static func find( in windows: [Window], windowID: CGWindowID, identify: (Window) throws -> CGWindowID?, focused: () throws -> Window? = { nil }, onFailure: (any Error) -> Void ) throws -> Window? { var firstError: (any Error)? for window in windows { do { if try identify(window) == windowID { return window } } catch { if firstError == nil { firstError = error } onFailure(error) } } // AXWindows may omit a native fullscreen window while its focused AX element remains live. if let window = try focused(), try identify(window) == windowID { return window } if let firstError { throw firstError } return nil } } extension AppThreadFailure { static func callback(_ error: any Error, fallback: (String) -> Self) -> Self { if let error = error as? AXPlatformError { return .accessibility(error) } return fallback(String(describing: error)) } } enum AppThreadFocusReader { static let notifications = [kAXFocusedWindowChangedNotification, kAXMainWindowChangedNotification] static func event(for notification: String, readID: () throws -> CGWindowID?) -> AppThreadEvent? { guard notifications.contains(notification) else { return nil } if notification == kAXMainWindowChangedNotification { return .focusedWindowChanged } return event(readID: readID) } static func event(readID: () throws -> CGWindowID?) -> AppThreadEvent { do { return .focusedWindowRead(try readID()) } catch { return .failure(.callback(error, fallback: AppThreadFailure.windowIdentification)) } } static func read( focusedWindow: () throws -> Window, identify: (Window) throws -> CGWindowID ) throws -> CGWindowID? { guard let window = try optionalWindowFact(focusedWindow) else { return nil } return try optionalWindowFact { try identify(window) } } } struct AppThreadMotionMailbox { private var inFlight: [CGWindowID: Int] = [:] private var latest: [CGWindowID: AppThreadEvent] = [:] var inFlightCount: Int { inFlight.count } var pendingCount: Int { latest.count } mutating func offer(_ event: AppThreadEvent) -> AppThreadEvent? { guard let id = event.motionWindowID else { return event } guard inFlight[id] == nil else { let previous = latest[id] latest[id] = previous?.motionOrigin == .unattributed ? event.withMotionOrigin(.unattributed) : event previous?.finishDroppedTrace() return nil } inFlight[id] = 1 return event } mutating func flush(_ id: CGWindowID) -> AppThreadEvent? { guard let event = latest.removeValue(forKey: id) else { return nil } inFlight[id, default: 0] += 1 return event } mutating func flushBefore(_ event: AppThreadEvent) -> AppThreadEvent? { guard event.motionWindowID == nil, let id = event.windowID else { return nil } return flush(id) } static func materialize( _ event: AppThreadEvent, readFrame: (CGWindowID) throws -> CGRect ) -> AppThreadEvent { if case .detected(let observation, let trace) = event { return .detected(materialize(observation, readFrame: readFrame), trace: trace) } do { switch event { case .windowMoved(let id, let origin): return .windowMovedWithFrame(id, frame: try readFrame(id), origin: origin) case .windowResized(let id, let origin): return .windowResizedWithFrame(id, frame: try readFrame(id), origin: origin) default: return event } } catch let error as AppThreadFailure { return .failure(error) } catch { return .failure(.callback(error, fallback: AppThreadFailure.windowFrame)) } } mutating func acknowledge(_ id: CGWindowID) -> AppThreadEvent? { guard let outstanding = inFlight[id] else { return nil } if outstanding > 1 { inFlight[id] = outstanding - 1 return nil } if let event = latest.removeValue(forKey: id) { return event } inFlight[id] = nil return nil } mutating func remove(_ id: CGWindowID) { latest.removeValue(forKey: id)?.finishDroppedTrace() inFlight[id] = nil } mutating func removeAll() { for event in latest.values { event.finishDroppedTrace() } latest.removeAll() inFlight.removeAll() } } extension AppThreadEvent { var motionWindowID: CGWindowID? { switch self { case .detected(let event, _): return event.motionWindowID case .windowMoved(let id, _), .windowResized(let id, _), .windowMovedWithFrame(let id, _, _), .windowResizedWithFrame(let id, _, _): return id default: return nil } } var windowID: CGWindowID? { switch self { case .detected(let event, _): return event.windowID case .windowCreated(let id), .windowDestroyed(let id), .windowTitleChanged(let id), .windowMinimized(let id), .windowDeminimized(let id): return id case .windowCreatedWithFacts(let window): return window.windowID case .focusedWindowRead(let id): return id default: return motionWindowID } } fileprivate var motionOrigin: AppThreadEventOrigin? { switch self { case .detected(let event, _): return event.motionOrigin case .windowMoved(_, let origin), .windowResized(_, let origin), .windowMovedWithFrame(_, _, let origin), .windowResizedWithFrame(_, _, let origin): return origin default: return nil } } fileprivate func withMotionOrigin(_ origin: AppThreadEventOrigin) -> AppThreadEvent { switch self { case .detected(let event, let trace): return .detected(event.withMotionOrigin(origin), trace: trace) case .windowMoved(let id, _): return .windowMoved(id, origin: origin) case .windowResized(let id, _): return .windowResized(id, origin: origin) case .windowMovedWithFrame(let id, let frame, _): return .windowMovedWithFrame(id, frame: frame, origin: origin) case .windowResizedWithFrame(let id, let frame, _): return .windowResizedWithFrame(id, frame: frame, origin: origin) default: return self } } func finishDroppedTrace() { if case .detected(let event, let trace) = self { trace.dropIfUnowned() event.finishDroppedTrace() } } } struct AppThreadCreatedWindowTracker { private var emitted: Set = [] mutating func claim(_ id: CGWindowID) -> Bool { emitted.insert(id).inserted } mutating func remove(_ id: CGWindowID) { emitted.remove(id) } } struct AppThreadRegistrationBackoff { static let maximumAgeNanoseconds: UInt64 = 1_000_000_000 static let maximumAttempts = 16 private let startedAt: UInt64 private var step = 0 init(now: UInt64 = DispatchTime.now().uptimeNanoseconds) { startedAt = now } mutating func nextDelay(now: UInt64 = DispatchTime.now().uptimeNanoseconds) -> Double? { guard step < Self.maximumAttempts, now >= startedAt, now - startedAt < Self.maximumAgeNanoseconds else { return nil } let remaining = Self.maximumAgeNanoseconds - (now - startedAt) let delay = min(UInt64(5_000_000) << min(step, 4), remaining) step += 1 return Double(delay) / 1_000_000_000 } } enum AppThreadSpeculativePlacement { static func place( _ window: AppThreadCreatedWindow, speculate: Bool, assistiveTechnology: AssistiveTechnology?, read: (@Sendable (AppThreadCreatedWindow) -> CGRect?)?, write: (CGRect) throws -> CGRect ) throws -> AppThreadCreatedWindow { guard speculate, let target = try target(for: window, assistiveTechnology: assistiveTechnology, read: read) else { return window } var placed = AppThreadCreatedWindow( windowID: window.windowID, facts: window.facts, frame: try write(target), isOnScreen: window.isOnScreen, parentWindowID: window.parentWindowID) placed.placementInitialFrame = window.frame placed.placementTarget = target return placed } static func target( for window: AppThreadCreatedWindow, assistiveTechnology: AssistiveTechnology?, read: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? ) throws -> CGRect? { guard window.isOnScreen, assistiveTechnology != nil, let target = read?(window) else { return nil } guard [target.origin.x, target.origin.y, target.size.width, target.size.height].allSatisfy(\.isFinite), target.size.width > 0, target.size.height > 0 else { throw AXPlatformError.unexpectedValue("Speculative window target") } return target } } private enum AppThreadCallbackTrace { private static let enabled = ProcessInfo.processInfo.environment["PARCEL_TRACE"] == "1" private static let signposter = OSSignposter(subsystem: "com.parcel", category: .pointsOfInterest) static func begin(notification: String) -> OSSignpostIntervalState? { guard enabled else { return nil } return signposter.beginInterval( "appthread.callback", id: signposter.makeSignpostID(), "notification=\(notification, privacy: .public)") } static func end(_ interval: OSSignpostIntervalState?) { if let interval { signposter.endInterval("appthread.callback", interval) } } static func beginSpeculativeWrite(windowID: CGWindowID) -> OSSignpostIntervalState? { guard enabled else { return nil } return signposter.beginInterval( "appthread.speculativeWrite", id: signposter.makeSignpostID(), "window=\(windowID)") } static func endSpeculativeWrite(_ interval: OSSignpostIntervalState?) { if let interval { signposter.endInterval("appthread.speculativeWrite", interval) } } } struct AppThreadRegistrationTracker { private var completed: [CGWindowID?: Set] = [:] func needs(_ notification: String, windowID: CGWindowID?) -> Bool { !(completed[windowID]?.contains(notification) ?? false) } mutating func record(_ result: AXError, notification: String, windowID: CGWindowID?) { if result == .success || result == .notificationAlreadyRegistered || result == .notificationUnsupported { completed[windowID, default: []].insert(notification) } } mutating func remove(windowID: CGWindowID) { completed.removeValue(forKey: windowID) } } struct AppThreadFrameWriteTracker { enum Axis { case position, size } static let maximumAgeNanoseconds: UInt64 = 500_000_000 private struct Candidate { let id: UUID let frame: CGRect let createdAt: UInt64 var position: Bool var size: Bool } private var candidates: [CGWindowID: Candidate] = [:] mutating func record( windowID: CGWindowID, writeID: UUID, before: CGRect?, actual: CGRect, attempted: CGRect? = nil, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) { let attemptedWrite = attempted.map { $0 != before } ?? false let position = before?.origin != actual.origin || attemptedWrite let size = before?.size != actual.size || attemptedWrite candidates[windowID] = position || size ? Candidate(id: writeID, frame: actual, createdAt: now, position: position, size: size) : nil } mutating func clear(windowID: CGWindowID) { candidates.removeValue(forKey: windowID) } mutating func hasCandidate( windowID: CGWindowID, axis: Axis, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> Bool { guard let candidate = candidates[windowID] else { return false } guard now >= candidate.createdAt && now - candidate.createdAt < Self.maximumAgeNanoseconds else { clear(windowID: windowID) return false } switch axis { case .position: return candidate.position case .size: return candidate.size } } mutating func origin( windowID: CGWindowID, axis: Axis, pointerIsDown: Bool, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> AppThreadEventOrigin { if pointerIsDown { clear(windowID: windowID) return .unattributed } guard hasCandidate(windowID: windowID, axis: axis, now: now), let candidate = candidates[windowID] else { return .unattributed } return .possiblySelfGenerated(candidate.id) } mutating func match( windowID: CGWindowID, axis: Axis, frame: CGRect, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> AppThreadEventOrigin { guard hasCandidate(windowID: windowID, axis: axis, now: now), let candidateValue = candidates[windowID] else { return .unattributed } guard candidateValue.frame == frame else { clear(windowID: windowID) return .unattributed } return .possiblySelfGenerated(candidateValue.id) } } struct AppThreadTimeoutTracker { private let threshold: Int private var count = 0 private var wedged = false init(threshold: Int) { precondition(threshold > 0) self.threshold = threshold } mutating func timedOut() -> Bool { if count < threshold { count += 1 } guard count == threshold && !wedged else { return false } wedged = true return true } mutating func succeeded() -> Bool { count = 0 let wasWedged = wedged wedged = false return wasWedged } mutating func otherFailure() { count = 0 } mutating func observe(_ activity: AXCallActivity) -> [AppThreadEvent] { var events: [AppThreadEvent] = [] for result in activity.results { switch result { case nil: if succeeded() { events.append(.responsive) } case .timedOut: if timedOut() { events.append(.unresponsive) } case .some: otherFailure() } } return events } } // The waiter can finish before AX returns. Expired queued jobs must never start. final class AppThreadBoundedJob: Sendable { private struct State { var result: Result? var continuation: CheckedContinuation? var timer: AXWatchdogDeadline? } private let state = Mutex(State()) private let onAbort: @Sendable () -> Void init(onAbort: @escaping @Sendable () -> Void) { self.onAbort = onAbort } var isPending: Bool { state.withLock { $0.result == nil } } func wait(timeout: Double) async throws -> Value { precondition(timeout.isFinite && timeout > 0) return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in let result = state.withLock { state -> Result? in if let result = state.result { return result } state.continuation = continuation return nil } if let result { continuation.resume(with: result) return } let timer = AXWatchdogDeadline(deadline: timeout, queue: .global(qos: .utility)) { [weak self] in self?.finish(.failure(AXPlatformError.timedOut), abort: true) } let installed = state.withLock { state in guard state.result == nil else { return false } state.timer = timer return true } if !installed { timer.cancel() } } } onCancel: { self.finish(.failure(CancellationError()), abort: true) } } func finish(_ result: Result, abort: Bool = false) { let completed = state.withLock { state -> (CheckedContinuation?, AXWatchdogDeadline?)? in guard state.result == nil else { return nil } state.result = result let completed = (state.continuation, state.timer) state.continuation = nil state.timer = nil return completed } guard let completed else { return } if abort { onAbort() } completed.1?.cancel() completed.0?.resume(with: result) } } extension AppThreadExecutor { func performBounded( timeout: Double, onAbort: @escaping @Sendable () -> Void = {}, _ operation: @escaping @Sendable () throws -> Value ) async throws -> Value { let job = AppThreadBoundedJob(onAbort: onAbort) return try await withTaskCancellationHandler { try Task.checkCancellation() submit( run: { guard job.isPending else { return } do { job.finish(.success(try operation())) } catch { job.finish(.failure(error)) } }, cancel: { job.finish(.failure(AppThreadFailure.stopped), abort: true) }) return try await job.wait(timeout: timeout) } onCancel: { job.finish(.failure(CancellationError()), abort: true) } } } // The lock protects the queue and run-loop handles; jobs themselves only run on the owner thread. final class AppThreadExecutor: @unchecked Sendable { private struct Job: Sendable { let run: @Sendable () -> Void let cancel: @Sendable () -> Void } private let lock = NSLock() private var jobs: [Job] = [] private var stopping = false private var runLoop: CFRunLoop? private var source: CFRunLoopSource? private let start: @Sendable () -> Void private let stop: @Sendable () -> Void private let failure: @Sendable () -> Void init( start: @escaping @Sendable () -> Void, stop: @escaping @Sendable () -> Void, failure: @escaping @Sendable () -> Void = {} ) { self.start = start self.stop = stop self.failure = failure Thread { [self] in threadMain() }.start() } func submit(run: @escaping @Sendable () -> Void, cancel: @escaping @Sendable () -> Void) { lock.lock() guard !stopping else { lock.unlock() cancel() return } jobs.append(Job(run: run, cancel: cancel)) signalLocked() lock.unlock() } func shutdown() { lock.lock() guard !stopping else { lock.unlock() return } stopping = true let cancelled = jobs jobs.removeAll() signalLocked() lock.unlock() for job in cancelled { job.cancel() } } private func signalLocked() { if let source { CFRunLoopSourceSignal(source) } if let runLoop { CFRunLoopWakeUp(runLoop) } } private func threadMain() { guard let runLoop = CFRunLoopGetCurrent() else { failure() shutdown() stop() return } var context = CFRunLoopSourceContext( version: 0, info: Unmanaged.passUnretained(self).toOpaque(), retain: nil, release: nil, copyDescription: nil, equal: nil, hash: nil, schedule: nil, cancel: nil, perform: { info in guard let info else { return } Unmanaged.fromOpaque(info).takeUnretainedValue().drain() } ) guard let source = CFRunLoopSourceCreate(nil, 0, &context) else { failure() shutdown() stop() return } CFRunLoopAddSource(runLoop, source, .defaultMode) lock.lock() self.runLoop = runLoop self.source = source signalLocked() lock.unlock() start() CFRunLoopRun() lock.lock() let unexpectedExit = !stopping lock.unlock() if unexpectedExit { failure() } shutdown() stop() CFRunLoopRemoveSource(runLoop, source, .defaultMode) lock.lock() self.source = nil self.runLoop = nil lock.unlock() } private func drain() { lock.lock() if stopping { lock.unlock() CFRunLoopStop(CFRunLoopGetCurrent()) return } guard !jobs.isEmpty else { lock.unlock() return } let job = jobs.removeFirst() if !jobs.isEmpty { signalLocked() } lock.unlock() job.run() } }