Android: stop re-arming the idle DISPATCH_UI Choreographer frame callback (behind feature flag) (#58378)

Summary:
# Stop re-arming the idle `DISPATCH_UI` Choreographer frame callback (Android)

Part of #58367. Split from #58368 per review feedback (one PR per pump, each behind a feature flag).

`FabricUIManager.DispatchUIFrameCallback.doFrameGuarded` re-schedules itself unconditionally in its `finally` block, so the `DISPATCH_UI` Choreographer callback runs at vsync rate forever — including while no mount items, pre-mount items or view commands are pending.

This PR makes the re-schedule demand-gated, behind `ReactNativeFeatureFlags.disableIdleMountItemFrameCallbackRearmAndroid` (default **false** = current behavior; `ossReleaseStage: 'experimental'`):

- `doFrameGuarded` only re-schedules while `mMountItemDispatcher.hasPendingItems()`.
- Items queued while the callback is idle re-arm it through `DispatchUIFrameCallback.schedule()`. The scheduler accepts calls from any thread, runs inline on the UI thread, coalesces off-thread handoffs, and skips work while paused or already armed.
- C++ animation sessions re-arm the callback for their first tick and keep it armed while animation work remains.

## Foregrounding / backgrounding

`onHostResume` → `resume()` re-schedules, while `onHostPause` → `pause()` disables scheduling. Items queued while paused are dispatched after resume. Items arriving on the UI thread during a commit keep the existing inline dispatch path; items added during a dispatch leave `hasPendingItems()` true, so the `finally` re-arms.

## Rollout

Flag: `disableIdleMountItemFrameCallbackRearmAndroid` — `defaultValue: false`, `expectedReleaseValue: true`, `ossReleaseStage: 'experimental'`. With the flag off, behavior is identical to current `main`.

Pull Request resolved: #58378

Test Plan:
- [x] `arc lint -a`
- [x] `buck2 build fbsource//xplat/js/react-native-github/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric:fabricAndroid` — `BUILD SUCCEEDED`
- [x] `buck2 test fbsource//xplat/js/react-native-github/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/fabric:fabricAndroid` — Pass 57, Fail 0 ([test run](https://www.internalfb.com/intern/testinfra/testrun/24769797998629457))
- [x] Flag off (`defaultValue`): both new paths are inert.
- [x] Compiles for the open-source Gradle build: `./gradlew :packages:react-native:ReactAndroid:compileReleaseKotlin :packages:react-native:ReactAndroid:compileReleaseJavaWithJavac`.
- [ ] Flag on, real app on device (OnePlus 3T, Android 9): idle `adb shell atrace` shows `DISPATCH_UI` doFrames drop to ~0 with a static UI; any render re-arms and commits land the same frame or the next; `dispatchCommand` from JS still executes promptly at idle; background/foreground round-trips keep the UI responsive.
- [ ] Flag on: RNTester rendering integration tests pass.

Reviewed By: cortinico

Differential Revision: D119071289

Pulled By: javache

fbshipit-source-id: 9e53cb6cde340e7fd501c359ed514dc4796bc308

Author: capt-muji

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java

@@ -107,6 +107,7 @@
 import java.util.Set;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * We instruct ProGuard not to strip out any fields or methods, because many of these methods are
@@ -212,7 +213,7 @@ public class FabricUIManager
    */
   private volatile boolean mDestroyed = false;
 
-  private boolean mDriveCxxAnimations = false;
+  private volatile boolean mDriveCxxAnimations = false;
 
   private @Nullable ViewTransitionSnapshotManager mViewTransitionSnapshotManager;
 
@@ -1463,6 +1464,11 @@ public String resolveCustomDirectEventName(@Nullable String eventName) {
   @AnyThread
   public void onAnimationStarted() {
     mDriveCxxAnimations = true;
+    if (ReactNativeFeatureFlags.disableIdleMountItemFrameCallbackRearmAndroid()) {
+      // A C++ animation session may begin while the DISPATCH_UI frame callback is disarmed at
+      // idle and no mount items are pending yet; re-arm it for the first tick.
+      mDispatchUIFrameCallback.schedule();
+    }
   }
 
   // Called from Binding.cpp
@@ -1548,6 +1554,12 @@ public void didDispatchMountItems() {
         listener.didDispatchMountItems(FabricUIManager.this);
       }
     }
+
+    @Override
+    public void onItemsQueued() {
+      // Items may be queued from any thread while the DISPATCH_UI frame callback is idle.
+      mDispatchUIFrameCallback.schedule();
+    }
   }
 
   /**
@@ -1574,24 +1586,38 @@ private class DispatchUIFrameCallback extends GuardedFrameCallback {
 
     private volatile boolean mIsMountingEnabled = true;
 
-    @ThreadConfined(UI)
-    private boolean mShouldSchedule = false;
+    private volatile boolean mShouldSchedule = false;
 
-    @ThreadConfined(UI)
-    private boolean mIsScheduled = false;
+    private final AtomicBoolean mScheduleTaskPending = new AtomicBoolean(false);
+    private volatile boolean mIsScheduled = false;
 
     private DispatchUIFrameCallback(ReactContext reactContext) {
       super(reactContext);
     }
 
-    @UiThread
-    @ThreadConfined(UI)
-    private void schedule() {
-      if (!mIsScheduled && mShouldSchedule) {
-        mIsScheduled = true;
-        ReactChoreographer.getInstance()
-            .postFrameCallback(ReactChoreographer.CallbackType.DISPATCH_UI, this);
+    @AnyThread
+    void schedule() {
+      if (mIsScheduled || !mShouldSchedule) {
+        return;
       }
+
+      if (!UiThreadUtil.isOnUiThread()) {
+        if (mScheduleTaskPending.compareAndSet(false, true)) {
+          UiThreadUtil.runOnUiThread(
+              () -> {
+                try {
+                  schedule();
+                } finally {
+                  mScheduleTaskPending.set(false);
+                }
+              });
+        }
+        return;
+      }
+
+      mIsScheduled = true;
+      ReactChoreographer.getInstance()
+          .postFrameCallback(ReactChoreographer.CallbackType.DISPATCH_UI, this);
     }
 
     @UiThread
@@ -1639,9 +1665,6 @@ public void doFrameGuarded(long frameTimeNanos) {
       }
 
       // Drive any animations from C++.
-      // There is a race condition here between getting/setting
-      // `mDriveCxxAnimations` which shouldn't matter; it's safe to call
-      // the mBinding method, unless mBinding has gone away.
       if ((mDriveCxxAnimations || ReactNativeFeatureFlags.cxxNativeAnimatedEnabled())
           && mBinding != null) {
         mBinding.driveCxxAnimations();
@@ -1664,7 +1687,19 @@ public void doFrameGuarded(long frameTimeNanos) {
         mIsMountingEnabled = false;
         throw ex;
       } finally {
-        schedule();
+        // Keep the Choreographer armed while items remain pending or a C++ animation driver
+        // needs per-frame ticks from this callback (driveCxxAnimations and
+        // driveAnimationBackend run here). Queueing new items re-arms it via
+        // MountItemDispatcher.onItemsQueued, and onAnimationStarted re-arms it when the C++
+        // side begins an animation session. The two flags below drive animations from this
+        // callback unconditionally, so they disable the idle optimization entirely.
+        if (!ReactNativeFeatureFlags.disableIdleMountItemFrameCallbackRearmAndroid()
+            || mMountItemDispatcher.hasPendingItems()
+            || mDriveCxxAnimations
+            || ReactNativeFeatureFlags.cxxNativeAnimatedEnabled()
+            || ReactNativeFeatureFlags.useSharedAnimatedBackend()) {
+          schedule();
+        }
       }
 
       if (ReactNativeFeatureFlags.useSharedAnimatedBackend() && mBinding != null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/mounting/MountItemDispatcher.kt

@@ -34,6 +34,18 @@ internal class MountItemDispatcher(
   private val mountItems: Queue<MountItem> = ConcurrentLinkedQueue()
   private val preMountItems: Queue<MountItem> = ConcurrentLinkedQueue()
 
+  /** @return true if any mount items, pre-mount items or view commands are still pending */
+  fun hasPendingItems(): Boolean =
+      !viewCommandMountItems.isEmpty() || !mountItems.isEmpty() || !preMountItems.isEmpty()
+
+  // Items can be queued from any thread while the DISPATCH_UI frame callback is disarmed at
+  // idle (see FabricUIManager's doFrameGuarded); the listener re-arms it.
+  private fun notifyItemsQueued() {
+    if (ReactNativeFeatureFlags.disableIdleMountItemFrameCallbackRearmAndroid()) {
+      itemDispatchListener.onItemsQueued()
+    }
+  }
+
   private var inDispatch: Boolean = false
   var batchedExecutionTime: Long = 0L
     private set
@@ -49,19 +61,22 @@ internal class MountItemDispatcher(
     } else {
       mountItems.add(mountItem)
     }
+    notifyItemsQueued()
   }
 
   fun addMountItem(mountItem: MountItem) {
     mountItems.add(mountItem)
+    notifyItemsQueued()
   }
 
   fun addPreAllocateMountItem(mountItem: MountItem) {
     // We do this check only for PreAllocateViewMountItem - and not DispatchMountItem or regular
-    // MountItem - because PreAllocateViewMountItems are not batched, and is relatively more
+    // MountItem - because PreAllocateViewMountItem are not batched, and is relatively more
     // expensive
     // both to queue, to drain, and to execute.
     if (!mountingManager.surfaceIsStopped(mountItem.getSurfaceId())) {
       preMountItems.add(mountItem)
+      notifyItemsQueued()
     } else if (FabricUIManager.IS_DEVELOPMENT_ENVIRONMENT) {
       FLog.e(
           TAG,
@@ -399,6 +414,9 @@ internal class MountItemDispatcher(
     fun didMountItems(mountItems: List<MountItem>?)
 
     fun didDispatchMountItems()
+
+    /** Called (from any thread) whenever new items are queued into the dispatcher. */
+    fun onItemsQueued()
   }
 
   private companion object {

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<<ab68be1fe69275aae7e13121d0827f0e>>
+ * @generated SignedSource<<a39494512e761e266940e5d1853f38fc>>
  */
 
 /**
@@ -60,6 +60,12 @@ public object ReactNativeFeatureFlags {
   @JvmStatic
   public fun disableEarlyViewCommandExecution(): Boolean = accessor.disableEarlyViewCommandExecution()
 
+  /**
+   * Stop re-arming the DISPATCH_UI Choreographer frame callback at vsync rate while no mount items are pending on Android; queueing new items re-arms it
+   */
+  @JvmStatic
+  public fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean = accessor.disableIdleMountItemFrameCallbackRearmAndroid()
+
   /**
    * Force disable view preallocation for images triggered from createNode off the main thread on Android
    */

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<<00e1e0529cbef727ab81a6a75174c87e>>
+ * @generated SignedSource<<cd1753241fa2f51c23cd4e01ffe3f18c>>
  */
 
 /**
@@ -25,6 +25,7 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
   private var cxxNativeAnimatedEnabledCache: Boolean? = null
   private var defaultTextToOverflowHiddenCache: Boolean? = null
   private var disableEarlyViewCommandExecutionCache: Boolean? = null
+  private var disableIdleMountItemFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableImageViewPreallocationAndroidCache: Boolean? = null
   private var disableMountItemReorderingAndroidCache: Boolean? = null
   private var disableSubviewClippingAndroidCache: Boolean? = null
@@ -154,6 +155,15 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
     return cached
   }
 
+  override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean {
+    var cached = disableIdleMountItemFrameCallbackRearmAndroidCache
+    if (cached == null) {
+      cached = ReactNativeFeatureFlagsCxxInterop.disableIdleMountItemFrameCallbackRearmAndroid()
+      disableIdleMountItemFrameCallbackRearmAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun disableImageViewPreallocationAndroid(): Boolean {
     var cached = disableImageViewPreallocationAndroidCache
     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<<427c98d364e8a0aec3a0834b6a8117c8>>
+ * @generated SignedSource<<eb8737673aaec0b1eda6ae2ebc0b9970>>
  */
 
 /**
@@ -38,6 +38,8 @@ public object ReactNativeFeatureFlagsCxxInterop {
 
   @DoNotStrip @JvmStatic public external fun disableEarlyViewCommandExecution(): Boolean
 
+  @DoNotStrip @JvmStatic public external fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean
+
   @DoNotStrip @JvmStatic public external fun disableImageViewPreallocationAndroid(): Boolean
 
   @DoNotStrip @JvmStatic public external fun disableMountItemReorderingAndroid(): 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<<b6c47b10d221b493df4038e492482961>>
+ * @generated SignedSource<<890e204b6cf8afef481f64de44766edf>>
  */
 
 /**
@@ -33,6 +33,8 @@ public open class ReactNativeFeatureFlagsDefaults : ReactNativeFeatureFlagsProvi
 
   override fun disableEarlyViewCommandExecution(): Boolean = false
 
+  override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean = false
+
   override fun disableImageViewPreallocationAndroid(): Boolean = false
 
   override fun disableMountItemReorderingAndroid(): Boolean = false

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<<20a908f1ef475bb5f51b631e2d0f2038>>
+ * @generated SignedSource<<9044f0df865ba9d7668f9ff391d21911>>
  */
 
 /**
@@ -29,6 +29,7 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
   private var cxxNativeAnimatedEnabledCache: Boolean? = null
   private var defaultTextToOverflowHiddenCache: Boolean? = null
   private var disableEarlyViewCommandExecutionCache: Boolean? = null
+  private var disableIdleMountItemFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableImageViewPreallocationAndroidCache: Boolean? = null
   private var disableMountItemReorderingAndroidCache: Boolean? = null
   private var disableSubviewClippingAndroidCache: Boolean? = null
@@ -163,6 +164,16 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
     return cached
   }
 
+  override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean {
+    var cached = disableIdleMountItemFrameCallbackRearmAndroidCache
+    if (cached == null) {
+      cached = currentProvider.disableIdleMountItemFrameCallbackRearmAndroid()
+      accessedFeatureFlags.add("disableIdleMountItemFrameCallbackRearmAndroid")
+      disableIdleMountItemFrameCallbackRearmAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun disableImageViewPreallocationAndroid(): Boolean {
     var cached = disableImageViewPreallocationAndroidCache
     if (cached == null) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/internal/featureflags/ReactNativeFeatureFlagsOverrides_RNOSS_Experimental_Android.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<<bad3dbaf92a0a869dfb91523ef4904f9>>
+ * @generated SignedSource<<9a51a403bfc02cd33bbe47c1f0fe6fd6>>
  */
 
 /**
@@ -23,6 +23,8 @@ public open class ReactNativeFeatureFlagsOverrides_RNOSS_Experimental_Android :
   // We could use JNI to get the defaults from C++,
   // but that is more expensive than just duplicating the defaults here.
 
+  override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean = true
+
   override fun enableFlexboxAutoMinSizeInStrictMode(): Boolean = true
 
   override fun preventShadowTreeCommitExhaustion(): Boolean = true

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<<ac56780559e180d552086f3c53a1f111>>
+ * @generated SignedSource<<cfd99e53a077549124370e6bb123ba43>>
  */
 
 /**
@@ -33,6 +33,8 @@ public interface ReactNativeFeatureFlagsProvider {
 
   @DoNotStrip public fun disableEarlyViewCommandExecution(): Boolean
 
+  @DoNotStrip public fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean
+
   @DoNotStrip public fun disableImageViewPreallocationAndroid(): Boolean
 
   @DoNotStrip public fun disableMountItemReorderingAndroid(): Boolean

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<<13e3827487eba885b4de3746844f1942>>
+ * @generated SignedSource<<e6f56d60147d5c08e0b38549b9956e52>>
  */
 
 /**
@@ -69,6 +69,12 @@ class ReactNativeFeatureFlagsJavaProvider
     return method(javaProvider_);
   }
 
+  bool disableIdleMountItemFrameCallbackRearmAndroid() override {
+    static const auto method =
+        getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("disableIdleMountItemFrameCallbackRearmAndroid");
+    return method(javaProvider_);
+  }
+
   bool disableImageViewPreallocationAndroid() override {
     static const auto method =
         getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("disableImageViewPreallocationAndroid");
@@ -596,6 +602,11 @@ bool JReactNativeFeatureFlagsCxxInterop::disableEarlyViewCommandExecution(
   return ReactNativeFeatureFlags::disableEarlyViewCommandExecution();
 }
 
+bool JReactNativeFeatureFlagsCxxInterop::disableIdleMountItemFrameCallbackRearmAndroid(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
+  return ReactNativeFeatureFlags::disableIdleMountItemFrameCallbackRearmAndroid();
+}
+
 bool JReactNativeFeatureFlagsCxxInterop::disableImageViewPreallocationAndroid(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
   return ReactNativeFeatureFlags::disableImageViewPreallocationAndroid();
@@ -1057,6 +1068,9 @@ void JReactNativeFeatureFlagsCxxInterop::registerNatives() {
       makeNativeMethod(
         "disableEarlyViewCommandExecution",
         JReactNativeFeatureFlagsCxxInterop::disableEarlyViewCommandExecution),
+      makeNativeMethod(
+        "disableIdleMountItemFrameCallbackRearmAndroid",
+        JReactNativeFeatureFlagsCxxInterop::disableIdleMountItemFrameCallbackRearmAndroid),
       makeNativeMethod(
         "disableImageViewPreallocationAndroid",
         JReactNativeFeatureFlagsCxxInterop::disableImageViewPreallocationAndroid),