[macOS] Implement merged UI and platform thread (#162883)

Original issue: flutter/flutter#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

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

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

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: knopp

engine/src/flutter/ci/licenses_golden/licenses_flutter

@@ -52934,6 +52934,9 @@ ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterPla
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatformViewControllerTest.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.mm + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizer.h + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizer.mm + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizerTest.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurface.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurface.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurfaceManager.h + ../../../flutter/LICENSE
@@ -52947,9 +52950,6 @@ ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTex
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextInputSemanticsObjectTest.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextureRegistrar.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextureRegistrar.mm + ../../../flutter/LICENSE
-ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.h + ../../../flutter/LICENSE
-ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.mm + ../../../flutter/LICENSE
-ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizerTest.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTimeConverter.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTimeConverter.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterUmbrellaImportTests.m + ../../../flutter/LICENSE
@@ -55943,6 +55943,11 @@ FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatf
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatformViewControllerTest.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.mm
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizer.h
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizer.mm
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterResizeSynchronizerTest.mm
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRunLoop.h
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterRunLoop.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurface.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurface.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterSurfaceManager.h
@@ -55956,9 +55961,6 @@ FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextI
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextInputSemanticsObjectTest.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextureRegistrar.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTextureRegistrar.mm
-FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.h
-FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizer.mm
-FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterThreadSynchronizerTest.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTimeConverter.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterTimeConverter.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterUmbrellaImportTests.m

engine/src/flutter/shell/platform/darwin/macos/BUILD.gn

@@ -94,6 +94,10 @@ source_set("flutter_framework_source") {
     "framework/Source/FlutterPlatformViewController.mm",
     "framework/Source/FlutterRenderer.h",
     "framework/Source/FlutterRenderer.mm",
+    "framework/Source/FlutterResizeSynchronizer.h",
+    "framework/Source/FlutterResizeSynchronizer.mm",
+    "framework/Source/FlutterRunLoop.h",
+    "framework/Source/FlutterRunLoop.mm",
     "framework/Source/FlutterSurface.h",
     "framework/Source/FlutterSurface.mm",
     "framework/Source/FlutterSurfaceManager.h",
@@ -104,8 +108,6 @@ source_set("flutter_framework_source") {
     "framework/Source/FlutterTextInputSemanticsObject.mm",
     "framework/Source/FlutterTextureRegistrar.h",
     "framework/Source/FlutterTextureRegistrar.mm",
-    "framework/Source/FlutterThreadSynchronizer.h",
-    "framework/Source/FlutterThreadSynchronizer.mm",
     "framework/Source/FlutterTimeConverter.h",
     "framework/Source/FlutterTimeConverter.mm",
     "framework/Source/FlutterVSyncWaiter.h",
@@ -194,10 +196,10 @@ executable("flutter_desktop_darwin_unittests") {
     "framework/Source/FlutterMutatorViewTest.mm",
     "framework/Source/FlutterPlatformNodeDelegateMacTest.mm",
     "framework/Source/FlutterPlatformViewControllerTest.mm",
+    "framework/Source/FlutterResizeSynchronizerTest.mm",
     "framework/Source/FlutterSurfaceManagerTest.mm",
     "framework/Source/FlutterTextInputPluginTest.mm",
     "framework/Source/FlutterTextInputSemanticsObjectTest.mm",
-    "framework/Source/FlutterThreadSynchronizerTest.mm",
     "framework/Source/FlutterVSyncWaiterTest.mm",
     "framework/Source/FlutterViewControllerTest.mm",
     "framework/Source/FlutterViewControllerTestUtils.h",

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

@@ -4,6 +4,7 @@
 #import <AppKit/AppKit.h>
 
 @protocol FlutterDisplayLinkDelegate <NSObject>
+/// This will be called on main thread.
 - (void)onDisplayLink:(CFTimeInterval)timestamp targetTimestamp:(CFTimeInterval)targetTimestamp;
 @end
 
@@ -12,27 +13,28 @@
 /// Internally FlutterDisplayLink will use at most one CVDisplayLink per
 /// screen shared for all views belonging to that screen. This is necessary
 /// because each CVDisplayLink comes with its own thread.
+///
+/// All methods must be called on main thread.
 @interface FlutterDisplayLink : NSObject
 
 /// Creates new instance tied to provided NSView. FlutterDisplayLink
 /// will track view display changes transparently to synchronize
 /// update with display refresh.
-/// This function must be called on the main thread.
 + (instancetype)displayLinkWithView:(NSView*)view;
 
-/// Delegate must be set on main thread. Delegate method will be called on
-/// on display link thread.
+/// Delegate must be set on main thread.
+/// Delegate method will be also called on main thread.
 @property(nonatomic, weak) id<FlutterDisplayLinkDelegate> delegate;
 
-/// Pauses and resumes the display link. May be called from any thread.
+/// Pauses and resumes the display link.
 @property(readwrite) BOOL paused;
 
 /// Returns the nominal refresh period of the display to which the view
 /// currently belongs (in seconds). If view does not belong to any display,
-/// returns 0. Can be called from any thread.
+/// returns 0.
 @property(readonly) CFTimeInterval nominalOutputRefreshPeriod;
 
-/// Invalidates the display link. Must be called on the main thread.
+/// Invalidates the display link.
 - (void)invalidate;
 
 @end