Fix iOS JS timers when the system clock changes

## Summary:

On iOS, `RCTTiming` uses wall-clock dates for pending JS timers. Moving the system clock backward can delay `setTimeout` and `setInterval`, and moving it forward can make them fire early.

Use a monotonic clock for timer deadlines and wakeup ordering so callbacks follow elapsed time, including time spent asleep.

Related to #59782.

## Changelog:

[IOS] [FIXED] - Keep JavaScript timers on schedule when the system clock changes.

## Test Plan:

Ran `RCTTimingClockChangeTests` through the `RNTesterUnitTests` scheme on an iPhone 18 Pro simulator running iOS 27.2. The tests simulate a one-hour wall-clock jump and check that:

- A forward jump does not fire a pending `setTimeout` early.
- A backward jump does not delay a due `setTimeout`.
- A backward jump does not delay the next callback of a running `setInterval`.

All three tests failed on upstream commit `f480836` and passed with the fix. Both runs used the same local build settings. I excluded the existing `RCTImageLoaderTests.m` because it references undefined macros in this checkout, and added the Xcode Swift compatibility library search path. These build overrides are not part of the PR.

From `packages/rn-tester`, with `SIMULATOR_UDID` set to the simulator used for testing:

```sh
swift_lib="$(xcode-select -p)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/iphonesimulator"
xcodebuild test -workspace RNTesterPods.xcworkspace -scheme RNTesterUnitTests \
  -destination "platform=iOS Simulator,id=$SIMULATOR_UDID" \
  -only-testing:RNTesterUnitTests/RCTTimingClockChangeTests -parallel-testing-enabled NO \
  'EXCLUDED_SOURCE_FILE_NAMES=RCTImageLoaderTests.m' \
  "LIBRARY_SEARCH_PATHS=\$(inherited) $swift_lib" 2>&1 | xcbeautify
```

The test run was limited to this regression suite. A physical-device clock change was not tested.

Differential Revision: D131244913

Pull Request resolved: https://github.com/react/react-native/pull/59865
This commit is contained in:
Lyu You authored and GitHub committed 2026-11-13 13:43:34 +00:00
1 parent f2a0b2f06e
commit 85a285a4bb
3 files changed
+168 -26

No files matched your search

