fix: offload every main-thread onFocus / onUnfocused handler behind sdk_background_threading FF

[abdulraqeeb33]

One Line Summary

Wrap every main-thread IApplicationLifecycleHandler.onFocus / onUnfocused that does slow / blocking work with runOnSerialIOIfBackgroundThreading (introduced in #2643). Five handlers, one rollout knob, one ordering guarantee.

Linear: SDK-4506
Project: Android: refactor loading during initialization
Base branch: ar/sdk-4505 (#2643 — adds the helper + serial dispatcher)

Motivation

Activity.onStart → ApplicationService.onActivityStarted → handleFocus → applicationLifecycleNotifier.fire { onFocus(...) } synchronously invokes every IApplicationLifecycleHandler on the main thread:

User action (background -> foreground)
  -> Activity.onStart                                  [main thread]
  -> Application.dispatchActivityStarted               [main thread]
  -> ApplicationService.onActivityStarted              [main thread]
  -> ApplicationService.handleFocus                    [main thread]
  -> applicationLifecycleNotifier.fire { onFocus(...) }[main thread]
  -> <every IApplicationLifecycleHandler.onFocus>      [main thread - WORK HAPPENS HERE]

Five lifecycle handlers do slow / blocking work on that main-thread fanout. ANR-dump analysis of logs/2026-05-12 (500 ANR entries, all on sdk_background_threading) plus two prior OTel samples attribute ~94 / 500 (~18.8 %) of main-thread ANRs to them.

Handler	What it does on main	ANR signature	Observed
BackgroundManager.onFocus / onUnfocused	JobScheduler.cancel / .schedule (synchronous Binder to system_server)	JobSchedulerImpl.cancel	OTel ycae33cjpu6gcyut — 20,796 ms on Xiaomi 25078RA3EL / Android 15
NotificationsManager.onFocus	NotificationRestoreWorkManager.beginEnqueueingWork → WorkManager SQLite init + enqueueUniqueWork	SQLiteConnection.nativeExecuteForLong	OTel 9qy5s0ta0cwqwmb0 — 30,516 ms on vivo I2306 / Android 15
NotificationPermissionController polling listener (onFocus / onUnfocused)	reads ConfigModel, calls pollingWaiter.wake() → IO pool dispatch	dispatcher / executor lazy chain	26 / 500 in logs/2026-05-12
FeatureFlagsRefreshService.onFocus / onUnfocused	restartForegroundPolling → OneSignalDispatchers.launchOnIO	dispatcher / executor lazy chain	18 / 500 in logs/2026-05-12
SessionService.onFocus / onUnfocused	sessionLifeCycleNotifier.fire { onSessionStarted / onSessionActive } — runs every subscribed handler synchronously (operation repo, IAM trigger eval, etc.)	dispatcher / executor lazy chain	25 / 500 in logs/2026-05-12

The three dispatcher-cold-start handlers (NPC + FFRS + SessionService) all bottom out in the OneSignalDispatchers lazy chain — the deeper structural fix for that is #2645 (prewarm). This PR is the safer first cut: keep all five handlers on one FF-gated knob so the rollout matrix stays simple.

Fix

Single shared helper from #2643:

fun runOnSerialIOIfBackgroundThreading(block: () -> Unit) {
    if (ThreadingMode.useBackgroundThreading) {
        suspendifyOnSerialIO { block() }
    } else {
        block()
    }
}

Applied uniformly at every call site:

// BackgroundManager
override fun onFocus(firedOnSubscribe: Boolean) {
    runOnSerialIOIfBackgroundThreading { cancelSyncTask() }
}
override fun onUnfocused() {
    runOnSerialIOIfBackgroundThreading { scheduleBackground() }
}

// NotificationsManager
override fun onFocus(firedOnSubscribe: Boolean) {
    runOnSerialIOIfBackgroundThreading { refreshNotificationState() }
}

// NotificationPermissionController polling lifecycle listener
override fun onFocus(firedOnSubscribe: Boolean) {
    super.onFocus(firedOnSubscribe)
    runOnSerialIOIfBackgroundThreading {
        pollingWaitInterval = _configModelStore.model.foregroundFetchNotificationPermissionInterval
        pollingWaiter.wake()
    }
}
override fun onUnfocused() {
    super.onUnfocused()
    runOnSerialIOIfBackgroundThreading {
        pollingWaitInterval = _configModelStore.model.backgroundFetchNotificationPermissionInterval
    }
}

// FeatureFlagsRefreshService
override fun onFocus(firedOnSubscribe: Boolean) {
    runOnSerialIOIfBackgroundThreading { restartForegroundPolling() }
}
override fun onUnfocused() {
    runOnSerialIOIfBackgroundThreading {
        synchronized(this@FeatureFlagsRefreshService) {
            pollJob?.cancel(); pollJob = null; pollingAppId = null
        }
    }
}

// SessionService — timestamps captured on the main thread BEFORE the wrapper
override fun onFocus(firedOnSubscribe: Boolean) {
    val focusTimeMs = _time.currentTimeMillis
    runOnSerialIOIfBackgroundThreading { handleOnFocus(firedOnSubscribe, focusTimeMs) }
}
override fun onUnfocused() {
    val unfocusTimeMs = _time.currentTimeMillis
    runOnSerialIOIfBackgroundThreading { handleOnUnfocused(unfocusTimeMs) }
}

Notable per-handler details:

• FeatureFlagsRefreshService.onUnfocused qualifies this as this@FeatureFlagsRefreshService so the lambda locks on the service instance — the same monitor restartForegroundPolling takes — rather than on the no-receiver lambda object.
• SessionService captures _time.currentTimeMillis on the caller's thread BEFORE the wrapper, so session.startTime / session.focusTime / activeDuration reflect when Android delivered the event, not whenever the serial dispatcher ran the block.
• NotificationPermissionController.onUnfocused is intentionally NOT a no-op — it pushes the polling interval to 1 day to effectively pause polling. With the wrapper, FF=ON moves that single-field assignment onto SerialIO and FF=OFF keeps it inline.

Gated rollout

Cohort	onFocus / onUnfocused path	Behavior
FF on	runOnSerialIOIfBackgroundThreading { ... } → OneSignalDispatchers.SerialIO (single-thread executor)	ANR-fixed
FF off	inline on the lifecycle main thread	Legacy behavior — retains the ANRs for the control cohort

Activation is APP_STARTUP per FeatureFlag.kt, so a given session is latched on one path and won't bounce mid-run. Worth flagging that the production ANR samples for every handler in this PR were on FF=ON — because all five previously bypassed every threading helper, the FF did not gate any of these codepaths. This PR is what introduces the gate.

Why the serial dispatcher (not suspendifyOnIO)

All five handlers are invoked from the same main-thread fanout (ApplicationService.handleFocus → applicationLifecycleNotifier.fire). A rapid focus burst on a multi-thread IO pool could interleave them with each other and with the BackgroundManager.cancel / schedule pair. Pinning all five to the same single-thread executor keeps lifecycle work globally ordered on the main-thread submission order, and future per-event work added to any of these handlers inherits the ordering guarantee for free.

Scope

• BackgroundManager: synchronous JobScheduler.cancel / schedule no longer on main when sdk_background_threading is on.
• NotificationsManager.onFocus: WorkManager SQLite init + enqueue no longer on main.
• NotificationPermissionController polling listener: onFocus + onUnfocused move to SerialIO.
• FeatureFlagsRefreshService: onFocus + onUnfocused move to SerialIO (lock qualified).
• SessionService: onFocus + onUnfocused move to SerialIO with timing capture preserved.
• Unchanged: refreshNotificationState, NotificationRestoreWorkManager.beginEnqueueingWork (still synchronized + idempotent on restored), NotificationHelper.areNotificationsEnabled, setPermissionStatusAndFire, the body of restartForegroundPolling, and handleOnFocus / handleOnUnfocused's session-state mutation semantics.
• NotificationsManager.onUnfocused is empty in production; not touched.
• Deeper prewarm fix for the dispatcher / executor lazy chain itself lands in fix: warm OneSignalDispatchers on init to avoid cold-start ANRs #2645.

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• Outcomes
• Sessions
• In-App Messaging
• REST API requests
• Public API changes

Testing

Static

• :OneSignal:core:detekt, :OneSignal:notifications:detekt — clean.
• :OneSignal:core:compileReleaseKotlin, :OneSignal:notifications:compileReleaseKotlin, :OneSignal:testhelpers:compileReleaseKotlin — clean.

Automated

• :OneSignal:core:testReleaseUnitTest — full suite green, including:
  • BackgroundManagerTests — FF=on dispatch via launchOnSerialIO in submission order on both cancel and schedule, FF=off inline, rapid unfocus -> focus burst routes through the serial dispatcher in submission order.
  • FeatureFlagsRefreshServiceTests — onFocus / onUnfocused route through runOnSerialIOIfBackgroundThreading.
  • SessionServiceTests — existing state-mutation assertions still pass under the FF-off default; new assertions for the dispatch contract on onFocus + onUnfocused + the rapid unfocus -> focus burst.
• :OneSignal:notifications:testReleaseUnitTest — full suite green, including:
  • NotificationsManagerTests — dispatch contract + rapid-burst ordering, lambda body observable so JaCoCo sees the refreshNotificationState call covered.
  • NotificationPermissionControllerTests — onFocus + onUnfocused polling lifecycle listener dispatch contract. Existing polling integration tests still pass under the FF-off default since the wrapper inlines.

Manual

Will follow up with manual repro on a vivo device under simulated SQLite contention conditions.

Checklist

Overview

• I have filled out all REQUIRED sections above
• PR does one thing (apply a single FF-gated helper at every order-sensitive lifecycle handler call site)
• No public API changes

Testing

• Test coverage on the dispatch contracts for all five handlers
• Existing automated tests still pass for the touched modules
• Manual repro on a vivo device pending

Final pass

• Code is as readable as possible
• I have reviewed this PR myself

[github-actions]

📊 Diff Coverage Report

Diff Coverage Report (Changed Lines Only)

Gate: aggregate coverage on changed executable lines must be ≥ 80% (JaCoCo line data for lines touched in the diff).

Changed Files Coverage

• BackgroundManager.kt: 2/2 touched executable lines (100.0%) (6 touched lines in diff)
• FeatureFlagsRefreshService.kt: 7/7 touched executable lines (100.0%) (13 touched lines in diff)
• SessionService.kt: 13/13 touched executable lines (100.0%) (24 touched lines in diff)
• NotificationsManager.kt: 0/1 touched executable lines (0.0%) (5 touched lines in diff)
  • 1 uncovered touched lines in this file
• NotificationPermissionController.kt: 0/7 touched executable lines (0.0%) (12 touched lines in diff)
  • 7 uncovered touched lines in this file

Overall (aggregate gate)

22/30 touched executable lines covered (73.3% — requires ≥ 80%)

Per-file detail (informational; gate is aggregate above):

• NotificationsManager.kt: 0.0% (1 uncovered touched lines)

• NotificationPermissionController.kt: 0.0% (7 uncovered touched lines)

❌ Coverage Check Failed

Aggregate coverage on touched lines is 73.3% (minimum 80%).

📥 View workflow run