Add feature flag to keep Android timers running while the host is paused (#59371)

Summary:
Pull Request resolved: #59371

On Android, `JavaTimerManager` stops JS timers on `onHostPause` and only restarts them on `onHostResume` or while a headless JS task is active. When the app keeps using the JS runtime without a resumed React screen, pending `setTimeout`s and Promise-driven work that depends on them stall until a React screen resumes. On iOS, `RCTTiming` does not depend on host lifecycle: timers keep firing until the instance is invalidated.

Add `keepTimersRunningWhileHostPausedAndroid` (default `false`). When enabled, `JavaTimerManager`:
- starts the timer frame callback when it is created, since the host may never resume;
- stops timers only once the instance is destroyed (tracked by a new `isDestroyed`), instead of when the host is paused.

Independently of the flag, instance destroy now stops timers even while a headless JS task is still marked active. The instance's JS thread and runtime are gone by then, so such a task can no longer run JS; previously the timer frame callback kept re-posting itself every frame and retained the destroyed `JavaTimerManager`.

Changelog: [Internal]

Reviewed By: christophpurrer

Differential Revision: D126948111

fbshipit-source-id: ae4422c07ebdcf01498a6284686e44344207fa28

Author: zeyap

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlags.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<f8fad51e8b31224b04d7933da8affb3a>>
+ * @generated SignedSource<<f308cce94b6675fb99b66792ba49347a>>
  */
 
 /**
@@ -444,6 +444,12 @@ public object ReactNativeFeatureFlags {
   @JvmStatic
   public fun fuseboxWebSocketEventsEnabled(): Boolean = accessor.fuseboxWebSocketEventsEnabled()
 
+  /**
+   * Keep JS timers running on Android while the React host is paused, stopping them only when the React instance is destroyed. Matches iOS, where timers do not depend on host lifecycle.
+   */
+  @JvmStatic
+  public fun keepTimersRunningWhileHostPausedAndroid(): Boolean = accessor.keepTimersRunningWhileHostPausedAndroid()
+
   /**
    * When enabled, uses optimized platform-specific paths to apply animated props synchronously. On Android, this uses a batched int/double buffer protocol with a single JNI call. Other platforms apply the props of each view through the existing synchronous update.
    */

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsCxxAccessor.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<846a8685f662d66dbcdaa4324c772d51>>
+ * @generated SignedSource<<1cefe829b93cd661df195cbf3a3663a7>>
  */
 
 /**
@@ -89,6 +89,7 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
   private var fuseboxFrameRecordingEnabledCache: Boolean? = null
   private var fuseboxScreenshotCaptureEnabledCache: Boolean? = null
   private var fuseboxWebSocketEventsEnabledCache: Boolean? = null
+  private var keepTimersRunningWhileHostPausedAndroidCache: Boolean? = null
   private var optimizedAnimatedPropUpdatesCache: Boolean? = null
   private var overrideBySynchronousMountPropsAtMountingAndroidCache: Boolean? = null
   private var perfIssuesEnabledCache: Boolean? = null
@@ -739,6 +740,15 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
     return cached
   }
 
+  override fun keepTimersRunningWhileHostPausedAndroid(): Boolean {
+    var cached = keepTimersRunningWhileHostPausedAndroidCache
+    if (cached == null) {
+      cached = ReactNativeFeatureFlagsCxxInterop.keepTimersRunningWhileHostPausedAndroid()
+      keepTimersRunningWhileHostPausedAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun optimizedAnimatedPropUpdates(): Boolean {
     var cached = optimizedAnimatedPropUpdatesCache
     if (cached == null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsCxxInterop.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<9ccf3958e1db2db295ba73dc371b5185>>
+ * @generated SignedSource<<e984b654c4b8fc17f99046e60306f3f6>>
  */
 
 /**
@@ -166,6 +166,8 @@ public object ReactNativeFeatureFlagsCxxInterop {
 
   @DoNotStrip @JvmStatic public external fun fuseboxWebSocketEventsEnabled(): Boolean
 
+  @DoNotStrip @JvmStatic public external fun keepTimersRunningWhileHostPausedAndroid(): Boolean
+
   @DoNotStrip @JvmStatic public external fun optimizedAnimatedPropUpdates(): Boolean
 
   @DoNotStrip @JvmStatic public external fun overrideBySynchronousMountPropsAtMountingAndroid(): Boolean

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsDefaults.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<0a04c5e0a0b418f2efd4b253646ae7c1>>
+ * @generated SignedSource<<c0f98773f7b83272d69132d1a3e2f45a>>
  */
 
 /**
@@ -161,6 +161,8 @@ public open class ReactNativeFeatureFlagsDefaults : ReactNativeFeatureFlagsProvi
 
   override fun fuseboxWebSocketEventsEnabled(): Boolean = false
 
+  override fun keepTimersRunningWhileHostPausedAndroid(): Boolean = false
+
   override fun optimizedAnimatedPropUpdates(): Boolean = false
 
   override fun overrideBySynchronousMountPropsAtMountingAndroid(): Boolean = true

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsLocalAccessor.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<861063ef7d217992d3cecd410e25d885>>
+ * @generated SignedSource<<f18d16c52745abc62a0b9ccad5358a0b>>
  */
 
 /**
@@ -93,6 +93,7 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
   private var fuseboxFrameRecordingEnabledCache: Boolean? = null
   private var fuseboxScreenshotCaptureEnabledCache: Boolean? = null
   private var fuseboxWebSocketEventsEnabledCache: Boolean? = null
+  private var keepTimersRunningWhileHostPausedAndroidCache: Boolean? = null
   private var optimizedAnimatedPropUpdatesCache: Boolean? = null
   private var overrideBySynchronousMountPropsAtMountingAndroidCache: Boolean? = null
   private var perfIssuesEnabledCache: Boolean? = null
@@ -812,6 +813,16 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
     return cached
   }
 
+  override fun keepTimersRunningWhileHostPausedAndroid(): Boolean {
+    var cached = keepTimersRunningWhileHostPausedAndroidCache
+    if (cached == null) {
+      cached = currentProvider.keepTimersRunningWhileHostPausedAndroid()
+      accessedFeatureFlags.add("keepTimersRunningWhileHostPausedAndroid")
+      keepTimersRunningWhileHostPausedAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun optimizedAnimatedPropUpdates(): Boolean {
     var cached = optimizedAnimatedPropUpdatesCache
     if (cached == null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsProvider.kt

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<5fa21c808df68be4c007469040fbca2a>>
+ * @generated SignedSource<<0a088b4c798dd44274c63a4aa6cba312>>
  */
 
 /**
@@ -161,6 +161,8 @@ public interface ReactNativeFeatureFlagsProvider {
 
   @DoNotStrip public fun fuseboxWebSocketEventsEnabled(): Boolean
 
+  @DoNotStrip public fun keepTimersRunningWhileHostPausedAndroid(): Boolean
+
   @DoNotStrip public fun optimizedAnimatedPropUpdates(): Boolean
 
   @DoNotStrip public fun overrideBySynchronousMountPropsAtMountingAndroid(): Boolean

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/core/JavaTimerManager.kt

@@ -20,6 +20,7 @@ import com.facebook.react.common.SystemClock.nanoTime
 import com.facebook.react.common.SystemClock.uptimeMillis
 import com.facebook.react.common.annotations.internal.LegacyArchitecture
 import com.facebook.react.devsupport.interfaces.DevSupportManager
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags
 import com.facebook.react.jstasks.HeadlessJsTaskContext
 import com.facebook.react.jstasks.HeadlessJsTaskEventListener
 import java.util.PriorityQueue
@@ -50,6 +51,7 @@ public open class JavaTimerManager(
   private val idleCallbackGuard = Any()
   private val timerIdsToTimers: SparseArray<Timer> = SparseArray()
   private val isPaused = AtomicBoolean(true)
+  private val isDestroyed = AtomicBoolean(false)
   private val isRunningTasks = AtomicBoolean(false)
   private val timerFrameCallback = TimerFrameCallback()
   private val idleFrameCallback = IdleFrameCallback()
@@ -65,6 +67,15 @@ public open class JavaTimerManager(
   init {
     reactApplicationContext.addLifecycleEventListener(this)
     HeadlessJsTaskContext.getInstance(reactApplicationContext).addTaskEventListener(this)
+    if (ReactNativeFeatureFlags.keepTimersRunningWhileHostPausedAndroid()) {
+      // The host may never resume (e.g. no React screen is shown), so start timers here.
+      UiThreadUtil.runOnUiThread {
+        if (!isDestroyed.get()) {
+          setChoreographerCallback()
+          maybeSetChoreographerIdleCallback()
+        }
+      }
+    }
   }
 
   override fun onHostPause() {
@@ -105,10 +116,21 @@ public open class JavaTimerManager(
   public open fun onInstanceDestroy() {
     HeadlessJsTaskContext.getInstance(reactApplicationContext).removeTaskEventListener(this)
     reactApplicationContext.removeLifecycleEventListener(this)
+    isDestroyed.set(true)
     clearFrameCallback()
     clearChoreographerIdleCallback()
   }
 
+  // Timers always stop once the instance is destroyed: its JS thread and runtime are gone, so
+  // headless tasks left active on its context can no longer run JS. With the flag, timers
+  // otherwise follow the instance lifetime like iOS, so JS work keeps progressing while no React
+  // screen is resumed.
+  private fun isStopped(): Boolean =
+      isDestroyed.get() ||
+          (!ReactNativeFeatureFlags.keepTimersRunningWhileHostPausedAndroid() &&
+              isPaused.get() &&
+              !isRunningTasks.get())
+
   @LegacyArchitecture
   private fun maybeSetChoreographerIdleCallback() {
     synchronized(idleCallbackGuard) {
@@ -120,7 +142,7 @@ public open class JavaTimerManager(
 
   @LegacyArchitecture
   private fun maybeIdleCallback() {
-    if (isPaused.get() && !isRunningTasks.get()) {
+    if (isStopped()) {
       clearFrameCallback()
     }
   }
@@ -136,8 +158,7 @@ public open class JavaTimerManager(
   }
 
   private fun clearFrameCallback() {
-    val headlessJsTaskContext = HeadlessJsTaskContext.getInstance(reactApplicationContext)
-    if (frameCallbackPosted && isPaused.get() && !headlessJsTaskContext.hasActiveTasks()) {
+    if (frameCallbackPosted && isStopped()) {
       reactChoreographer.removeFrameCallback(
           ReactChoreographer.CallbackType.TIMERS_EVENTS,
           timerFrameCallback,
@@ -286,7 +307,7 @@ public open class JavaTimerManager(
 
     /** Calls all timers that have expired since the last time this frame callback was called. */
     override fun doFrame(frameTimeNanos: Long) {
-      if (isPaused.get() && !isRunningTasks.get()) {
+      if (isStopped()) {
         return
       }
       val frameTimeMillis = frameTimeNanos / 1000000
@@ -318,7 +339,7 @@ public open class JavaTimerManager(
 
   private inner class IdleFrameCallback : Choreographer.FrameCallback {
     override fun doFrame(frameTimeNanos: Long) {
-      if (isPaused.get() && !isRunningTasks.get()) {
+      if (isStopped()) {
         return
       }
 

packages/react-native/ReactAndroid/src/main/jni/react/featureflags/JReactNativeFeatureFlagsCxxInterop.cpp

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<7e430d5b575ea983d53ecde87c4dc9f0>>
+ * @generated SignedSource<<19e1daeb6cb72249eb279268fc7122e5>>
  */
 
 /**
@@ -453,6 +453,12 @@ class ReactNativeFeatureFlagsJavaProvider
     return method(javaProvider_);
   }
 
+  bool keepTimersRunningWhileHostPausedAndroid() override {
+    static const auto method =
+        getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("keepTimersRunningWhileHostPausedAndroid");
+    return method(javaProvider_);
+  }
+
   bool optimizedAnimatedPropUpdates() override {
     static const auto method =
         getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("optimizedAnimatedPropUpdates");
@@ -970,6 +976,11 @@ bool JReactNativeFeatureFlagsCxxInterop::fuseboxWebSocketEventsEnabled(
   return ReactNativeFeatureFlags::fuseboxWebSocketEventsEnabled();
 }
 
+bool JReactNativeFeatureFlagsCxxInterop::keepTimersRunningWhileHostPausedAndroid(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
+  return ReactNativeFeatureFlags::keepTimersRunningWhileHostPausedAndroid();
+}
+
 bool JReactNativeFeatureFlagsCxxInterop::optimizedAnimatedPropUpdates(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
   return ReactNativeFeatureFlags::optimizedAnimatedPropUpdates();
@@ -1348,6 +1359,9 @@ void JReactNativeFeatureFlagsCxxInterop::registerNatives() {
       makeNativeMethod(
         "fuseboxWebSocketEventsEnabled",
         JReactNativeFeatureFlagsCxxInterop::fuseboxWebSocketEventsEnabled),
+      makeNativeMethod(
+        "keepTimersRunningWhileHostPausedAndroid",
+        JReactNativeFeatureFlagsCxxInterop::keepTimersRunningWhileHostPausedAndroid),
       makeNativeMethod(
         "optimizedAnimatedPropUpdates",
         JReactNativeFeatureFlagsCxxInterop::optimizedAnimatedPropUpdates),

packages/react-native/ReactAndroid/src/main/jni/react/featureflags/JReactNativeFeatureFlagsCxxInterop.h

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<6b96c286c25d3c9fcb66d39d67092787>>
+ * @generated SignedSource<<d3d1a8ea9d6f94f1e069a3f43a79bd68>>
  */
 
 /**
@@ -237,6 +237,9 @@ class JReactNativeFeatureFlagsCxxInterop
   static bool fuseboxWebSocketEventsEnabled(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
 
+  static bool keepTimersRunningWhileHostPausedAndroid(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
+
   static bool optimizedAnimatedPropUpdates(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);