@@ -7,12 +7,16 @@
#import "RCTTiming.h"
#include <math.h>
#include <chrono>
#import <React/RCTAssert.h>
#import <React/RCTConvert.h>
#import <React/RCTLog.h>
#import <React/RCTUtils.h>
static const NSTimeInterval kMinimumSleepInterval = 1;
static const NSTimeInterval kNoTimerTarget = INFINITY;
// These timing contants should be kept in sync with the ones in `JSTimers.js`.
// The duration of a frame. This assumes that we want to run at 60 fps.
@@ -20,9 +24,15 @@ static const NSTimeInterval kFrameDuration = 1.0 / 60.0;
// The minimum time left in a frame to trigger the idle callback.
static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
static NSTimeInterval RCTMonotonicTime()
{
// Apple libc++ uses CLOCK_MONOTONIC_RAW, which includes time spent asleep.
return std::chrono::duration<NSTimeInterval>(std::chrono::steady_clock::now().time_since_epoch()).count();
}
@interface _RCTTimer : NSObject
@property (nonatomic, strong, readonly) NSDate *target;
@property (nonatomic, assign, readonly) NSTimeInterval target;
@property (nonatomic, assign, readonly) BOOL repeats;
@property (nonatomic, copy, readonly) NSNumber *callbackID;
@property (nonatomic, assign, readonly) NSTimeInterval interval;
@@ -40,7 +50,7 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
_interval = interval;
_repeats = repeats;
_callbackID = callbackID;
_target = [NSDate dateWithTimeIntervalSinceNow:targetTime];
_target = RCTMonotonicTime() + targetTime;
}
return self;
}
@@ -48,18 +58,15 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
/**
* Returns `YES` if we should invoke the JS callback.
*/
- (BOOL)shouldFire:(NSDate *)now
- (BOOL)shouldFire:(NSTimeInterval)now
{
if (_target && [_target timeIntervalSinceDate:now] <= 0) {
return YES;
}
return NO;
return _target <= now;
}
- (void)reschedule
{
// The JS Timers will do fine grained calculating of expired timeouts.
_target = [NSDate dateWithTimeIntervalSinceNow:_interval];
_target = RCTMonotonicTime() + _interval;
}
@end
@@ -92,6 +99,7 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
@implementation RCTTiming {
NSMutableDictionary<NSNumber *, _RCTTimer *> *_timers;
NSTimer *_sleepTimer;
NSTimeInterval _sleepTimerTarget;
BOOL _sendIdleEvents;
BOOL _inBackground;
id<RCTTimingDelegate> _timingDelegate;
@@ -226,15 +234,15 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
- (void)didUpdateFrame:(RCTFrameUpdate *)update
{
NSDate *nextScheduledTarget = [NSDate distantFuture];
NSTimeInterval nextScheduledTarget = kNoTimerTarget;
NSMutableArray<_RCTTimer *> *timersToCall = [NSMutableArray new];
NSDate *now = [NSDate date]; // compare all the timers to the same base time
NSTimeInterval now = RCTMonotonicTime();
@synchronized(_timers) {
for (_RCTTimer *timer in _timers.allValues) {
if ([timer shouldFire:now]) {
[timersToCall addObject:timer];
} else {
nextScheduledTarget = [nextScheduledTarget earlierDate:timer.target];
} else if (timer.target < nextScheduledTarget) {
nextScheduledTarget = timer.target;
}
}
}
@@ -242,7 +250,13 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
// Call timers that need to be called
if (timersToCall.count > 0) {
NSArray<NSNumber *> *sortedTimers = [[timersToCall sortedArrayUsingComparator:^(_RCTTimer *a, _RCTTimer *b) {
return [a.target compare:b.target];
if (a.target < b.target) {
return NSOrderedAscending;
}
if (a.target > b.target) {
return NSOrderedDescending;
}
return NSOrderedSame;
}] valueForKey:@"callbackID"];
[_timingDelegate callTimers:sortedTimers];
}
@@ -250,7 +264,9 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
for (_RCTTimer *timer in timersToCall) {
if (timer.repeats) {
[timer reschedule];
nextScheduledTarget = [nextScheduledTarget earlierDate:timer.target];
if (timer.target < nextScheduledTarget) {
nextScheduledTarget = timer.target;
}
} else {
@synchronized(_timers) {
[_timers removeObjectForKey:timer.callbackID];
@@ -275,7 +291,7 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
timerCount = _timers.count;
}
if (_inBackground) {
if (timerCount != 0u) {
if (nextScheduledTarget != kNoTimerTarget) {
[self scheduleSleepTimer:nextScheduledTarget];
}
} else if (!_sendIdleEvents && timersToCall.count == 0) {
@@ -285,26 +301,30 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
_paused = YES;
}
// If the next timer is more than 1 second out, pause and schedule an NSTimer;
else if ([nextScheduledTarget timeIntervalSinceNow] > kMinimumSleepInterval) {
else if (
nextScheduledTarget != kNoTimerTarget && nextScheduledTarget - RCTMonotonicTime() > kMinimumSleepInterval) {
[self scheduleSleepTimer:nextScheduledTarget];
_paused = YES;
}
}
}
- (void)scheduleSleepTimer:(NSDate *)sleepTarget
- (void)scheduleSleepTimer:(NSTimeInterval)sleepTarget
{
@synchronized(self) {
NSTimeInterval delay = MAX(sleepTarget - RCTMonotonicTime(), 0);
if ((_sleepTimer == nil) || !_sleepTimer.valid) {
_sleepTimer = [[NSTimer alloc] initWithFireDate:sleepTarget
interval:0
target:[_RCTTimingProxy proxyWithTarget:self]
selector:@selector(timerDidFire)
userInfo:nil
repeats:NO];
_sleepTimer = [NSTimer timerWithTimeInterval:delay
target:[_RCTTimingProxy proxyWithTarget:self]
selector:@selector(timerDidFire)
userInfo:nil
repeats:NO];
_sleepTimerTarget = sleepTarget;
[[NSRunLoop currentRunLoop] addTimer:_sleepTimer forMode:NSDefaultRunLoopMode];
} else {
_sleepTimer.fireDate = [_sleepTimer.fireDate earlierDate:sleepTarget];
} else if (sleepTarget <= _sleepTimerTarget) {
// Convert to a date only when setting the run loop's wakeup.
_sleepTimer.fireDate = [NSDate dateWithTimeIntervalSinceNow:delay];
_sleepTimerTarget = sleepTarget;
}
}
}
@@ -347,7 +367,7 @@ static const NSTimeInterval kIdleCallbackFrameDeadline = 0.001;
if (_inBackground) {
[self scheduleSleepTimer:timer.target];
} else if (_paused) {
if ([timer.target timeIntervalSinceNow] > kMinimumSleepInterval) {
if (timer.target - RCTMonotonicTime() > kMinimumSleepInterval) {
[self scheduleSleepTimer:timer.target];
} else {
[self startTimers];
@@ -17,6 +17,7 @@
602160B9478DAFF2BAB56595 /* RCTUtilsTests.m in Sources */ = {isa = PBXBuildFile; fileRef = D5D13FB1445C5C19639921CC /* RCTUtilsTests.m */; };
79B29C2E2E607A99007612A5 /* SceneDelegate.mm in Sources */ = {isa = PBXBuildFile; fileRef = 79B29C2D2E607A99007612A5 /* SceneDelegate.mm */; };
7F806D4D4D97AD6403558B35 /* RCTStatusBarAppearanceTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 67B0814814F7C07E196BC295 /* RCTStatusBarAppearanceTests.mm */; };
A8717727467541429C262C63 /* RCTTimingClockChangeTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = A8717727467541429C262C64 /* RCTTimingClockChangeTests.mm */; };
8145AE06241172D900A3F8DA /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 8145AE05241172D900A3F8DA /* LaunchScreen.storyboard */; };
832F45BB2A8A6E1F0097B4E6 /* SwiftTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 832F45BA2A8A6E1F0097B4E6 /* SwiftTest.swift */; };
A975CA6C2C05EADF0043F72A /* RCTNetworkTaskTests.m in Sources */ = {isa = PBXBuildFile; fileRef = A975CA6B2C05EADE0043F72A /* RCTNetworkTaskTests.m */; };
@@ -89,6 +90,7 @@
51BC9297B6C3163C14532020 /* Pods-RNTester.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-RNTester.release.xcconfig"; path = "Target Support Files/Pods-RNTester/Pods-RNTester.release.xcconfig"; sourceTree = "<group>"; };
5C60EB1B226440DB0018C04F /* AppDelegate.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; name = AppDelegate.mm; path = RNTester/AppDelegate.mm; sourceTree = "<group>"; };
67B0814814F7C07E196BC295 /* RCTStatusBarAppearanceTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = RCTStatusBarAppearanceTests.mm; sourceTree = "<group>"; };
A8717727467541429C262C64 /* RCTTimingClockChangeTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = RCTTimingClockChangeTests.mm; sourceTree = "<group>"; };
79B29C2C2E607A99007612A5 /* SceneDelegate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SceneDelegate.h; path = RNTester/SceneDelegate.h; sourceTree = "<group>"; };
79B29C2D2E607A99007612A5 /* SceneDelegate.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; name = SceneDelegate.mm; path = RNTester/SceneDelegate.mm; sourceTree = "<group>"; };
8145AE05241172D900A3F8DA /* LaunchScreen.storyboard */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = file.storyboard; name = LaunchScreen.storyboard; path = RNTester/LaunchScreen.storyboard; sourceTree = "<group>"; };
@@ -318,6 +320,7 @@
D5D13FB1445C5C19639921CC /* RCTUtilsTests.m */,
E7DB20B322B2BAA4005AC45F /* RNTesterUnitTestsBundle.js */,
67B0814814F7C07E196BC295 /* RCTStatusBarAppearanceTests.mm */,
A8717727467541429C262C64 /* RCTTimingClockChangeTests.mm */,
);
path = RNTesterUnitTests;
sourceTree = "<group>";
@@ -637,6 +640,7 @@
E7DB20D822B2BAA6005AC45F /* RCTJSONTests.m in Sources */,
602160B9478DAFF2BAB56595 /* RCTUtilsTests.m in Sources */,
7F806D4D4D97AD6403558B35 /* RCTStatusBarAppearanceTests.mm in Sources */,
A8717727467541429C262C63 /* RCTTimingClockChangeTests.mm in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
@@ -0,0 +1,118 @@
/*
* 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.
*/
#import <XCTest/XCTest.h>
#import <objc/runtime.h>
#import <React/RCTTiming.h>
static constexpr NSTimeInterval kClockJump = 60 * 60;
static constexpr NSTimeInterval kTimerDelay = 0.05;
static thread_local NSTimeInterval wallClockOffset;
static Method dateMethod()
{
return class_getClassMethod(NSDate.class, @selector(date));
}
static auto originalDateImplementation()
{
static const auto implementation = method_getImplementation(dateMethod());
return implementation;
}
static NSDate *dateWithClockOffset(id receiver, SEL selector)
{
auto originalDate = reinterpret_cast<NSDate *(*)(id, SEL)>(originalDateImplementation());
NSDate *now = originalDate(receiver, selector);
return wallClockOffset == 0 ? now : [now dateByAddingTimeInterval:wallClockOffset];
}
@interface RCTTimingClockChangeTests : XCTestCase <RCTTimingDelegate>
@end
@implementation RCTTimingClockChangeTests {
RCTTiming *_timing;
NSMutableArray<NSNumber *> *_callbacks;
}
- (void)setUp
{
[super setUp];
_callbacks = [NSMutableArray new];
_timing = [[RCTTiming alloc] initWithDelegate:self];
}
- (void)tearDown
{
[_timing invalidate];
_timing = nil;
[super tearDown];
}
- (void)callTimers:(NSArray<NSNumber *> *)timers
{
[_callbacks addObjectsFromArray:timers];
}
- (void)immediatelyCallTimer:(NSNumber *)callbackID
{
[_callbacks addObject:callbackID];
}
- (void)callIdleCallbacks:(NSNumber *)absoluteFrameStartMS
{
}
- (void)updateFrameWithClockOffset:(NSTimeInterval)offset
{
// Simulate a clock change after scheduling. Only this thread sees the
// shifted time, and only while checking which timers are due.
IMP original = originalDateImplementation();
wallClockOffset = offset;
method_setImplementation(dateMethod(), reinterpret_cast<IMP>(dateWithClockOffset));
@try {
[_timing didUpdateFrame:nil];
} @finally {
method_setImplementation(dateMethod(), original);
wallClockOffset = 0;
}
}
- (void)testClockMovingForwardDoesNotFirePendingTimeoutEarly
{
[_timing createTimerForNextFrame:@1 duration:60 jsSchedulingTime:nil repeats:NO];
[self updateFrameWithClockOffset:kClockJump];
XCTAssertEqual(_callbacks.count, 0u);
}
- (void)testClockMovingBackwardDoesNotDelayDueTimeout
{
[_timing createTimerForNextFrame:@1 duration:kTimerDelay jsSchedulingTime:nil repeats:NO];
[NSThread sleepForTimeInterval:2 * kTimerDelay];
[self updateFrameWithClockOffset:-kClockJump];
XCTAssertEqualObjects(_callbacks, (@[ @1 ]));
}
- (void)testClockMovingBackwardDoesNotDelayRescheduledInterval
{
[_timing createTimerForNextFrame:@1 duration:kTimerDelay jsSchedulingTime:nil repeats:YES];
[NSThread sleepForTimeInterval:2 * kTimerDelay];
[_timing didUpdateFrame:nil];
XCTAssertEqualObjects(_callbacks, (@[ @1 ]));
[NSThread sleepForTimeInterval:2 * kTimerDelay];
[self updateFrameWithClockOffset:-kClockJump];
XCTAssertEqualObjects(_callbacks, (@[ @1, @1 ]));
}
@end