[iOS] Add FlutterTracing to support tracing from Swift#185918
Merged
Conversation
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a unified FlutterTracing utility for Darwin platforms, wrapping FML tracing macros for use in both Objective-C and Swift. The changes include the creation of the FlutterTracing class, updates to the GN build configuration, and the addition of Swift unit tests. The review feedback suggests enhancing the header with nullability annotations for better Swift interoperability and adding defensive checks in the implementation to prevent crashes when passing null strings to the underlying C++ tracing macros.
hellohuanlin
reviewed
May 4, 2026
|
|
||
| @implementation FlutterTracing | ||
|
|
||
| + (void)traceScope:(NSString*)name work:(void(NS_NOESCAPE ^)(void))work { |
Contributor
There was a problem hiding this comment.
I wonder if we can create a similar RAII style API, which doesn't involve a closure like the original C++ API?
Member
Author
There was a problem hiding this comment.
My thinking on this was that we could create a @Trace("scope") annotation but we need the scope first, and we'd need it for small blocks inside a method regardless. The end result would look like:
@Trace(scope: "SomeScope")
func foo() {
...
}
An alternative option would be to create a start/end calls and do something like:
let traceScope = Tracing.beginScope("SomeScope")
defer { traceScope.end() }
RAII in itself isn't really possible in Swift because dealloc isn't guaranteed to wait until the end of the block; it can be super aggressive with cleanup.
While the block/closure approach feels a bit Swiftier, I'm kind of partial to the general explicitness of the .traceEvent() / defer .end() approach too, even if it makes it possible for people to forget to end the block.
Supporting a @Trace macro is definitely doable but it would require me to do some work in the build toolchain to support using them. That does seem like something useful to support, but
Member
Author
There was a problem hiding this comment.
Re your comment below on the synchronous block-based API being suprising, digging around, Swift has a bunch of synchonous block-based API:
- withUnsafePointer(to:_:)
- withExtendedLifetime(::)
- withTaskGroup(of:returning:body:)
- etc.
all of these are synchronous; however, they also all seem to start with with. Maybe Tracing.withScope("foo") { ... }? That keeps it aligned with existing synchronous Swift API, but gives us the ability to do tracing ad-hoc and never need to remember to fire an end event.
re: the issue that tracing a whole method is common, but with this API we'd be stuck with:
func foo() {
Tracing.withScope("Foo") {
// ... annoyingly double-indented ...
}
}I think it probably makes sense to add a begin/end API like:
func foo() {
let traceScope = Tracing.beginScope("Foo")
defer { traceScope.end() }
// ... method body goes here ...
}That still gives us the nice advantage of being able to do:
func foo() {
// ... bunch of setup code ...
Tracing.withScope("Foo") {
// ... some traced section ...
}
// ... bunch more code ...
}Eventually, once I get support for macros landed, we'll be able to just do:
@Trace(scope: "Foo")
func foo() {
// ... method body ...
}Thoughts?
Contributor
There was a problem hiding this comment.
Sounds good
all of these are synchronous; however, they also all seem to start with with.
interesting! I didn't realize this.
This extracts an Obj-C `FlutterTracing` wrapper around FML C++ tracing macros (`TRACE_EVENT`), which will enable code written in Swift to emit timeline trace events, which was not previously possible since C++ macros are inacessible to Swift. Issue: flutter#112232
hellohuanlin
previously approved these changes
May 6, 2026
hellohuanlin
approved these changes
May 6, 2026
This was referenced May 6, 2026
pull Bot
pushed a commit
to Little-Star888/flutter
that referenced
this pull request
May 6, 2026
…ter#186120) Allows Swift extension symbols defined in internal modules on Objective-C classes to pass the symbol verification. Swift extensions on Objective-C classes (which reside in Swift's 'So' namespace) mangle differently than standard Swift symbols. Instead of starting with the module name (e.g., `_$s25InternalFlutterSwift...`), they start with the extended type (e.g., `_$sSo14FlutterTracingC...`) and have the module name embedded inside. Furthermore, the Swift compiler may compress repeated tokens in the module name (e.g., substituting 'Flutter' with 'A' in `InternalFlutterSwiftCommon` if 'Flutter' was already used in the extended type name), resulting in `InternalA11Swift` in the mangled symbol. This is pretty common in extensions since we prefix all our Obj-C types with "Flutter". This updates this code to allow the Swift extension added in this patch to pass: flutter#185918 From that failure: ```sh xcrun swift-demangle -expand '_$sSo14FlutterTracingC08InternalA11SwiftCommonE10beginScopeyAC05TraceG0CSSFZ' ``` We see: ``` Demangling for _$sSo14FlutterTracingC08InternalA11SwiftCommonE10beginScopeyAC05TraceG0CSSFZ kind=Global kind=Static kind=Function kind=Extension kind=Module, text="InternalFlutterSwiftCommon" kind=Class kind=Module, text="__C" kind=Identifier, text="FlutterTracing" kind=Identifier, text="beginScope" kind=LabelList kind=Type kind=FunctionType kind=ArgumentTuple kind=Type kind=Structure kind=Module, text="Swift" kind=Identifier, text="String" kind=ReturnType kind=Type kind=Class kind=Module, text="InternalFlutterSwiftCommon" kind=Identifier, text="TraceScope" _$sSo14FlutterTracingC08InternalA11SwiftCommonE10beginScopeyAC05TraceG0CSSFZ ---> static (extension in InternalFlutterSwiftCommon):__C.FlutterTracing.beginScope(Swift.String) -> InternalFlutterSwiftCommon.TraceScope ``` Swift has a stable ABI so these aren't at risk of changing, so this updates the regexes themselves to handle Swift extensions. No tests because this script is itself a test. Fixes: flutter#186119 ## Pre-launch Checklist - [X] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [X] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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]. 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](https://developers.google.com/gemini-code-assist/docs/review-github-code). 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. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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
This was referenced May 6, 2026
10 tasks
cbracken
added a commit
to cbracken/flutter
that referenced
this pull request
May 7, 2026
…stamps Migrates `FlutterVSyncClient` from a hybrid C++/Obj-C implementation to a pure Objective-C implementation by removing C++ types from its interface and implementation. Further, in flutter#185918 the timestamps used in `FlutterTracing` were updated from `int64_t` to `NSTimeInterval` in response to code review, but the call site was (incorrectly) not updated. This fixes that. 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: https://github.com/flutter/flutter/blob/master/engine/src/flutter/shell/platform/darwin/ios/framework/Source/VSyncClientTest.swift
cbracken
added a commit
to cbracken/flutter
that referenced
this pull request
May 7, 2026
…stamps Migrates `FlutterVSyncClient` from a hybrid C++/Obj-C implementation to a pure Objective-C implementation by removing C++ types from its interface and implementation. Further, in flutter#185918 the timestamps used in `FlutterTracing` were updated from `int64_t` to `NSTimeInterval` in response to code review, but the call site was (incorrectly) not updated. This fixes that. 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: https://github.com/flutter/flutter/blob/master/engine/src/flutter/shell/platform/darwin/ios/framework/Source/VSyncClientTest.swift
10 tasks
cbracken
added a commit
to cbracken/flutter
that referenced
this pull request
May 7, 2026
…stamps Migrates `FlutterVSyncClient` from a hybrid C++/Obj-C implementation to a pure Objective-C implementation by removing C++ types from its interface and implementation. Further, in flutter#185918 the timestamps used in `FlutterTracing` were updated from `int64_t` to `NSTimeInterval` in response to code review, but the call site was (incorrectly) not updated. This fixes that. 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: https://github.com/flutter/flutter/blob/master/engine/src/flutter/shell/platform/darwin/ios/framework/Source/VSyncClientTest.swift
This was referenced May 7, 2026
pull Bot
pushed a commit
to Superoldman96/flutter
that referenced
this pull request
May 7, 2026
…lutter#186190) Fixes an issue in `FlutterVSyncClient` where platform vsync timestamps were reported incorrectly to the timeline. In flutter#185918 I introduced the Obj-C tracing API, which originally used microseconds as an int64_t. During review this was updated to use NSTimeInterval to be more idiomatic and use a clear type in place of int64_t for the timestamp. The tests were updated but the callsite was not. Authoring a test that would differentiate microseconds from fractional seconds (NSTimeInterval) is infeasible in the current state without significant refactoring, however, that refactoring is coming in followup patch: flutter#186166 That patch could be landed as an alternative as it also contains the fix. Issue: flutter#112232 <!-- Thanks for filing a pull request! Reviewers are typically assigned within a week of filing a request. To learn more about code review, see our documentation on Tree Hygiene: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md --> ## Pre-launch Checklist - [X] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [X] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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]. 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](https://developers.google.com/gemini-code-assist/docs/review-github-code). 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. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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
This was referenced May 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This extracts an Obj-C
FlutterTracingwrapper around FML C++ tracing macros (TRACE_EVENT), as well as Swift convenience APIs to enable code written in Swift in the iOS/macOS embedders to emit timeline trace events, which was not previously possible since C++ macros are inacessible to Swift.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-assistbot 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.