Clarification on BGTaskScheduler.submitTaskRequest(_:completionHandler:) main-thread warning

I’m looking at the new BGTaskScheduler.submitTaskRequest(_:completionHandler:) API on iOS 27 that replaces the now deprecated submit(_:).*

The documentation says:

This method asynchronously submits the task request and invokes the completion handler with any errors that occur during submission.

It also says:

The completion handler may be invoked on a arbitrary queue after an arbitrary amount of delay. Do not call this method from the main thread or performance-critical contexts.

I’m confused when it says “Do not call this method from the main thread.” Since the method asynchronously submits the request and reports errors later through the completion handler, I initially read this as a warning not to wait for the completion handler to be called assuming it returns quickly. But it specifically says not to call the method from the main thread, which suggests the initial call itself may perform blocking expensive work before returning (although this is confusingly stated in the same block describing the completion handler behavior).

Is the intended usage to create/configure the request on the main thread, then dispatch only submitTaskRequest to a background queue, or is calling that on the main thread actually okay just like the submit(_:) API it replaced?

My current code in a synchronous function running on the main thread:

BGTaskScheduler.shared.register(forTaskWithIdentifier: id, using: .main) { @Sendable registeredTask in
    // The background continued processing task has started, use it to update progress...
}

let request = BGContinuedProcessingTaskRequest(identifier: id, title: title, subtitle: subtitle)
request.strategy = .fail // Start the task immediately and fail if it cannot
if BGTaskScheduler.supportedResources.contains(.gpu) {
    request.requiredResources = .gpu
}

do {
    try BGTaskScheduler.shared.submit(request) // FIXME: How to migrate to the new API?
} catch {
    // No worries, user will just have to keep the app open until the task completes
    print("BGTaskScheduler request failed: \(error.localizedDescription)")
}

*I assume this change was made to address issues like FB21052216 (https://developer.apple.com/forums/thread/807370)

Answered by DTS Engineer in 900500022
I’m not sure what that comment you referenced means.

At this point I’m pretty sure that that part of the doc comment is just wrong. Please file a bug against the header, and reply back here with the bug number so that I can pass it on to the team.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

I assume this change was made to address issues like FB21052216

I think that’s a reasonable assumption.

The new API is definitely intended to support being called from any thread, including the main thread. I’m not sure what that comment you referenced means. I’ll research this and get back to you.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

I’m not sure what that comment you referenced means.

At this point I’m pretty sure that that part of the doc comment is just wrong. Please file a bug against the header, and reply back here with the bug number so that I can pass it on to the team.

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Thanks Quinn! FB24179736

Clarification on BGTaskScheduler.submitTaskRequest(_:completionHandler:) main-thread warning
 
 
Q