iOS] Migrate VSyncClient to a pure Obj-C implementation (#186166) by cbracken · Pull Request #186935 · flutter/flutter

cbracken · 2026-05-22T09:40:23Z

Migrates FlutterVSyncClient from a hybrid C++/Obj-C implementation to a pure Objective-C implementation by removing C++ types from its interface and implementation.

Previously, FlutterVSyncClient stored a C++
flutter::VsyncWaiter::Callback and used a temporary std::unique_ptr<flutter::FrameTimingsRecorder> to propagate vsync timestamps. This was redundant:

FlutterVSyncClient allocated a temporary FrameTimingsRecorder and recorded vsync times.
It passed this to a C++ lambda wrapper.
The lambda extracted the start/target times as seconds and passed them to the Obj-C block callback.
The temporary recorder was immediately discarded.
VsyncWaiterIOS converted the seconds back to fml::TimePoint.
VsyncWaiter::FireCallback allocated another FrameTimingsRecorder and recorded the same times again.

We now:

manage the callback as pure Obj-C block that accepts raw CFTimeInterval (double seconds) directly from CADisplayLink.
Remove the redundant FrameTimingsRecorder and C++ lambda wrapper.
Rely solely on VsyncWaiter::FireCallback to handle the final FrameTimingsRecorder creation and recording, which it already does.

This is a re-land of #186166 which was reverted in #186266. That patch failed to correctly adjust the epoch of timestamps obtained from CoreAnimation (which uses mach_absolute_time under the hood) to the epoch used by the core engine, which is built on fml::TimePoint, which uses std::chrono::steady_clock, which uses mach_continuous_time under the hood, consistent with the C++ specification's of a continuous clock. While these two clocks start roughly synchronized at boot, mach_absolute_time pauses on device sleep, whereas mach_continuous_time does not.

The iOS embedder now uses timings based on CoreAnimation throughout and translates to fml::TimePoint only at the engine-embedder boundary. This is consistent with embedders based on the embedder API, such as macOS, which does this work in -[FlutterEngine viewControllerViewDidLoad] using FlutterTimeConverter.

Added tests for frame rate snapping/fallback. No other test changes because this introduces no semantic change and is covered by existing tests recently added in: #186457

Issue: #112232

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Migrates `FlutterVSyncClient` from a hybrid C++/Obj-C implementation to a pure Objective-C implementation by removing C++ types from its interface and implementation. Previously, `FlutterVSyncClient` stored a C++ `flutter::VsyncWaiter::Callback` and used a temporary `std::unique_ptr<flutter::FrameTimingsRecorder>` to propagate vsync timestamps. This was redundant: * `FlutterVSyncClient` allocated a temporary `FrameTimingsRecorder` and recorded vsync times. * It passed this to a C++ lambda wrapper. * The lambda extracted the start/target times as seconds and passed them to the Obj-C block callback. * The temporary recorder was immediately discarded. * `VsyncWaiterIOS` converted the seconds back to `fml::TimePoint`. * `VsyncWaiter::FireCallback` allocated *another* `FrameTimingsRecorder` and recorded the same times again. We now: * manage the callback as pure Obj-C block that accepts raw `CFTimeInterval` (double seconds) directly from `CADisplayLink`. * Remove the redundant `FrameTimingsRecorder` and C++ lambda wrapper. * Rely solely on `VsyncWaiter::FireCallback` to handle the final `FrameTimingsRecorder` creation and recording, which it already does. No test changes because this introduces no semantic change and is covered by existing tests recently added in: flutter#186457 Issue: flutter#112232

flutter-dashboard · 2026-05-22T09:40:28Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

gemini-code-assist

Code Review

This pull request refactors VSync timing on iOS by transitioning from FML-based time points to CACurrentMediaTime and replacing C++ callbacks with Objective-C blocks in FlutterVSyncClient. It also updates VsyncWaiterIOS to align these timestamps with the engine's steady clock. Feedback was provided regarding a potential division-by-zero error and a misleading code comment in the duration calculation logic.

cbracken · 2026-05-22T10:38:21Z

-  # for example), consider adding them to the ":framework_common_swift_unittests"
-  # target.
+  # for example), consider adding them to the
+  # ":framework_common_swift_unittests" target.


Not an actual change but turns out we were past 80 cols which upset the format presubmit.

cbracken · 2026-05-22T10:40:07Z

      "framework/Source/SemanticsObjectTest.mm",
      "framework/Source/SemanticsObjectTestMocks.h",
      "framework/Source/UIViewController_FlutterScreenAndSceneIfLoadedTest.mm",
+      "framework/Source/VsyncWaiterIOSTest.mm",


Yes, the filename is inconsistent with the implementation file, but the test is an Obj-C XCTest and the class under test is a C++ class, hence the difference in naming.

cbracken · 2026-05-22T10:44:01Z

  CGFloat currentInset = delegate.physicalViewInsetBottom;
  self.keyboardAnimationView.frame = CGRectMake(0, currentInset, 0, 0);
-  self.keyboardAnimationStartTime = fml::TimePoint::Now().ToEpochDelta().ToSecondsF();
+  self.keyboardAnimationStartTime = CACurrentMediaTime();


Note that this was adjusted since FlutterVSyncClient is now pure Obj-C and sticks to CoreAnimation APIs (along with the rest of the embedder now).

cbracken · 2026-05-22T10:47:39Z

+        VsyncWaiterIOS::SnapDuration(targetTime - startTime, max_refresh_rate_);
+
+    // Align target time to the C++ steady_clock used by fml::TimePoint.
+    fml::TimePoint target_time = start_time + fml::TimeDelta::FromSecondsF(duration);


The core engine deals in fml::TimePoints which are based on std::chrono::steady_clock which is backed by mach_continuous_time, whereas CoreAnimation uses mach_absolute_time.

Consistent with embedders on the embedder API, we adjust the epoch for start and target time here.

The core engine deals in fml::TimePoints which are based on std::chrono::steady_clock which is backed by mach_continuous_time, whereas CoreAnimation uses mach_absolute_time.

This comment is helpful. can you add this info to the comment?

cbracken · 2026-05-22T11:05:41Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

Added tests.

hellohuanlin

should we rename this to .m file?

hellohuanlin · 2026-05-22T16:47:33Z

+        VsyncWaiterIOS::SnapDuration(targetTime - startTime, max_refresh_rate_);
+
+    // Align target time to the C++ steady_clock used by fml::TimePoint.
+    fml::TimePoint target_time = start_time + fml::TimeDelta::FromSecondsF(duration);


The core engine deals in fml::TimePoints which are based on std::chrono::steady_clock which is backed by mach_continuous_time, whereas CoreAnimation uses mach_absolute_time.

This comment is helpful. can you add this info to the comment?

hellohuanlin · 2026-05-22T16:48:12Z

  return client_.refreshRate;
 }

