Android: make the batched-event-dispatch Choreographer frame callback one-shot (behind feature flag) (#58376)

Summary:
# Make the batched-event-dispatch Choreographer frame callback one-shot (Android)

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

`FabricEventDispatcher.ScheduleDispatchFrameCallback.doFrame` calls `dispatchBatchedEvents()` at the end of every frame — which (despite the name) only **re-posts the same frame callback**. Events themselves are dispatched synchronously as they are emitted, so once this callback is posted it keeps the `TIMERS_EVENTS` Choreographer armed at vsync rate forever, doing no work each frame beyond re-posting itself and firing the batch-dispatched listeners.

This PR makes the callback one-shot, behind `ReactNativeFeatureFlags.disableIdleEventDispatchFrameCallbackRearmAndroid` (default **false** = current behavior; `ossReleaseStage: 'experimental'`):

- With the flag on, `doFrame` clears `isFrameCallbackDispatchScheduled` and does not re-post.
- Re-arming is already demand-driven in the existing code: `dispatchEvent` → `scheduleDispatchOfBatchedEvents` → `maybeDispatchBatchedEvents` posts the callback whenever new events arrive while it is not scheduled, and `onHostResume` re-posts.

## Foregrounding / backgrounding

`onHostPause` / `onHostDestroy` → `cancelDispatchOfBatchedEvents()` and `onHostResume` → `scheduleDispatchOfBatchedEvents()` + `currentFrameCallback.resume()` are untouched. On the paused (`shouldStop`) frame the batch-dispatched listeners still fire, exactly as on `main`.

## Rollout

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

Changelog: [Internal]

Pull Request resolved: #58376

Test Plan:
- [x] Flag off (`defaultValue`): branch structure is identical to `main` (the legacy `shouldStop`/re-post path is taken verbatim).
- [x] Compiles: `./gradlew :packages:react-native:ReactAndroid:compileReleaseKotlin`.
- [ ] Flag on, real app on device (OnePlus 3T, Android 9): idle `adb shell atrace` shows the event-dispatch `doFrame` stops firing between event bursts; touch/scroll event delivery unchanged; pause/resume keeps events flowing after foreground return.
- [ ] Flag on: RNTester event integration tests pass.

## Changelog:

[Android] [Fixed] - Make the batched-event-dispatch Choreographer frame callback one-shot instead of re-posting itself every frame (behind `disableIdleEventDispatchFrameCallbackRearmAndroid`)

## Prior art

Same one-shot mechanism as #41658 (November 2023, removed by #43044 with the rest of `enableOnDemandReactChoreographer`). Comparison and analysis: #58367.

Reviewed By: christophpurrer

Differential Revision: D124365969

Pulled By: javache

fbshipit-source-id: 553e6679c5f13b4f4cb8f1d1ac5aaac1759a22c3

Author: capt-muji

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<<72ad53973a7de132705b9ec1a72aac08>>
+ * @generated SignedSource<<d824f6746b2cc7d4560164c04d123988>>
  */
 
 /**
@@ -60,6 +60,12 @@ public object ReactNativeFeatureFlags {
   @JvmStatic
   public fun disableEarlyViewCommandExecution(): Boolean = accessor.disableEarlyViewCommandExecution()
 
+  /**
+   * Make the batched-event-dispatch Choreographer frame callback one-shot on Android instead of re-posting itself every frame
+   */
+  @JvmStatic
+  public fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean = accessor.disableIdleEventDispatchFrameCallbackRearmAndroid()
+
   /**
    * 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
    */

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<<60051ebbc387ff06db855ed661340217>>
+ * @generated SignedSource<<ea771505a9f0b070dd8b2c4b50411c6e>>
  */
 
 /**
@@ -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 disableIdleEventDispatchFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableIdleMountItemFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableImageViewPreallocationAndroidCache: Boolean? = null
   private var disableMountItemReorderingAndroidCache: Boolean? = null
@@ -157,6 +158,15 @@ internal class ReactNativeFeatureFlagsCxxAccessor : ReactNativeFeatureFlagsAcces
     return cached
   }
 
+  override fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean {
+    var cached = disableIdleEventDispatchFrameCallbackRearmAndroidCache
+    if (cached == null) {
+      cached = ReactNativeFeatureFlagsCxxInterop.disableIdleEventDispatchFrameCallbackRearmAndroid()
+      disableIdleEventDispatchFrameCallbackRearmAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean {
     var cached = disableIdleMountItemFrameCallbackRearmAndroidCache
     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<<9ed55c4c14d640c0fb2bd6c8fb7ef557>>
+ * @generated SignedSource<<51b7baf7b3c2758ec619c77cb4fa637d>>
  */
 
 /**
@@ -38,6 +38,8 @@ public object ReactNativeFeatureFlagsCxxInterop {
 
   @DoNotStrip @JvmStatic public external fun disableEarlyViewCommandExecution(): Boolean
 
+  @DoNotStrip @JvmStatic public external fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean
+
   @DoNotStrip @JvmStatic public external fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean
 
   @DoNotStrip @JvmStatic public external fun disableImageViewPreallocationAndroid(): 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<<2170527111c8b3c34c213c24a9948931>>
+ * @generated SignedSource<<e8540d339cda9300ee0eac6e2ce316d2>>
  */
 
 /**
@@ -33,6 +33,8 @@ public open class ReactNativeFeatureFlagsDefaults : ReactNativeFeatureFlagsProvi
 
   override fun disableEarlyViewCommandExecution(): Boolean = false
 
+  override fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean = false
+
   override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean = false
 
   override fun disableImageViewPreallocationAndroid(): 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<<a96a359df0616229d7a7979ae9499ecc>>
+ * @generated SignedSource<<3e94c46a8a6fda2a4c0378e326291d73>>
  */
 
 /**
@@ -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 disableIdleEventDispatchFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableIdleMountItemFrameCallbackRearmAndroidCache: Boolean? = null
   private var disableImageViewPreallocationAndroidCache: Boolean? = null
   private var disableMountItemReorderingAndroidCache: Boolean? = null
@@ -166,6 +167,16 @@ internal class ReactNativeFeatureFlagsLocalAccessor : ReactNativeFeatureFlagsAcc
     return cached
   }
 
+  override fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean {
+    var cached = disableIdleEventDispatchFrameCallbackRearmAndroidCache
+    if (cached == null) {
+      cached = currentProvider.disableIdleEventDispatchFrameCallbackRearmAndroid()
+      accessedFeatureFlags.add("disableIdleEventDispatchFrameCallbackRearmAndroid")
+      disableIdleEventDispatchFrameCallbackRearmAndroidCache = cached
+    }
+    return cached
+  }
+
   override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean {
     var cached = disableIdleMountItemFrameCallbackRearmAndroidCache
     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<<9a51a403bfc02cd33bbe47c1f0fe6fd6>>
+ * @generated SignedSource<<c5daa3cf1c88507ccb625ba7367dfcaf>>
  */
 
 /**
@@ -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 disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean = true
+
   override fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean = true
 
   override fun enableFlexboxAutoMinSizeInStrictMode(): 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<<256b97731c59551616a8e0cbc777f3fa>>
+ * @generated SignedSource<<0c7d62679814835a3ef86a63174c7f7f>>
  */
 
 /**
@@ -33,6 +33,8 @@ public interface ReactNativeFeatureFlagsProvider {
 
   @DoNotStrip public fun disableEarlyViewCommandExecution(): Boolean
 
+  @DoNotStrip public fun disableIdleEventDispatchFrameCallbackRearmAndroid(): Boolean
+
   @DoNotStrip public fun disableIdleMountItemFrameCallbackRearmAndroid(): Boolean
 
   @DoNotStrip public fun disableImageViewPreallocationAndroid(): Boolean

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/events/FabricEventDispatcher.kt

@@ -13,6 +13,7 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactSoftExceptionLogger
 import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.common.annotations.UnstableReactNativeAPI
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags
 import com.facebook.react.modules.core.ReactChoreographer
 import com.facebook.react.uimanager.UIManagerHelper
 import com.facebook.react.uimanager.common.UIManagerType
@@ -147,10 +148,18 @@ internal class FabricEventDispatcher(
     override fun doFrame(frameTimeNanos: Long) {
       UiThreadUtil.assertOnUiThread()
 
-      if (shouldStop) {
-        isFrameCallbackDispatchScheduled = false
+      if (!ReactNativeFeatureFlags.disableIdleEventDispatchFrameCallbackRearmAndroid()) {
+        if (shouldStop) {
+          isFrameCallbackDispatchScheduled = false
+        } else {
+          dispatchBatchedEvents()
+        }
       } else {
-        dispatchBatchedEvents()
+        // One-shot semantics: events are dispatched synchronously as they are emitted, so a
+        // posted callback only needs to fire the batch-dispatched listeners once. Re-posting
+        // here kept the Choreographer armed at vsync rate while idle; new events re-post via
+        // maybeDispatchBatchedEvents (see scheduleDispatchOfBatchedEvents/dispatchEvent).
+        isFrameCallbackDispatchScheduled = false
       }
 
       Systrace.beginSection(Systrace.TRACE_TAG_REACT, "BatchEventDispatchedListeners")

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<<2b4f896552dd54c3ec858ca788ab4254>>
+ * @generated SignedSource<<b5f8c3c048123ddda3c712f289313b3f>>
  */
 
 /**
@@ -69,6 +69,12 @@ class ReactNativeFeatureFlagsJavaProvider
     return method(javaProvider_);
   }
 
+  bool disableIdleEventDispatchFrameCallbackRearmAndroid() override {
+    static const auto method =
+        getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("disableIdleEventDispatchFrameCallbackRearmAndroid");
+    return method(javaProvider_);
+  }
+
   bool disableIdleMountItemFrameCallbackRearmAndroid() override {
     static const auto method =
         getReactNativeFeatureFlagsProviderJavaClass()->getMethod<jboolean()>("disableIdleMountItemFrameCallbackRearmAndroid");
@@ -614,6 +620,11 @@ bool JReactNativeFeatureFlagsCxxInterop::disableEarlyViewCommandExecution(
   return ReactNativeFeatureFlags::disableEarlyViewCommandExecution();
 }
 
+bool JReactNativeFeatureFlagsCxxInterop::disableIdleEventDispatchFrameCallbackRearmAndroid(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
+  return ReactNativeFeatureFlags::disableIdleEventDispatchFrameCallbackRearmAndroid();
+}
+
 bool JReactNativeFeatureFlagsCxxInterop::disableIdleMountItemFrameCallbackRearmAndroid(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop> /*unused*/) {
   return ReactNativeFeatureFlags::disableIdleMountItemFrameCallbackRearmAndroid();
@@ -1090,6 +1101,9 @@ void JReactNativeFeatureFlagsCxxInterop::registerNatives() {
       makeNativeMethod(
         "disableEarlyViewCommandExecution",
         JReactNativeFeatureFlagsCxxInterop::disableEarlyViewCommandExecution),
+      makeNativeMethod(
+        "disableIdleEventDispatchFrameCallbackRearmAndroid",
+        JReactNativeFeatureFlagsCxxInterop::disableIdleEventDispatchFrameCallbackRearmAndroid),
       makeNativeMethod(
         "disableIdleMountItemFrameCallbackRearmAndroid",
         JReactNativeFeatureFlagsCxxInterop::disableIdleMountItemFrameCallbackRearmAndroid),

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<<228fff4f0ef0e530bf50203050adb9b0>>
+ * @generated SignedSource<<a384c61ed84daad078fb102fdc734233>>
  */
 
 /**
@@ -45,6 +45,9 @@ class JReactNativeFeatureFlagsCxxInterop
   static bool disableEarlyViewCommandExecution(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
 
+  static bool disableIdleEventDispatchFrameCallbackRearmAndroid(
+    facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);
+
   static bool disableIdleMountItemFrameCallbackRearmAndroid(
     facebook::jni::alias_ref<JReactNativeFeatureFlagsCxxInterop>);