Repository navigation
Description
Update 5/20/2025
As of Flutter 3.32 stable, threads are merged by default on iOS and Android with a flag available to opt-out. In Flutter 3.33 beta changes have landed so that threads will also be merged by default on Windows and macOS. Work to merge threads on Linux is WIP. We expect that the ability to opt-out of merged threads will be removed in a later release.
Known issues:
- Recover merged thread startup latency regression #163064
- [Windows] app frame rate unstable since Flutter 3.35.0 #175135
- [Windows] Windows tasks aren't processed if the Dart event loop is never drained #173843
Currently Flutter has a separate UI thread (that runs dart code) and platform thread. I think the main purpose of the UI thread is to prevent blocking the platform thread, but the actual benefit of this eludes me. In most applications the platform thread stays idle apart from tiny amount of work during event processing and compositing. The work is moved to UI thread, but if the work doesn't complete in time, it causes jank just like it would when blocking the platform thread.
The drawbacks however seem pretty clear. The vast majority of platform APIs need to be accessed on platform thread. This means that instead of being able to call the API from Dart directly (i.e. through FFI), platform channels or something similar need to be used to marshal the call to platform thread. This adds some friction and asynchronous behavior to what could otherwise be simple synchronous call.
Situation gets even more complicated the other way around - when needed to call into Dart from platform thread. Platform callbacks are often synchronous (i.e. accessibility, event handling, IME, application delegate, and many more). Traditionally the approach here was to push enough state to platform thread to be able to provide synchronous response, but that's not always feasible or reliable enough. Eventual consistency fails in some cases, for example we're getting bitten by issue where IME on iOS generate fast sequence of events and then reads the text before the events have been processed by UI thread and sent back to platform thread.
On iOS for keyboard handling we need synchronous response, and to get it we keep pumping the CFRunLoop inside the event handler until we get it. This is a feasible approach for the problems above, but it's a tricky solution because of added reentrancy (the system code invoking the handler may not expect the runloop to be running while waiting for response) and edge cases (what if the isolate gets terminated while waiting for response?). With enough effort these are fixable (i.e. platform channels can have custom run loop mode (iOS, macOS) or custom execution so that it doesn't interfere with system run loop), but still, we're solving problem that probably shouldn't have existed in the first place.
Non-exhaustive list of issues that would improve with merged UI and Platform thread
- Calling platform APIs directly and synchronously from Dart without needing platform channels or platform isolate
- Ability to get synchronous response from Dart code for platform callbacks, which would help with
- accessibility
- event handling (keyboard events, drag & drop)
- IME (cursor position query, no need to replicate composited text, could properly support custom bindings in
DefaultKeyBinding.dict, ...) - Ability to synchronously respond to platform callbacks (i.e. window draggable area,
NSApplicationDelegatemethods)
Possible drawbacks
- Non trivial change, would likely impact ecosystem (some plugins may need to get adapted, though most of plugins might just work if we keep platform channels working asynchronously)
- Possible performance regression with thread merging and shared raster/platform thread (linux). I think the proper solution here is to get rid of thread merging (adopt solution similar to what macOS is doing on all platforms) and implement separate raster thread in Linux embedder.
Activity
cbracken commentedon Jun 19, 2024
/cc @chinmaygarde @johnmccutchan @jonahwilliams
jonahwilliams commentedon Jun 19, 2024
We'd almost certainly need a way to do this gradually and per platform. That would probably limit us from improving any APIs until after the transition had been completed.
The biggest question for me is what we can do about platform views. On iOS, I believe we can do some trickery to separate platform view updates from rasterization.
But Android is a bit of a mess. With TLHC we can manipulate platform views on a different thread, but with HC we have to manipulate them on the same thread. Because of the threading restrictions on older android devices + OpenGLES I dont know that we have a good thread merging solution that works on all android versions.
stuartmorgan-g commentedon Jun 20, 2024
I would expect essentially no impact on plugins using platform channels as long as we keep the default async, the real potential problem would be with packages using FFI, where the threading of the code being called by FFI would be changed, without us being able to do anything about it centrally.
mkustermann commentedon Jun 20, 2024
For now we have the new
runOnPlatformThreadAPI - which runs dart code in a stateful isolate on the platform thread. One can synchronously call into platform APIs and (AFAIK) platform APIs should be able to call synchronously back into Dart (via callbacks created using e.g.NativeCallable.isolateLocal).That allows moving arbitrary dart logic to the platform thread. Though if the logic has to influence the UI then it has to interact asynchronously with the UI isolate. Only merging the threads will solve this. But even if threads were merged, a call from the platform thread into Dart doesn't directly draw a new frame and therefore only affect UI asynchronously - as flutter engine determines when it's time to draw the next frame.
johnmccutchan commentedon Jun 20, 2024
We plan on tackling this in the next year.
knopp commentedon Jun 20, 2024
Maybe the thread merging could be split to a separate issue? As for the HC, wouldn't recording the mutations during preroll and then applying atomically them from platform thread once everything is rendered (similar to EmbedderExternalViewEmbedder) be an option? I'm not that familiar with how this is handled on Android so perhaps I'm missing something. I can see that @johnmccutchan has a talk scheduled about Android platform views at FlutterCon, hopefully I won't miss it :)
knopp commentedon Jun 20, 2024
Indeed. I mentioned platform isolate in the original comment, but I do think that this is trying to solve a problem that shouldn't exist in the first place.
I don't think that's a problem (or even expected behavior). Not all callbacks from platform should trigger a frame (i.e. IME update, query draggable areas, etc).
jonahwilliams commentedon Jun 20, 2024
Another example of a problematic API is semantics. The platform thread will query the flutter semantics tree at a particular rate, but since we don't know what that rate is we need to produce a full semantics tree on every frame.
justinmc commentedon Jun 20, 2024
Possibly the handling of large amounts of text in text fields. Currently the entire contents of the field get synced between the framework and engine on each keystroke (though this could possibly be mitigated using DeltaTextInputClient). #90063, #96173
126 remaining items
Flutter-DoHyunKim commentedon Mar 10, 2026
Hi team,
We're planning to upgrade our Flutter add-to-app module from 3.24 → 3.41 in order to pick up the WebView gesture fix (PR #179908).
However, As previously discussed, we observed noticeable jank when scrolling PlatformView-heavy screens with merged Platform/UI threads enabled.
Since the opt-out flag was removed in PR #174408, we experimented with reverting that PR locally on top of the 3.41 stable engine to temporarily restore the non-merged thread behavior.
So far we were able to build and run the local engine successfully, and basic testing did not reveal any obvious issues.
The changes in that PR also seem relatively self-contained, but before considering this approach for production we wanted to confirm with the team.
Our intention would be to use this only as a temporary workaround, and switch back to the stable engine once PlatformView performance under merged threads improves
(for example when HCPP lands or other related optimizations are available).
A couple of questions:
Would this be considered a reasonable temporary workaround for production?
Knowing roughly when this might improve would help us plan when we can remove the custom engine.
Thanks again for all the work on this.
Happy to provide more details or test builds if that would be helpful.
stuartmorgan-g commentedon Mar 10, 2026
If you use any package that uses FFI and is targeting 3.41 in order to be able to rely on being on the main thread, your application will have undefined behavior. Any package calling most iOS system APIs via FFI, for example, will likely throw exceptions and/or crash. So at a minimum you would need to audit the source of every package you use, and do so again any time you updated any dependency (including transitive dependencies).
The Flutter team is not going to be able to give any assurances that an untested configuration is safe.
srmncnk commentedon Mar 10, 2026
Honestly one could (and should) also argue this the other way around.
Given the percentage of plugins that use FFI versus those that use MethodChannel, the risk profile is very different in practice.
Flutter-DoHyunKim commentedon Mar 11, 2026
@stuartmorgan-g
Thanks for the detailed explanation. We understand the risks you mentioned around FFI packages that may rely on the merged-thread behavior in newer Flutter versions.
To reduce that risk, our current plan is to upgrade from 3.24 while keeping dependency updates minimal and avoiding packages that assume merged-thread behavior. In practice, we expect most of our dependencies to stay around the ~3.38 target range for now.
For the time being, we are considering a temporary custom engine workaround by reverting PR #174408 so that we can continue running with the non-merged thread configuration while evaluating newer Flutter versions.
While investigating the jank we observed, I did a bit of root cause analysis around PlatformView(TLHC) behavior under merged threads. During scrolling, setOffset appears to be called every frame for each visible PlatformView, which seems to trigger setLayoutParams() → requestLayout() → draw() repeatedly. With merged threads, this work appears to run serially on the main thread, which may explain the visible jank when several PlatformViews are on screen.
I also experimented with a small engine-side modification that avoids calling setLayoutParams() on every scroll-driven offset update and instead updates the wrapper position directly via layout(). This avoids the expensive requestLayout() path during scrolling, which in our testing significantly reduced the repeated layout/draw work we were seeing. In our test case, this removed the scrolling jank.
If this seems worth exploring, I'm happy to open a separate issue with more detailed analysis and the patch.
cc. @knopp @mit-mit @jtmcdole
loic-sharma commentedon Mar 12, 2026
@Flutter-DoHyunKim Yes please file a separate issue for the Android platform view jank issue. I'd make sure to include a minimal Flutter app that reproduces the jank.
Flutter-DoHyunKim commentedon Mar 13, 2026
@loic-sharma
Filed a separate issue with a minimal reproduction sample: #183626
stuartmorgan-g commentedon Jul 21, 2026
Is there an issue tracking removing the option on macOS? I have some plugin work that's blocked on being able to rely on merged threads for both iOS and macOS, so it would be helpful to be able to track the later.
knopp commentedon Jul 21, 2026
Not that I'm aware of. We should remove it, it's not really tested or supported at this point on desktop platforms.
stuartmorgan-g commentedon Aug 3, 2026
Turns out there is already #181874 which I missed before.
svprdga commentedon Aug 9, 2026
The thread merge caused a serious performance problem with platform views on iOS. I detected
it in my apps that use AdMob banners, but it's reproducible with any platform view, even one
that sits outside the scrollable and never moves still makes an unrelated ListView janky.
I confirmed it's the merge: setting
FLTEnableMergedPlatformUIThreadtofalseon 3.35.7makes it disappear completely, and setting it back to
truebrings it back.I've written a fully detailed report of the problem and how to reproduce it here.
The bad part is that now that you can't opt out of the thread merge anymore, there's no way
to mitigate this.
Remove the option to disable the merged platform/UI thread on Android…
[iOS] Supported rendering platform views without merging the raster t…
[engine] support combined UI/Platform thread for iOS/Android. (flutte…
[engine] make UI thread the platform thread for Android. Still allows…