Some preliminary work on TaskScheduler

Author: mattmassicotte

README.md

@@ -20,7 +20,7 @@ dependencies: [
 
 ## Concept
 
-[`URLSession`](https://developer.apple.com/documentation/foundation/urlsession)'s background upload and download facilities are relatively straightforward to get started with. But, they are surprisingly difficult to manage. The core challange is an operation could start and/or complete while your process isn't even running. You cannot just wait for a completion handler or `await` call. This usually means you have to involve peristent storage to juggle state across process launches.
+[`URLSession`](https://developer.apple.com/documentation/foundation/urlsession)'s background upload and download facilities are relatively straightforward to get started with. But, they are surprisingly difficult to manage. The core challenge is an operation could start and/or complete while your process isn't even running. You cannot just wait for a completion handler or `await` call. This usually means you have to involve persistent storage to juggle state across process launches.
 
 You also typically need to make use of system-provided API to reconnect your session to any work that has happened between launches. This can be done a few different ways, depending on your type of project and how you'd like your system to work.
 
@@ -125,6 +125,12 @@ struct YourWidget: Widget {
 }
 ```
 
+### Background Tasks
+
+It's disappointing that the [BackgroundTasks](https://developer.apple.com/documentation/backgroundtasks) framework isn't available for macOS. The library includes some preliminary work to build a nearly source-compatible version of `BGTaskScheduler` that works across all platforms. As of right now, these types aren't public because the work isn't complete.
+
+The macOS implementation is build around [NSBackgroundActivityScheduler](https://developer.apple.com/documentation/foundation/nsbackgroundactivityscheduler), which works very differently internally.
+
 ### More Complex Usage
 
 This package is used to manage the background uploading facilities of [Wells](https://github.com/ChimeHQ/Wells), a diagnostics report submission system. You can check out that project for a much more complex example of how to manage background uploads.

Sources/Background/TaskScheduler.swift

@@ -3,13 +3,159 @@ import Foundation
 import BackgroundTasks
 #endif
 
-enum BackgroundTask {
+protocol BackgroundTaskRequest: Hashable {
+	var identifier: String { get }
+	var earliestBeginDate: Date? { get }
+}
+
+enum BackgroundTaskError: Error {
+	case unsupportedTaskRequest
+}
+
+#if os(iOS) || os(tvOS) || os(visionOS)
+struct BackgroundTask {
+	private let task: BGTask
+	
+	init(_ task: BGTask) {
+		self.task = task
+	}
+	
+	public var identifier: String { task.identifier }
+	
+	public var expirationHandler: (@Sendable () -> Void)? {
+		get {
+			unsafeBitCast(task.expirationHandler, to: (@Sendable () -> Void)?.self)
+		}
+		set { task.expirationHandler = newValue }
+	}
+	
+	public func setTaskCompleted(success: Bool) {
+		task.setTaskCompleted(success: success)
+	}
+}
+
+extension BackgroundTaskRequest {
+	var bgTaskRequest: BGTaskRequest {
+		get throws {
+			switch self {
+			case is AppRefreshTaskRequest:
+				let request = BGAppRefreshTaskRequest(identifier: identifier)
+				
+				request.earliestBeginDate = earliestBeginDate
+				
+				return request
+			case let processing as ProcessingTaskRequest:
+				let request = BGProcessingTaskRequest(identifier: identifier)
+				
+				request.earliestBeginDate = earliestBeginDate
+				request.requiresNetworkConnectivity = processing.requiresNetworkConnectivity
+				request.requiresExternalPower = processing.requiresExternalPower
+				
+				return request
+			default:
+				throw BackgroundTaskError.unsupportedTaskRequest
+			}
+		}
+	}
+}
+#else
+struct BackgroundTask {
+	public let identifier: String
+	public let expirationHandler: (@Sendable () -> Void)?
+	
+	public func setTaskCompleted(success: Bool) {
+	}
+}
+#endif
+
+struct AppRefreshTaskRequest: BackgroundTaskRequest {
+	public let identifier: String
+	public var earliestBeginDate: Date?
+	
+	init(identifier: String) {
+		self.identifier = identifier
+	}
+}
 
+struct ProcessingTaskRequest: BackgroundTaskRequest {
+	public let identifier: String
+	public var earliestBeginDate: Date?
+	public var requiresNetworkConnectivity: Bool = false
+	public var requiresExternalPower: Bool = false
+	
+	init(identifier: String) {
+		self.identifier = identifier
+	}
 }
 
+#if os(iOS) || os(tvOS) || os(visionOS)
 final class TaskScheduler: Sendable {
 	public static let shared = TaskScheduler()
 
 	private init() {
 	}
+	
+	public func submit(_ task: any BackgroundTaskRequest) throws {
+		let bgTaskRequest = try task.bgTaskRequest
+		
+		try BGTaskScheduler.shared.submit(bgTaskRequest)
+	}
+	
+	public func register(
+		forTaskWithIdentifier identifier: String,
+		using queue: dispatch_queue_t? = nil,
+		launchHandler: @escaping @Sendable (BackgroundTask) -> Void
+	) -> Bool {
+		BGTaskScheduler.shared.register(forTaskWithIdentifier: identifier, using: queue) { @Sendable bgTask in
+			let task = BackgroundTask(bgTask)
+			
+			launchHandler(task)
+		}
+	}
+}
+
+extension BGTaskScheduler {
+	public func register(
+		forTaskWithIdentifier identifier: String,
+		launchHandler: @escaping @Sendable (BGTask) -> Void
+	) -> Bool {
+		register(forTaskWithIdentifier: identifier, using: nil, launchHandler: launchHandler)
+	}
+}
+
+#else
+final class TaskScheduler: @unchecked Sendable {
+	public static let shared = TaskScheduler()
+	
+	private let scheduler = NSBackgroundActivityScheduler(identifier: "com.chimehq.Background")
+	private let lock = NSLock()
+	private var requests: [String: any BackgroundTaskRequest] = [:]
+	private var registrations: [String: HandlerRegistration] = [:]
+	
+	private struct HandlerRegistration: Sendable {
+		let handler: @Sendable (BackgroundTask) -> Void
+		let identifier: String
+		let queue: dispatch_queue_t?
+	}
+
+	private init() {
+	}
+	
+	public func submit<T: BackgroundTaskRequest>(_ task: T) throws {
+		requests[task.identifier] = task
+	}
+	
+	public func register(
+		forTaskWithIdentifier identifier: String,
+		using queue: dispatch_queue_t? = nil,
+		launchHandler: @escaping @Sendable (BackgroundTask) -> Void
+	) -> Bool {
+		let registration = HandlerRegistration(handler: launchHandler, identifier: identifier, queue: queue)
+		
+		registrations[identifier] = registration
+		
+		return true
+	}
 }
+
+#endif

Tests/BackgroundTests/BackgroundTests.swift

@@ -1,12 +1,16 @@
-import XCTest
+import Testing
 @testable import Background
 
-final class BackgroundTests: XCTestCase {
-    func testExample() throws {
-        // XCTest Documentation
-        // https://developer.apple.com/documentation/xctest
-
-        // Defining Test Cases and Test Methods
-        // https://developer.apple.com/documentation/xctest/defining_test_cases_and_test_methods
-    }
+struct BackgroundTests {
+	@Test func testExample() throws {
+		let request = ProcessingTaskRequest(identifier: "abc")
+		
+		let scheduler = TaskScheduler.shared
+		
+		_ = scheduler.register(forTaskWithIdentifier: "abc") { task in
+			
+		}
+		
+		try scheduler.submit(request)
+	}
 }