+CFTimeInterval VsyncWaiterIOS::SnapDuration(CFTimeInterval duration, double max_refresh_rate) {


what's "snap duration"?

See the comment on the method: it snaps the duration to a round number of Hz. Due to floating point error or tiny inconsistencies in timing the duration may be off by a few microseconds etc, so we compute the inverse (frequency in Hz) snap to the closes integer Hz (60, 120, etc. whatever the nearest int value of Hz is), then adjust the time to keep the frame timing from drifting)

We were doing this before but decided it'd be better to put it in a named method with a doc comment.

cbracken · 2026-05-22T23:28:34Z

should we rename this to .m file?

We can do better :) In my next PR, I'm renaming it to a .swift file. Will update the comment in that PR too of that's okay to avoid the reapproval dance this close to your end of day.

Roll Flutter from e03b91f1fe34 to f3a4b9897834 (63 revisions) flutter/flutter@e03b91f...f3a4b98 2026-05-26 47866232+chunhtai@users.noreply.github.com Update batch release doc to reflect latest workflow (flutter/flutter#186979) 2026-05-26 engine-flutter-autoroll@skia.org Roll Skia from 0442274cc696 to 27a819894f7c (5 revisions) (flutter/flutter#187094) 2026-05-26 bkonyi@google.com [Tool Robustness] Gracefully handle asynchronous subprocess crashes and connection timeouts (flutter/flutter#186964) 2026-05-26 bkonyi@google.com [pubspec] Bump Dart SDK constraint to ^3.13.0 (flutter/flutter#186957) 2026-05-26 engine-flutter-autoroll@skia.org Roll Dart SDK from 7eb54169841d to 00e625453c43 (1 revision) (flutter/flutter#187086) 2026-05-26 bdero@google.com [Impeller] Retire Y-coord-scale plumbing by flipping GLES at the vertex stage (flutter/flutter#186556) 2026-05-26 engine-flutter-autoroll@skia.org Roll Skia from f4f294bdf98d to 0442274cc696 (2 revisions) (flutter/flutter#187079) 2026-05-26 kevmoo@users.noreply.github.com [flutter_tools] Fix version cache poisoning from git environment variables (flutter/flutter#186595) 2026-05-26 bkonyi@google.com [Tool] Handle DTD connection failures gracefully in widget-preview (flutter/flutter#186952) 2026-05-25 engine-flutter-autoroll@skia.org Roll Skia from 9d1adb5f2427 to f4f294bdf98d (1 revision) (flutter/flutter#187056) 2026-05-25 engine-flutter-autoroll@skia.org Roll Skia from 4dd78179e6ec to 9d1adb5f2427 (1 revision) (flutter/flutter#187048) 2026-05-25 engine-flutter-autoroll@skia.org Roll Skia from 1f26101197bf to 4dd78179e6ec (4 revisions) (flutter/flutter#187044) 2026-05-24 engine-flutter-autoroll@skia.org Roll Skia from bbe9ccc2bdbf to 1f26101197bf (1 revision) (flutter/flutter#187016) 2026-05-24 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from nsgcNDlZOuweOvy3Q... to Itd2Jq_ZIABH2rW7B... (flutter/flutter#187032) 2026-05-23 engine-flutter-autoroll@skia.org Roll Dart SDK from 7e0f28eb5315 to 7eb54169841d (1 revision) (flutter/flutter#187005) 2026-05-23 engine-flutter-autoroll@skia.org Roll Dart SDK from 90e55fa88456 to 7e0f28eb5315 (1 revision) (flutter/flutter#186990) 2026-05-23 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from 6T6BY9PTftoG3vP_1... to nsgcNDlZOuweOvy3Q... (flutter/flutter#186984) 2026-05-23 chris@bracken.jp iOS] Migrate VSyncClient to a pure Obj-C implementation (#186166) (flutter/flutter#186935) 2026-05-23 30870216+gaaclarke@users.noreply.github.com Disables embedder_tests.cm for fuchsia (flutter/flutter#186969) 2026-05-23 engine-flutter-autoroll@skia.org Roll Dart SDK from b8414c46f6c7 to 90e55fa88456 (2 revisions) (flutter/flutter#186977) 2026-05-22 engine-flutter-autoroll@skia.org Roll Skia from 6fdb013d1953 to bbe9ccc2bdbf (1 revision) (flutter/flutter#186980) 2026-05-22 mdebbar@google.com [web] Fix cutoff text in WebParagraph (flutter/flutter#186819) 2026-05-22 1961493+harryterkelsen@users.noreply.github.com fix(web): Removes the iterative downscaling hack (flutter/flutter#186914) 2026-05-22 30870216+gaaclarke@users.noreply.github.com opts the linux embedder into sdf rendering (flutter/flutter#186909) 2026-05-22 engine-flutter-autoroll@skia.org Roll Skia from dae8778ca40d to 6fdb013d1953 (5 revisions) (flutter/flutter#186970) 2026-05-22 dacoharkes@google.com Fix hooks inputs outputs rebuilt (flutter/flutter#186701) 2026-05-22 30870216+gaaclarke@users.noreply.github.com adds linux impeller integration test for external textures (flutter/flutter#186759) 2026-05-22 kevmoo@users.noreply.github.com fix(flutter_tools): defensively catch DWDS unregistered service extension errors (flutter/flutter#186896) 2026-05-22 bdero@google.com [Impeller] Add golden harness support to the renderer test layer (flutter/flutter#186735) 2026-05-22 mdebbar@google.com [web] Remove image codecs from canvaskit_chromium (flutter/flutter#178133) 2026-05-22 30870216+gaaclarke@users.noreply.github.com opts all macos into wide gamut (flutter/flutter#186277) 2026-05-22 engine-flutter-autoroll@skia.org Roll Skia from 356185490a75 to dae8778ca40d (9 revisions) (flutter/flutter#186949) 2026-05-22 1598289+lukemmtt@users.noreply.github.com Filter out SwiftPM schemes when fetching schemes (flutter/flutter#186006) 2026-05-22 engine-flutter-autoroll@skia.org Roll Packages from 3754d04 to 69cf959 (1 revision) (flutter/flutter#186950) 2026-05-22 engine-flutter-autoroll@skia.org Roll Dart SDK from eca46bec956d to b8414c46f6c7 (2 revisions) (flutter/flutter#186944) 2026-05-22 30870216+gaaclarke@users.noreply.github.com Saves a DeviceHolderVK with the CommandPoolVK (flutter/flutter#186749) 2026-05-22 engine-flutter-autoroll@skia.org Roll Dart SDK from e0d509fd676e to eca46bec956d (1 revision) (flutter/flutter#186922) 2026-05-22 bkonyi@google.com [ Tool ] Stop generating widget preview scaffold under $TMP (flutter/flutter#186476) 2026-05-21 737941+loic-sharma@users.noreply.github.com Fix typo in StretchingOverscrollIndicator docs (flutter/flutter#186897) 2026-05-21 engine-flutter-autoroll@skia.org Roll Dart SDK from 28c7cb5a8e8d to e0d509fd676e (1 revision) (flutter/flutter#186903) 2026-05-21 jason-simmons@users.noreply.github.com Fix some issues in the integration between EmbedderExternalViewEmbedder and Impeller (flutter/flutter#184905) 2026-05-21 jason-simmons@users.noreply.github.com Fix a potential buffer overflow in the animated PNG decoder when parsing malformed fdAT chunks (flutter/flutter#186700) 2026-05-21 engine-flutter-autoroll@skia.org Roll Skia from 2ff20950975d to 356185490a75 (5 revisions) (flutter/flutter#186892) 2026-05-21 flar@google.com Add primitive shadows to rendering benchmark (flutter/flutter#186779) 2026-05-21 15619084+vashworth@users.noreply.github.com Move prefetchSwiftPackages to be per platform (flutter/flutter#186468) 2026-05-21 okorohelijah@google.com Upgrade iOS version (flutter/flutter#186889) ...

cbracken requested review from hellohuanlin and vashworth May 22, 2026 09:40

cbracken requested a review from a team as a code owner May 22, 2026 09:40

flutter-dashboard Bot added the CICD Run CI/CD label May 22, 2026

github-actions Bot added platform-ios iOS applications specifically engine flutter/engine related. See also e: labels. team-ios Owned by iOS platform team labels May 22, 2026

gemini-code-assist Bot reviewed May 22, 2026

View reviewed changes

Comment thread engine/src/flutter/shell/platform/darwin/ios/framework/Source/vsync_waiter_ios.mm Outdated

Address review feedback

6fd064b

github-actions Bot removed the CICD Run CI/CD label May 22, 2026

cbracken commented May 22, 2026

View reviewed changes

cbracken added the CICD Run CI/CD label May 22, 2026

hellohuanlin approved these changes May 22, 2026

View reviewed changes

cbracken added this pull request to the merge queue May 23, 2026

Merged via the queue into flutter:master with commit 722be07 May 23, 2026
202 checks passed

cbracken deleted the migrate-to-objc branch May 23, 2026 01:47

Conversation

cbracken commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

flutter-dashboard Bot commented May 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

cbracken May 22, 2026

Choose a reason for hiding this comment

Uh oh!

cbracken May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cbracken May 22, 2026

Choose a reason for hiding this comment

Uh oh!

cbracken May 22, 2026

Choose a reason for hiding this comment

Uh oh!

hellohuanlin May 22, 2026

Choose a reason for hiding this comment

Uh oh!

cbracken commented May 22, 2026

Uh oh!

hellohuanlin left a comment

Choose a reason for hiding this comment

Uh oh!

hellohuanlin May 22, 2026

Choose a reason for hiding this comment

Uh oh!

hellohuanlin May 22, 2026

Choose a reason for hiding this comment

Uh oh!

cbracken May 22, 2026

Choose a reason for hiding this comment

Uh oh!

cbracken commented May 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cbracken commented May 22, 2026 •

edited

Loading

cbracken May 22, 2026 •

edited

Loading