Skip to content

Merge the platform and UI threads #150525

Open

Description

@knopp

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:


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, NSApplicationDelegate methods)

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

  1. cbracken commented on Jun 19, 2024

    @cbracken
    Member
  2. jonahwilliams commented on Jun 19, 2024

    @jonahwilliams
    Contributor

    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.

  3. stuartmorgan-g commented on Jun 20, 2024

    @stuartmorgan-g
    Contributor
    • 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)

    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.

  4. mkustermann commented on Jun 20, 2024

    @mkustermann
    Member

    This means that instead of being able to call the API from Dart directly (i.e. through FFI) ... need to be used to marshal the call to platform thread

    For now we have the new runOnPlatformThread API - 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.

  5. added
    in triagePresently being triaged by the triage team
    engineflutter/engine related. See also e: labels.
    c: proposalA detailed proposal for a change to Flutter
    and removed
    in triagePresently being triaged by the triage team
    on Jun 20, 2024
  6. johnmccutchan commented on Jun 20, 2024

    @johnmccutchan
    Contributor

    We plan on tackling this in the next year.

  7. knopp commented on Jun 20, 2024

    @knopp
    MemberAuthor

    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 :)

  8. knopp commented on Jun 20, 2024

    @knopp
    MemberAuthor

    For now we have the new runOnPlatformThread API - 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).

    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.

    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.

    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).

  9. jonahwilliams commented on Jun 20, 2024

    @jonahwilliams
    Contributor

    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.

  10. justinmc commented on Jun 20, 2024

    @justinmc
    Contributor

    (@jonahwilliams in #150460): FYI @knopp I'm trying to collect sets of issues that would be improved by merged platform/ui thread

    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

  11. added
    P2Important issues not at the top of the work list
    on Jun 24, 2024
  12. 126 remaining items

  13. Flutter-DoHyunKim commented on Mar 10, 2026

    @Flutter-DoHyunKim

    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:

    1. Are there any known risks with reverting PR Remove the option to disable the merged platform/UI thread on Android and iOS #174408 and running the engine in non-merged thread mode on 3.41?
      Would this be considered a reasonable temporary workaround for production?
    2. Is there an active tracking issue or roadmap for improving PlatformView performance under merged threads?
      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.

  14. stuartmorgan-g commented on Mar 10, 2026

    @stuartmorgan-g
    Contributor

    Are there any known risks with reverting PR Remove the option to disable the merged platform/UI thread on Android and iOS #174408 and running the engine in non-merged thread mode on 3.41?

    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).

    Would this be considered a reasonable temporary workaround for production?

    The Flutter team is not going to be able to give any assurances that an untested configuration is safe.

  15. srmncnk commented on Mar 10, 2026

    @srmncnk

    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.

  16. Flutter-DoHyunKim commented on Mar 11, 2026

    @Flutter-DoHyunKim

    @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

  17. loic-sharma commented on Mar 12, 2026

    @loic-sharma
    Member

    @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.

  18. Flutter-DoHyunKim commented on Mar 13, 2026

    @Flutter-DoHyunKim

    @loic-sharma

    Filed a separate issue with a minimal reproduction sample: #183626

  19. stuartmorgan-g commented on Jul 21, 2026

    @stuartmorgan-g
    Contributor

    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.

  20. knopp commented on Jul 21, 2026

    @knopp
    MemberAuthor

    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.

    Not that I'm aware of. We should remove it, it's not really tested or supported at this point on desktop platforms.

  21. stuartmorgan-g commented on Aug 3, 2026

    @stuartmorgan-g
    Contributor

    Turns out there is already #181874 which I missed before.

  22. svprdga commented on Aug 9, 2026

    @svprdga

    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 FLTEnableMergedPlatformUIThread to false on 3.35.7
    makes it disappear completely, and setting it back to true brings 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.

  23. removed their assignment
    on Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P2Important issues not at the top of the work listc: proposalA detailed proposal for a change to Fluttercustomer: crowdAffects or could affect many people, though not necessarily a specific customer.engineflutter/engine related. See also e: labels.team-engineOwned by Engine teamtriaged-engineTriaged by Engine team

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions