Add an internal option to skip Native Animated frames while inactive (#58295)

Summary:
Pull Request resolved: https://github.com/react/react-native/pull/58295

This is to investigate a crash on ios in C++ Animated rollout.

On iOS, Native Animated drives frames from a `CADisplayLink` on the main run
loop. While the app is inactive — which includes the whole
`UIApplicationWillEnterForeground` → `UIApplicationDidBecomeActive` transition
— it is not presenting, so a frame rendered then is never seen. Its commit and
synchronous per-view updates still run on the main thread though, competing
with the work the app must complete to become responsive.

Adds `initWithSkipFramesDuringForegroundTransition:` to
`RCTAnimatedModuleProvider`, declared in a new
`RCTAnimatedModuleProvider+Private.h`. When YES, `_onDisplayLinkTick` returns
early while `applicationState == UIApplicationStateInactive`.

**The public API is unchanged.** `RCTAnimatedModuleProvider.h` is untouched and
the C++ API snapshots have no delta — `+Private.h` is in the ReactApple
`exclude_patterns`. Plain `init` still exists and defaults to NO, so every
existing caller is unaffected; only hosts that opt in via the private header see
different behaviour.

Two properties worth being explicit about:

- **The clock is not stopped, only the frame is skipped.** `AnimationDriver`
  computes progress from a timestamp
  (`timeDeltaMs = frameTimeMs - startFrameTimeMs_`), so the first frame after
  activation resolves to the value the animation should have reached rather
  than resuming from where it was suspended.
- **Frames are not skipped while backgrounded** — `Background` is not
  `Inactive`. Completion handlers, and any app logic they drive, are therefore
  delayed by at most the length of the transition, not by the time spent in the
  background.

Reading `applicationState` rather than tracking lifecycle notifications also
avoids a failure mode: a mirrored flag must be cleared on every path out of the
transition, including an abandoned foregrounding (a `willEnterForeground` with
no following `didBecomeActive`), or frames are skipped indefinitely. There is no
such state to get stuck here.

`UIApplicationStateInactive` also covers other non-presenting moments — Control
Center, the app switcher, an incoming call banner. Skipping frames there is
harmless for the same reason: the clock keeps running and the first frame after
activation is correct.

The check sits inside the file's existing `TARGET_OS_OSX` guard, since
`UIApplication` is iOS-only and this translation unit also builds for macOS.

Changelog:
[Internal]

Reviewed By: javache, christophpurrer

Differential Revision: D118188111

fbshipit-source-id: c9f19fafd7bc6f07649a7160fd71b02de888f879
This commit is contained in:
Zeya Peng authored and meta-codesync[bot] committed 2026-09-03 07:43:11 -07:00
1 parent d3b7893998
commit 3f9f385a0e
2 files changed
+47

No files matched your search

@@ -0,0 +1,20 @@
/*
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
#pragma once
#import <RCTAnimatedModuleProvider/RCTAnimatedModuleProvider.h>
@interface RCTAnimatedModuleProvider (Private)
/**
* When true, animated frames are skipped while the application is inactive (between
* `UIApplicationWillEnterForeground` -> `UIApplicationDidBecomeActive`), default is false.
*/
- (instancetype)initWithSkipFramesDuringForegroundTransition:(BOOL)skipFramesDuringForegroundTransition;
@end
@@ -7,12 +7,15 @@
#import "RCTAnimatedModuleProvider.h"
#import "RCTAnimatedModuleProvider+Private.h"
#import <functional>
#if TARGET_OS_OSX
#import <React/RCTPlatformDisplayLink.h>
#else
#import <QuartzCore/CADisplayLink.h>
#import <UIKit/UIKit.h>
#endif
#import <react/featureflags/ReactNativeFeatureFlags.h>
@@ -28,6 +31,21 @@
std::function<void()> _onRender;
std::weak_ptr<facebook::react::NativeAnimatedNodesManagerProvider> _nativeAnimatedNodesManagerProvider;
BOOL _skipFramesDuringForegroundTransition;
}
- (instancetype)init
{
return [self initWithSkipFramesDuringForegroundTransition:NO];
}
- (instancetype)initWithSkipFramesDuringForegroundTransition:(BOOL)skipFramesDuringForegroundTransition
{
if (self = [super init]) {
_skipFramesDuringForegroundTransition = skipFramesDuringForegroundTransition;
}
return self;
}
- (void)dealloc
@@ -61,6 +79,15 @@
// use-after-free during hot reload. The provider must remain alive for the
// entire duration of _onRender() since it holds references to the animation
// nodes manager and related data structures.
#if !TARGET_OS_OSX
// See initWithSkipFramesDuringForegroundTransition: the frame is skipped,
// never the clock.
if (_skipFramesDuringForegroundTransition &&
UIApplication.sharedApplication.applicationState == UIApplicationStateInactive) {
return;
}
#endif
auto strongProvider = _nativeAnimatedNodesManagerProvider.lock();
if (strongProvider != nullptr && _displayLink != nullptr && _onRender != nullptr) {
_onRender();