iOS master dispatcher architecture concerns

[peterzapalac]

Hi, I have a question/concern about the iOS dynamic task / master dispatcher architecture.

I understand why the master dispatcher exists: iOS requires task identifiers to be declared in Info.plist, so KMP WorkManager queues arbitrary dynamic task IDs internally and uses kmp_master_dispatcher_task to execute them.

However, it seems that this has an important consequence on iOS:

1. A task configured with isHeavyTask = false would normally be scheduled as a BGAppRefreshTaskRequest.
2. If the task uses a dynamic ID, it is instead placed in the internal queue.
3. The master dispatcher is then always scheduled as a BGProcessingTaskRequest, regardless of the characteristics of the queued tasks.
4. The master dispatcher also always uses requiresNetworkConnectivity = false.
5. Therefore, even if all pending tasks are lightweight and require network, iOS still wakes the app through an unconstrained BGProcessingTask.

This means a lightweight network task can consume a BGProcessingTask execution window while offline, fail its network requirement at the worker level, and then be rescheduled again. Since BGProcessingTask is intended for heavier/background processing and its execution is entirely controlled by iOS, I'm concerned that this architecture could result in less favorable scheduling than simply using BGAppRefreshTask for lightweight work.

I understand that BGAppRefreshTaskRequest itself has no requiresNetworkConnectivity property, so I'm not expecting that constraint to be represented at the Apple request level. My concern is specifically about the master dispatcher always becoming a BGProcessingTask and always being unconstrained, even when all queued work is lightweight and/or network-dependent.

Is this behavior intentional and considered the recommended iOS architecture?

If so, is the recommendation actually to use dedicated task IDs declared in BGTaskSchedulerPermittedIdentifiers for lightweight tasks, so that they can be scheduled directly as BGAppRefreshTaskRequests?

Alternatively, would it make sense for the master dispatcher to derive aggregate constraints from the pending queue — for example, requiring network when all pending tasks require network — and potentially use BGAppRefreshTask when all pending tasks are lightweight?

I'm mainly trying to understand whether this is an intentional trade-off of the dynamic-task architecture, a limitation that should be documented, or potentially an implementation issue.

[vietnguyentuan2019]

Thanks for the detailed write-up — you've read the code correctly, and this is a real trade-off worth explaining explicitly (it isn't documented today, which is on us).

What's happening today, confirmed in code:

• NativeTaskScheduler.createBackgroundTaskRequest() branches on Constraints.isHeavyTask — but only for static task IDs (ones declared in Info.plist). A static light task correctly becomes a BGAppRefreshTaskRequest.
• Any dynamic task ID (not in Info.plist) is queued and always wakes the app via kmp_master_dispatcher_task, submitted as BGProcessingTaskRequest with requiresNetworkConnectivity = false, regardless of what's actually pending.
• That false is intentional (see the comment in DynamicTaskDispatcher.rescheduleMasterDispatcher): it lets non-network tasks in a mixed queue run opportunistically even without connectivity, rather than blocking the whole batch on one task's network requirement. Each worker still checks its own requiresNetwork at execution time and fails/retries if unmet.
• What we didn't account for is your scenario: a queue that is entirely light + network-dependent still burns a BGProcessingTask slot unconstrained, which is a worse trade than BGAppRefreshTask would give it.

Answering your two questions directly:

1. Yes — using dedicated static IDs (declared in BGTaskSchedulerPermittedIdentifiers) for lightweight/network-bound work is the recommended workaround today. It routes through createBackgroundTaskRequest()'s isHeavyTask branch and gets a proper BGAppRefreshTaskRequest. We'll call this out explicitly in the iOS docs.

2. Aggregate constraint derivation is a legitimate idea and technically feasible, but not a small change: per-task requiresNetwork/isHeavyTask is already persisted in task metadata, but the dynamic-task queue (AppendOnlyQueue) is intentionally append-only/streaming with no non-destructive peek — it only supports enqueueTask/dequeueTask/getTasksQueueSize. Deriving "are all pending tasks light + network-required" cheaply would need incremental O(1) counters maintained alongside enqueue/dequeue, not a queue scan. That's a real architecture change, so we're tracking it as a separate enhancement rather than treating it as a quick fix — see the linked issue.

So: not a bug, but a genuine documentation gap plus a worthwhile enhancement. Filed the enhancement as #79; will also update docs/IOS_BGTASK_LIMITS.md / docs/ios-dynamic-task-scheduling.md to spell out this trade-off and the static-ID workaround. Thanks for pushing on this.

[vietnguyentuan2019]

Follow-up / correction on my reply above, after actually implementing this:

1. I was wrong about the queue. I said AppendOnlyQueue "only supports enqueueTask/dequeueTask/getTasksQueueSize" with no non-destructive peek, and that aggregating per-task constraints would need incremental counters. That's incorrect — AppendOnlyQueue.getAllItems() already exists and is non-destructive (it's what the chain queue's getActiveChainIds() uses). So the aggregation fix landed as a straightforward O(N) scan over getAllItems() + per-task metadata, not counters. Correcting the record since it's on the record in this thread.

2. The fix that shipped is narrower than my first draft, and specifically does not switch the dispatcher to BGAppRefreshTaskRequest for an all-light queue — the part of your question I answered "yes, technically feasible" to. On closer look it isn't safe with the current batch executor:

• BGAppRefreshTask has a hard ~30s ceiling with no extension API.
• A single dequeued task in the batch executor can run up to SingleTaskExecutor.DEFAULT_TIMEOUT_MS = 25s before its own per-task timeout fires.
• 25s of worker execution plus wake latency and completion overhead leaves no safe margin under a 30s hard ceiling — not for a whole batch, not even for one task. The static-ID case works today because a static light task is one task, one App Refresh window by construction; the dynamic-task master dispatcher is a batch processor sized for BGProcessingTask's multi-minute budget, so "every pending task is light" doesn't imply "the batch fits in 30 seconds."

What did ship: requiresNetworkConnectivity on the master dispatcher is now derived from the pending queue — true only when every pending dynamic task requires network, so an all-network queue no longer wakes opportunistically offline just to fail every task and re-queue it. That's the fix in the linked PR.

The BGAppRefreshTaskRequest-for-all-light-queues idea is still tracked in #79 as a real follow-up, but it needs the dispatcher to know it's running under an App Refresh budget (cap itself to ≤1 task, much smaller per-task timeout) and real-device verification — the Simulator doesn't model actual BGTaskScheduler timing. Static IDs remain the recommended path for lightweight, latency-sensitive work in the meantime.

Full writeup: docs/ios-dynamic-task-scheduling.md § 5.