[macOS] Implement merged UI and platform thread #162883

knopp · 2025-02-07T16:44:00Z

Original issue: #150525

This PR lets the macOS embedder run both with and without UI and platform thread merged.

Thread merging is controlled through FLTEnableMergedPlatformUIThread info.plist option similar to iOS embedder, though the default value is currently false.

Changes in the resize / vsync synchronization:

Added FlutterRunLoop class to schedule Flutter tasks on main thread in a way where it is possible to only process these (Flutter posted) tasks while waiting for correct frame size during resizing. This significantly simplifies the resize synchronization and makes the same code work both with separate UI thread and with UI and platform thread merged.
FlutterThreadSynchronizer has been renamed to FlutterResizeSynchronizer vastly simplified, mutex and conditions are removed and the blocking is now done by only processing Flutter messages while waiting for resizing. It is now per view (instead of storing a viewId->Size map internally) and owned by the view itself, instead of engine.
This approach to resize synchronization will work for Windows and Linux as well. This will allow us to conceptually consolidate the way we do threading and resize synchronization on all three desktop embedders.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

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

munrocket · 2025-02-07T18:21:44Z

Awesome! Making own graphic API with FFI on macOS is impossible without this. We need to land it ASAP.

knopp · 2025-02-25T16:11:51Z

Putting this as WIP. With this PR with unmerged thread, CVDisplayLink is started on UI thread and stopped on platform thread. I initially assumed that would work, but it doesn't. During resizing the CVDisplayLink sometimes creates two threads and trying to stop it deadlocks.

CVDisplayLink API documentation doesn't make any threading guarantees, I assumed it was thread safe but it doesn't seem to be the case.

knopp · 2025-02-26T12:44:35Z

I've simplified display link / vsync waiter threading model. Now everything is expected to happen on main thread. This requires one extra hop from UI to platform thread with unmerged threads, and zero extra hops when running with merged threads (which will become default).

The mental overhead of trying to keep everything thread safe was probably not really worth it with unmerged threads and is definitely not worth it with merged threads. Also while not documented anywhere, CVDisplayLink seems to break when start and stop are called from different threads (despite having an internal mutex). This is no longer an issue since all start / stop calls are serialized and performed on main thread.

johnmccutchan · 2025-02-26T23:16:48Z

@knopp This is so great!

loic-sharma · 2025-03-18T17:33:45Z

cc @dkwingsmt as you've also worked on the macOS embedder

jonahwilliams · 2025-03-26T16:47:25Z

@knopp sorry we lost track of this, should I start reviewing?

knopp · 2025-03-26T20:24:24Z

@knopp sorry we lost track of this, should I start reviewing?

Yeah, the PR should be ready for review. Thanks!

cbracken

LGTM modulo a few nits!

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterDisplayLink.mm

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterDisplayLinkTest.mm

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngine.mm

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngineTest.mm

...ne/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizerTest.mm

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterRunLoop.mm

The descriptions share single bridge retained engine while both of them would release it.

…utter#162883)

Roll Flutter from a0b1b3253416 to 02f13c37841f (37 revisions) flutter/flutter@a0b1b32...02f13c3 2025-04-03 [email protected] Roll Packages from 07496eb to 4a36dc6 (3 revisions) (flutter/flutter#166542) 2025-04-03 [email protected] Roll Skia from b67e53719e78 to 5f65df75febd (2 revisions) (flutter/flutter#166538) 2025-04-03 [email protected] Update docs to debug the Android embedder (flutter/flutter#166170) 2025-04-03 [email protected] Roll Dart SDK from 72562ca93bb5 to d174ec16c3ea (1 revision) (flutter/flutter#166525) 2025-04-03 [email protected] [macOS] Implement merged UI and platform thread (flutter/flutter#162883) 2025-04-03 [email protected] Roll Skia from f91412f5d89d to b67e53719e78 (1 revision) (flutter/flutter#166527) 2025-04-03 [email protected] Roll Packages from 125c117 to 07496eb (31 revisions) (flutter/flutter#166457) 2025-04-03 [email protected] Roll Skia from 2be12bc2668b to f91412f5d89d (2 revisions) (flutter/flutter#166517) 2025-04-03 [email protected] Roll Dart SDK from 2a1a13cc3a91 to 72562ca93bb5 (2 revisions) (flutter/flutter#166514) 2025-04-03 [email protected] [native_assets] Roll dependencies (flutter/flutter#166282) 2025-04-03 [email protected] Fix read only TextField focus traversal on macOS (flutter/flutter#166056) 2025-04-03 [email protected] Roll Skia from c106d7831592 to 2be12bc2668b (1 revision) (flutter/flutter#166509) 2025-04-03 [email protected] Roll Fuchsia Linux SDK from v7PGvypiiWLO8PbsZ... to vYisSsIgqw0mqFRVJ... (flutter/flutter#166508) 2025-04-03 [email protected] Roll Dart SDK from b8b4076b1237 to 2a1a13cc3a91 (1 revision) (flutter/flutter#166504) 2025-04-03 [email protected] Roll Skia from 75a0ec473181 to c106d7831592 (1 revision) (flutter/flutter#166499) 2025-04-03 [email protected] Migrate to Theme.brightnessOf method (flutter/flutter#163950) 2025-04-03 [email protected] Fix: Range slider show overlay for both thumbs on hovering one (flutter/flutter#165393) 2025-04-03 [email protected] Deprecate ExpansionTileController (flutter/flutter#166368) 2025-04-03 [email protected] Add styling parameters in `PopupMenuDivider` (flutter/flutter#164790) 2025-04-03 [email protected] Fix ISSUE_TEMPLATE Ordering: `10 < 9`, but `10 > 09` (flutter/flutter#166455) 2025-04-03 [email protected] Skip flaking scheduler test (flutter/flutter#166471) 2025-04-02 [email protected] Roll pub packages (flutter/flutter#166043) 2025-04-02 [email protected] [a11y] add SemanticsValidationResult (flutter/flutter#165935) 2025-04-02 [email protected] Remove unnecessary cache busting mechanism in hot restart (flutter/flutter#166295) 2025-04-02 [email protected] Roll Skia from 52cbb917fffd to 75a0ec473181 (21 revisions) (flutter/flutter#166484) 2025-04-02 [email protected] Started pixel aligning hairlines (flutter/flutter#166351) 2025-04-02 [email protected] Adds semantics role and adjust semantics for navigation bar (flutter/flutter#162467) 2025-04-02 [email protected] Reland "[skwasm] Dynamic Threading" (flutter/flutter#166454) 2025-04-02 [email protected] [dart:ui] Add `Path.addRSuperellipse` (flutter/flutter#166045) 2025-04-02 [email protected] Fix: Hero animation for page transition (flutter/flutter#164469) 2025-04-02 [email protected] Fix: DelegateTransition for cupertino sheet route (flutter/flutter#164675) 2025-04-02 [email protected] Roll Fuchsia Test Scripts from AEdsljKmUiPk92Wvv... to FZdRtNwH7jmADecj6... (flutter/flutter#166383) 2025-04-02 [email protected] [Impeller] cache for text shadows. (flutter/flutter#166228) 2025-04-02 [email protected] Convert `AppPluginLoaderPlugin` to Kotlin, and add `NativePluginLoaderReflectionBridge` to expose it in Kotlin (flutter/flutter#166027) 2025-04-02 [email protected] Roll Dart SDK from 4e1f02bc704f to b8b4076b1237 (7 revisions) (flutter/flutter#166474) 2025-04-02 [email protected] Update Roadmap (flutter/flutter#166332) 2025-04-02 [email protected] Update `CODEOWNERS` (flutter/flutter#166444) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose ...

Roll Flutter from a0b1b3253416 to 02f13c37841f (37 revisions) flutter/flutter@a0b1b32...02f13c3 2025-04-03 [email protected] Roll Packages from d10d5af to 95f8e65 (3 revisions) (flutter/flutter#166542) 2025-04-03 [email protected] Roll Skia from b67e53719e78 to 5f65df75febd (2 revisions) (flutter/flutter#166538) 2025-04-03 [email protected] Update docs to debug the Android embedder (flutter/flutter#166170) 2025-04-03 [email protected] Roll Dart SDK from 72562ca93bb5 to d174ec16c3ea (1 revision) (flutter/flutter#166525) 2025-04-03 [email protected] [macOS] Implement merged UI and platform thread (flutter/flutter#162883) 2025-04-03 [email protected] Roll Skia from f91412f5d89d to b67e53719e78 (1 revision) (flutter/flutter#166527) 2025-04-03 [email protected] Roll Packages from 0d5d57b to d10d5af (31 revisions) (flutter/flutter#166457) 2025-04-03 [email protected] Roll Skia from 2be12bc2668b to f91412f5d89d (2 revisions) (flutter/flutter#166517) 2025-04-03 [email protected] Roll Dart SDK from 2a1a13cc3a91 to 72562ca93bb5 (2 revisions) (flutter/flutter#166514) 2025-04-03 [email protected] [native_assets] Roll dependencies (flutter/flutter#166282) 2025-04-03 [email protected] Fix read only TextField focus traversal on macOS (flutter/flutter#166056) 2025-04-03 [email protected] Roll Skia from c106d7831592 to 2be12bc2668b (1 revision) (flutter/flutter#166509) 2025-04-03 [email protected] Roll Fuchsia Linux SDK from v7PGvypiiWLO8PbsZ... to vYisSsIgqw0mqFRVJ... (flutter/flutter#166508) 2025-04-03 [email protected] Roll Dart SDK from b8b4076b1237 to 2a1a13cc3a91 (1 revision) (flutter/flutter#166504) 2025-04-03 [email protected] Roll Skia from 75a0ec473181 to c106d7831592 (1 revision) (flutter/flutter#166499) 2025-04-03 [email protected] Migrate to Theme.brightnessOf method (flutter/flutter#163950) 2025-04-03 [email protected] Fix: Range slider show overlay for both thumbs on hovering one (flutter/flutter#165393) 2025-04-03 [email protected] Deprecate ExpansionTileController (flutter/flutter#166368) 2025-04-03 [email protected] Add styling parameters in `PopupMenuDivider` (flutter/flutter#164790) 2025-04-03 [email protected] Fix ISSUE_TEMPLATE Ordering: `10 < 9`, but `10 > 09` (flutter/flutter#166455) 2025-04-03 [email protected] Skip flaking scheduler test (flutter/flutter#166471) 2025-04-02 [email protected] Roll pub packages (flutter/flutter#166043) 2025-04-02 [email protected] [a11y] add SemanticsValidationResult (flutter/flutter#165935) 2025-04-02 [email protected] Remove unnecessary cache busting mechanism in hot restart (flutter/flutter#166295) 2025-04-02 [email protected] Roll Skia from 52cbb917fffd to 75a0ec473181 (21 revisions) (flutter/flutter#166484) 2025-04-02 [email protected] Started pixel aligning hairlines (flutter/flutter#166351) 2025-04-02 [email protected] Adds semantics role and adjust semantics for navigation bar (flutter/flutter#162467) 2025-04-02 [email protected] Reland "[skwasm] Dynamic Threading" (flutter/flutter#166454) 2025-04-02 [email protected] [dart:ui] Add `Path.addRSuperellipse` (flutter/flutter#166045) 2025-04-02 [email protected] Fix: Hero animation for page transition (flutter/flutter#164469) 2025-04-02 [email protected] Fix: DelegateTransition for cupertino sheet route (flutter/flutter#164675) 2025-04-02 [email protected] Roll Fuchsia Test Scripts from AEdsljKmUiPk92Wvv... to FZdRtNwH7jmADecj6... (flutter/flutter#166383) 2025-04-02 [email protected] [Impeller] cache for text shadows. (flutter/flutter#166228) 2025-04-02 [email protected] Convert `AppPluginLoaderPlugin` to Kotlin, and add `NativePluginLoaderReflectionBridge` to expose it in Kotlin (flutter/flutter#166027) 2025-04-02 [email protected] Roll Dart SDK from 4e1f02bc704f to b8b4076b1237 (7 revisions) (flutter/flutter#166474) 2025-04-02 [email protected] Update Roadmap (flutter/flutter#166332) 2025-04-02 [email protected] Update `CODEOWNERS` (flutter/flutter#166444) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose ...

…utter#162883)

github-actions bot added engine flutter/engine repository. See also e: labels. a: desktop Running on desktop platform-macos labels Feb 7, 2025

knopp force-pushed the macos_merged_ui_thread branch from 6dc1b3e to 4f80954 Compare February 7, 2025 17:58

knopp force-pushed the macos_merged_ui_thread branch 2 times, most recently from dc3f160 to f585e97 Compare February 8, 2025 15:41

knopp mentioned this pull request Feb 8, 2025

[Embedder] Implement merged platform and UI thread #162944

Merged

9 tasks

knopp force-pushed the macos_merged_ui_thread branch 3 times, most recently from eb3c3b5 to fbcd706 Compare February 11, 2025 14:23

knopp requested a review from cbracken February 11, 2025 14:29

knopp force-pushed the macos_merged_ui_thread branch from fbcd706 to 582cba0 Compare February 13, 2025 10:31

knopp changed the title ~~[macOS] Implement merged UI and platform thread~~ WIP: [macOS] Implement merged UI and platform thread Feb 25, 2025

knopp changed the title ~~WIP: [macOS] Implement merged UI and platform thread~~ [macOS] Implement merged UI and platform thread Feb 26, 2025

knopp force-pushed the macos_merged_ui_thread branch from 582cba0 to 6a3e7b0 Compare February 26, 2025 12:44

knopp force-pushed the macos_merged_ui_thread branch from 6a3e7b0 to 067d3ec Compare February 28, 2025 23:24

knopp force-pushed the macos_merged_ui_thread branch from 067d3ec to ceb43c1 Compare March 11, 2025 13:00

loic-sharma requested a review from dkwingsmt March 18, 2025 17:33

jonahwilliams self-requested a review March 26, 2025 20:25

knopp force-pushed the macos_merged_ui_thread branch from ceb43c1 to 3587460 Compare March 28, 2025 14:43

knopp mentioned this pull request Mar 31, 2025

Macos BUGFIX: change strong ref to weak ref #165177

Closed

9 tasks

cbracken approved these changes Apr 2, 2025

View reviewed changes

Allow running macOS embedder with UI and platform thread merged

3e64fdf

knopp added 3 commits April 3, 2025 11:14

Simplify vsync waiter threading

d429d4e

Include <atomic>

e9b8b4e

Nits

49d06ac

knopp force-pushed the macos_merged_ui_thread branch from 3587460 to 49d06ac Compare April 3, 2025 10:34

knopp added 4 commits April 3, 2025 12:42

Comment

61b9d66

Nit

24ce02f

Fix double release because of shallow runner description copy

2c1d25c

The descriptions share single bridge retained engine while both of them would release it.

Add missing shutDown

05aec5b

knopp added this pull request to the merge queue Apr 3, 2025

Merged via the queue into flutter:master with commit 3237222 Apr 3, 2025
172 checks passed

knopp deleted the macos_merged_ui_thread branch April 3, 2025 15:52

engine-flutter-autoroll mentioned this pull request Apr 3, 2025

Roll Flutter from a0b1b3253416 to 3237222b6211 (33 revisions) flutter/packages#8991

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Apr 3, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

f9da9ff

…utter#162883)

This comment has been minimized.

Sign in to view

engine-flutter-autoroll mentioned this pull request Apr 3, 2025

Roll Flutter from a0b1b3253416 to 269d544a9b9a (34 revisions) flutter/packages#8993

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Apr 3, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

ff7f268

…utter#162883)

engine-flutter-autoroll mentioned this pull request Apr 3, 2025

Roll Flutter from a0b1b3253416 to 73590fb0d2b7 (35 revisions) flutter/packages#8994

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Apr 3, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

1761188

…utter#162883)

engine-flutter-autoroll mentioned this pull request Apr 3, 2025

Roll Flutter from a0b1b3253416 to ceec33f16bea (36 revisions) flutter/packages#8995

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Apr 3, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

fa1ae59

…utter#162883)

engine-flutter-autoroll mentioned this pull request Apr 3, 2025

Roll Flutter from a0b1b3253416 to 02f13c37841f (37 revisions) flutter/packages#8996

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Apr 3, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

c2e19b1

…utter#162883)

munrocket mentioned this pull request Apr 14, 2025

os dialogs fail when called via dart:ffi on macOS (thread pinning Dart standalone) dart-lang/sdk#38315

Open

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request May 20, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

8e043b9

…utter#162883)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request May 20, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

5c74bbc

…utter#162883)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request May 21, 2025

3237222b6 [macOS] Implement merged UI and platform thread (flutter/fl…

10cc782

…utter#162883)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[macOS] Implement merged UI and platform thread #162883

[macOS] Implement merged UI and platform thread #162883

Uh oh!

knopp commented Feb 7, 2025 •

edited

Loading

Uh oh!

munrocket commented Feb 7, 2025

Uh oh!

knopp commented Feb 25, 2025 •

edited

Loading

Uh oh!

knopp commented Feb 26, 2025

Uh oh!

johnmccutchan commented Feb 26, 2025

Uh oh!

loic-sharma commented Mar 18, 2025

Uh oh!

jonahwilliams commented Mar 26, 2025

Uh oh!

knopp commented Mar 26, 2025

Uh oh!

cbracken left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

[macOS] Implement merged UI and platform thread #162883

[macOS] Implement merged UI and platform thread #162883

Uh oh!

Conversation

knopp commented Feb 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

munrocket commented Feb 7, 2025

Uh oh!

knopp commented Feb 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knopp commented Feb 26, 2025

Uh oh!

johnmccutchan commented Feb 26, 2025

Uh oh!

loic-sharma commented Mar 18, 2025

Uh oh!

jonahwilliams commented Mar 26, 2025

Uh oh!

knopp commented Mar 26, 2025

Uh oh!

cbracken left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

knopp commented Feb 7, 2025 •

edited

Loading

knopp commented Feb 25, 2025 •

edited

Loading