Skip to content

Commit cc0c10e

Browse files
authored
iOS: Ensure engine is run on the main thread (flutter#191626)
Previously, running a `FlutterEngine` from a background queue silently gave us an engine whose platform thread was not the main thread. The first symptom an app sees is an assertion deep inside `DisplayLinkManager.shared`, which is accurate but confusing and looks like a bug rather than an intentional precondition. `MakeThreadHost` adopts the calling thread as the engine's platform/UI thread. That thread is required to be the main thread for several reasons: * it reads UIKit state and runs every plugin and platform channel callback * nothing else pumps its run loop We now assert this via `FML_CHECK` in: * `createShell:libraryURI:initialRoute:`: covers the `run*` methods and `FlutterViewController`'s implicit engine * `spawnWithEntrypoint:libraryURI:initialRoute:entrypointArgs:`: covers the second and later engines in a `FlutterEngineGroup`. A spawned engine inherits its spawner's task runners rather than adopting the calling thread, so the check in `createShell` constrains every engine in a group. This also adds an `FML_DCHECK` during engine construction since it reads `UIApplication` lifecycle state and registers UIKit observers. This also annotates the Swift-visible entry points `NS_SWIFT_UI_ACTOR` so that Swift callers get a compile-time error rather than a runtime abort. `FlutterViewController` doesn't need an annotation since, like all view controllers, it already inherits main actor isolation from `UIViewController`. Issue: flutter#190909 Related: flutter#190725 Related: flutter#165904 No test changes, since these are assertions and unlike GoogleTest, XCUITest and Swift Testing tests have no death-test. This doesn't add any additional runtime aborts since `DisplayLinkManager.shared` already does this; it just pushes them up to where they're actually actionable by the user, and provides better error messages. <!-- 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
1 parent 8bae903 commit cc0c10e

7 files changed

Lines changed: 88 additions & 22 deletions

File tree

‎engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,11 @@ extern NSString* const FlutterDefaultInitialRoute;
5656
* A newly initialized FlutterEngine will not actually run a Dart Isolate until
5757
* either `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI` is invoked.
5858
* One of these methods must be invoked before calling `-setViewController:`.
59+
*
60+
* `FlutterEngine` instances must be created and run on the main thread. The engine adopts the
61+
* thread that runs it as its platform thread, which is also used for executing application UI code
62+
* written in Dart. Running an engine on a background queue is not supported, apps and app
63+
* extensions must dispatch to the main queue.
5964
*/
6065
FLUTTER_DARWIN_EXPORT
6166
@interface FlutterEngine : NSObject <FlutterPluginRegistry>
@@ -76,7 +81,7 @@ FLUTTER_DARWIN_EXPORT
7681
* This means that the engine will continue to run regardless of whether a `FlutterViewController`
7782
* is attached to it or not, until `-destroyContext:` is called or the process finishes.
7883
*/
79-
- (instancetype)init;
84+
- (instancetype)init NS_SWIFT_UI_ACTOR;
8085

8186
/**
8287
* Initialize this FlutterEngine.
@@ -95,7 +100,7 @@ FLUTTER_DARWIN_EXPORT
95100
* be unique across FlutterEngine instances, and is used in instrumentation to label
96101
* the threads used by this FlutterEngine.
97102
*/
98-
- (instancetype)initWithName:(NSString*)labelPrefix;
103+
- (instancetype)initWithName:(NSString*)labelPrefix NS_SWIFT_UI_ACTOR;
99104

100105
/**
101106
* Initialize this FlutterEngine with a `FlutterDartProject`.
@@ -116,7 +121,8 @@ FLUTTER_DARWIN_EXPORT
116121
* the threads used by this FlutterEngine.
117122
* @param project The `FlutterDartProject` to run.
118123
*/
119-
- (instancetype)initWithName:(NSString*)labelPrefix project:(nullable FlutterDartProject*)project;
124+
- (instancetype)initWithName:(NSString*)labelPrefix
125+
project:(nullable FlutterDartProject*)project NS_SWIFT_UI_ACTOR;
120126

121127
/**
122128
* Initialize this FlutterEngine with a `FlutterDartProject`.
@@ -137,7 +143,7 @@ FLUTTER_DARWIN_EXPORT
137143
*/
138144
- (instancetype)initWithName:(NSString*)labelPrefix
139145
project:(nullable FlutterDartProject*)project
140-
allowHeadlessExecution:(BOOL)allowHeadlessExecution;
146+
allowHeadlessExecution:(BOOL)allowHeadlessExecution NS_SWIFT_UI_ACTOR;
141147

142148
/**
143149
* Initialize this FlutterEngine with a `FlutterDartProject`.
@@ -161,7 +167,7 @@ FLUTTER_DARWIN_EXPORT
161167
- (instancetype)initWithName:(NSString*)labelPrefix
162168
project:(nullable FlutterDartProject*)project
163169
allowHeadlessExecution:(BOOL)allowHeadlessExecution
164-
restorationEnabled:(BOOL)restorationEnabled NS_DESIGNATED_INITIALIZER;
170+
restorationEnabled:(BOOL)restorationEnabled NS_DESIGNATED_INITIALIZER NS_SWIFT_UI_ACTOR;
165171

166172
/**
167173
* Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
@@ -171,9 +177,11 @@ FLUTTER_DARWIN_EXPORT
171177
* The first call to this method will create a new Isolate. Subsequent calls will return
172178
* immediately and have no effect.
173179
*
180+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
181+
*
174182
* @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
175183
*/
176-
- (BOOL)run;
184+
- (BOOL)run NS_SWIFT_UI_ACTOR;
177185

178186
/**
179187
* Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
@@ -182,14 +190,16 @@ FLUTTER_DARWIN_EXPORT
182190
* The first call to this method will create a new Isolate. Subsequent calls will return
183191
* immediately and have no effect.
184192
*
193+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
194+
*
185195
* @param entrypoint The name of a top-level function from the same Dart
186196
* library that contains the app's main() function. If this is FlutterDefaultDartEntrypoint (or
187197
* nil) it will default to `main()`. If it is not the app's main() function, that function must
188198
* be decorated with `@pragma(vm:entry-point)` to ensure the method is not tree-shaken by the Dart
189199
* compiler.
190200
* @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
191201
*/
192-
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint;
202+
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint NS_SWIFT_UI_ACTOR;
193203

194204
/**
195205
* Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
@@ -198,6 +208,8 @@ FLUTTER_DARWIN_EXPORT
198208
* The first call to this method will create a new Isolate. Subsequent calls will return
199209
* immediately and have no effect.
200210
*
211+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
212+
*
201213
* @param entrypoint The name of a top-level function from the same Dart
202214
* library that contains the app's main() function. If this is FlutterDefaultDartEntrypoint (or
203215
* nil), it will default to `main()`. If it is not the app's main() function, that function must
@@ -208,7 +220,7 @@ FLUTTER_DARWIN_EXPORT
208220
* @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
209221
*/
210222
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
211-
initialRoute:(nullable NSString*)initialRoute;
223+
initialRoute:(nullable NSString*)initialRoute NS_SWIFT_UI_ACTOR;
212224

213225
/**
214226
* Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
@@ -217,6 +229,8 @@ FLUTTER_DARWIN_EXPORT
217229
* The first call to this method will create a new Isolate. Subsequent calls will return
218230
* immediately and have no effect.
219231
*
232+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
233+
*
220234
* @param entrypoint The name of a top-level function from a Dart library. If this is
221235
* FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
222236
* main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
@@ -226,7 +240,8 @@ FLUTTER_DARWIN_EXPORT
226240
* the same library as the `main()` function in the Dart program.
227241
* @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
228242
*/
229-
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint libraryURI:(nullable NSString*)uri;
243+
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
244+
libraryURI:(nullable NSString*)uri NS_SWIFT_UI_ACTOR;
230245

231246
/**
232247
* Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
@@ -235,6 +250,8 @@ FLUTTER_DARWIN_EXPORT
235250
* The first call to this method will create a new Isolate. Subsequent calls will return
236251
* immediately and have no effect.
237252
*
253+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
254+
*
238255
* @param entrypoint The name of a top-level function from a Dart library. If this is
239256
* FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
240257
* main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
@@ -248,7 +265,7 @@ FLUTTER_DARWIN_EXPORT
248265
*/
249266
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
250267
libraryURI:(nullable NSString*)libraryURI
251-
initialRoute:(nullable NSString*)initialRoute;
268+
initialRoute:(nullable NSString*)initialRoute NS_SWIFT_UI_ACTOR;
252269

253270
/**
254271
* Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
@@ -257,6 +274,8 @@ FLUTTER_DARWIN_EXPORT
257274
* The first call to this method will create a new Isolate. Subsequent calls will return
258275
* immediately and have no effect.
259276
*
277+
* This method must be called on the main thread. See the `FlutterEngine` class documentation.
278+
*
260279
* @param entrypoint The name of a top-level function from a Dart library. If this is
261280
* FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
262281
* main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
@@ -272,7 +291,7 @@ FLUTTER_DARWIN_EXPORT
272291
- (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
273292
libraryURI:(nullable NSString*)libraryURI
274293
initialRoute:(nullable NSString*)initialRoute
275-
entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs;
294+
entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs NS_SWIFT_UI_ACTOR;
276295

277296
/**
278297
* Destroy running context for an engine.

‎engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngineGroup.h‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ FLUTTER_DARWIN_EXPORT
4949
* Deleting a FlutterEngineGroup doesn't invalidate existing FlutterEngines, but
5050
* it eliminates the possibility to create more FlutterEngines in that group.
5151
*
52+
* Engines in a group share task runners, including the platform thread of the first engine
53+
* created in the group. All `-makeEngine*` methods must therefore be called on the main thread.
54+
* See `FlutterEngine` class documentation.
55+
*
5256
* @warning This class is a work-in-progress and may change.
5357
* @see https://github.com/flutter/flutter/issues/72009
5458
*/
@@ -70,6 +74,8 @@ FLUTTER_DARWIN_EXPORT
7074
/**
7175
* Creates a running `FlutterEngine` that shares components with this group.
7276
*
77+
* This method must be called on the main thread.
78+
*
7379
* @param entrypoint The name of a top-level function from a Dart library. If this is
7480
* FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
7581
* main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
@@ -80,11 +86,13 @@ FLUTTER_DARWIN_EXPORT
8086
* @see FlutterEngineGroup
8187
*/
8288
- (FlutterEngine*)makeEngineWithEntrypoint:(nullable NSString*)entrypoint
83-
libraryURI:(nullable NSString*)libraryURI;
89+
libraryURI:(nullable NSString*)libraryURI NS_SWIFT_UI_ACTOR;
8490

8591
/**
8692
* Creates a running `FlutterEngine` that shares components with this group.
8793
*
94+
* This method must be called on the main thread.
95+
*
8896
* @param entrypoint The name of a top-level function from a Dart library. If this is
8997
* FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
9098
* main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
@@ -98,16 +106,19 @@ FLUTTER_DARWIN_EXPORT
98106
*/
99107
- (FlutterEngine*)makeEngineWithEntrypoint:(nullable NSString*)entrypoint
100108
libraryURI:(nullable NSString*)libraryURI
101-
initialRoute:(nullable NSString*)initialRoute;
109+
initialRoute:(nullable NSString*)initialRoute NS_SWIFT_UI_ACTOR;
102110

103111
/**
104112
* Creates a running `FlutterEngine` that shares components with this group.
105113
*
114+
* This method must be called on the main thread.
115+
*
106116
* @param options Options that control how a FlutterEngine should be created.
107117
*
108118
* @see FlutterEngineGroupOptions
109119
*/
110-
- (FlutterEngine*)makeEngineWithOptions:(nullable FlutterEngineGroupOptions*)options;
120+
- (FlutterEngine*)makeEngineWithOptions:(nullable FlutterEngineGroupOptions*)options
121+
NS_SWIFT_UI_ACTOR;
111122
@end
112123

113124
NS_ASSUME_NONNULL_END

‎engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ typedef void (^FlutterHeadlessDartRunnerCallback)(BOOL success);
2626
* and no native drawing surface. It is appropriate for use in running Dart
2727
* code e.g. in the background from a plugin.
2828
*
29+
* Like any `FlutterEngine`, this class must be created and run on the main thread.
30+
* See `FlutterEngine` class documentation.
31+
*
2932
* Most callers should prefer using `FlutterEngine` directly; this interface exists
3033
* for legacy support.
3134
*/
@@ -46,7 +49,8 @@ FLUTTER_DEPRECATED("FlutterEngine should be used rather than FlutterHeadlessDart
4649
* be unique across FlutterEngine instances
4750
* @param projectOrNil The `FlutterDartProject` to run.
4851
*/
49-
- (instancetype)initWithName:(NSString*)labelPrefix project:(FlutterDartProject*)projectOrNil;
52+
- (instancetype)initWithName:(NSString*)labelPrefix
53+
project:(FlutterDartProject*)projectOrNil NS_SWIFT_UI_ACTOR;
5054

5155
/**
5256
* Initialize this FlutterHeadlessDartRunner with a `FlutterDartProject`.
@@ -64,7 +68,7 @@ FLUTTER_DEPRECATED("FlutterEngine should be used rather than FlutterHeadlessDart
6468
*/
6569
- (instancetype)initWithName:(NSString*)labelPrefix
6670
project:(FlutterDartProject*)projectOrNil
67-
allowHeadlessExecution:(BOOL)allowHeadlessExecution;
71+
allowHeadlessExecution:(BOOL)allowHeadlessExecution NS_SWIFT_UI_ACTOR;
6872

6973
/**
7074
* Initialize this FlutterHeadlessDartRunner with a `FlutterDartProject`.
@@ -84,13 +88,13 @@ FLUTTER_DEPRECATED("FlutterEngine should be used rather than FlutterHeadlessDart
8488
- (instancetype)initWithName:(NSString*)labelPrefix
8589
project:(FlutterDartProject*)projectOrNil
8690
allowHeadlessExecution:(BOOL)allowHeadlessExecution
87-
restorationEnabled:(BOOL)restorationEnabled NS_DESIGNATED_INITIALIZER;
91+
restorationEnabled:(BOOL)restorationEnabled NS_DESIGNATED_INITIALIZER NS_SWIFT_UI_ACTOR;
8892

8993
/**
9094
* Not recommended for use - will initialize with a default label ("io.flutter.headless")
9195
* and the default FlutterDartProject.
9296
*/
93-
- (instancetype)init;
97+
- (instancetype)init NS_SWIFT_UI_ACTOR;
9498

9599
@end
96100

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine+Test.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,8 @@ class ThreadHost;
3434
- (FlutterEngine*)spawnWithEntrypoint:(/*nullable*/ NSString*)entrypoint
3535
libraryURI:(/*nullable*/ NSString*)libraryURI
3636
initialRoute:(/*nullable*/ NSString*)initialRoute
37-
entrypointArgs:(/*nullable*/ NSArray<NSString*>*)entrypointArgs;
37+
entrypointArgs:(/*nullable*/ NSArray<NSString*>*)entrypointArgs
38+
NS_SWIFT_UI_ACTOR;
3839
- (const flutter::ThreadHost&)threadHost;
3940
- (void)updateDisplays;
4041
- (void)flutterTextInputView:(FlutterTextInputView*)textInputView

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,10 @@ - (instancetype)initWithName:(NSString*)labelPrefix
241241
NSAssert(self, @"Super init cannot be nil");
242242
NSAssert(labelPrefix, @"labelPrefix is required");
243243

244+
// Reading the UIApplication lifecycle state and registering for UIKit notifications below both
245+
// require the main thread, as does running the engine.
246+
FML_DCHECK(NSThread.isMainThread) << "FlutterEngine must be created on the main thread.";
247+
244248
_restorationEnabled = restorationEnabled;
245249
_allowHeadlessExecution = allowHeadlessExecution;
246250
_labelPrefix = [labelPrefix copy];
@@ -289,7 +293,7 @@ - (instancetype)initWithName:(NSString*)labelPrefix
289293
}
290294

291295
+ (FlutterEngine*)engineForIdentifier:(int64_t)identifier {
292-
NSAssert([[NSThread currentThread] isMainThread], @"Must be called on the main thread.");
296+
NSAssert(NSThread.isMainThread, @"Must be called on the main thread.");
293297
return (__bridge FlutterEngine*)reinterpret_cast<void*>(identifier);
294298
}
295299

@@ -918,6 +922,18 @@ static void SetEntryPoint(flutter::Settings* settings, NSString* entrypoint, NSS
918922
- (BOOL)createShell:(NSString*)entrypoint
919923
libraryURI:(NSString*)libraryURI
920924
initialRoute:(NSString*)initialRoute {
925+
// MakeThreadHost below adopts the calling thread as this engine's platform/UI thread, which
926+
// must be the main thread. The engine relies on UIApplicationMain to pump the platform thread's
927+
// run loop, and the platform thread reads UIKit state (UIScreen, CADisplayLink) and runs all
928+
// plugin and platform channel callbacks.
929+
//
930+
// Engines spawned from this one inherit these task runners, so this applies to every engine in a
931+
// FlutterEngineGroup.
932+
FML_CHECK(NSThread.isMainThread)
933+
<< "FlutterEngine must be run on the main thread. The engine adopts the calling thread as "
934+
"its platform and UI thread, both of which must be the main thread. To start an engine "
935+
"from a background queue, dispatch to the main queue first.";
936+
921937
if (_shell != nullptr) {
922938
[FlutterLogger logWarning:@"This FlutterEngine was already invoked."];
923939
return NO;
@@ -1605,6 +1621,8 @@ - (FlutterEngine*)spawnWithEntrypoint:(/*nullable*/ NSString*)entrypoint
16051621
libraryURI:(/*nullable*/ NSString*)libraryURI
16061622
initialRoute:(/*nullable*/ NSString*)initialRoute
16071623
entrypointArgs:(/*nullable*/ NSArray<NSString*>*)entrypointArgs {
1624+
FML_CHECK(NSThread.isMainThread) << "FlutterEngine must be spawned on the iOS main thread.";
1625+
16081626
NSAssert(_shell, @"Spawning from an engine without a shell (possibly not run).");
16091627
FlutterEngine* result = [[FlutterEngine alloc] initWithName:self.labelPrefix
16101628
project:self.dartProject

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,14 @@ NS_ASSUME_NONNULL_BEGIN
5959
- (void)launchEngine:(nullable NSString*)entrypoint
6060
libraryURI:(nullable NSString*)libraryOrNil
6161
entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs;
62+
/**
63+
* Creates the shell, adopting the calling thread as this engine's platform thread.
64+
*
65+
* Must be called on the main thread; see the `FlutterEngine` class documentation.
66+
*/
6267
- (BOOL)createShell:(nullable NSString*)entrypoint
6368
libraryURI:(nullable NSString*)libraryOrNil
64-
initialRoute:(nullable NSString*)initialRoute;
69+
initialRoute:(nullable NSString*)initialRoute NS_SWIFT_UI_ACTOR;
6570
- (void)attachView;
6671
- (void)notifyLowMemory;
6772

@@ -74,11 +79,15 @@ NS_ASSUME_NONNULL_BEGIN
7479
*
7580
* This results in a faster creation time and a smaller memory footprint engine.
7681
* This should only be called on a FlutterEngine that is running.
82+
*
83+
* The spawned engine shares this engine's task runners, so this must be called on this engine's
84+
* platform thread, which is always the main thread.
7785
*/
7886
- (FlutterEngine*)spawnWithEntrypoint:(nullable NSString*)entrypoint
7987
libraryURI:(nullable NSString*)libraryURI
8088
initialRoute:(nullable NSString*)initialRoute
81-
entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs;
89+
entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs
90+
NS_SWIFT_UI_ACTOR;
8291

8392
/**
8493
* Dispatches the given key event data to the framework through the engine.

‎engine/src/flutter/shell/platform/darwin/ios/framework/Source/LaunchEngine.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,10 @@ import Foundation
2828
/// For new application code, application developers should consider conforming to
2929
/// `FlutterImplicitEngineDelegate` and implementing `didInitializeImplicitFlutterEngine` instead of
3030
/// relying on `FlutterAppDelegate`'s automatic registration.
31+
///
32+
/// This class is main-actor isolated. It creates and runs a `FlutterEngine`, both of which must
33+
/// happen on the main thread.
34+
@MainActor
3135
@objc(FlutterLaunchEngine)
3236
final class LaunchEngine: NSObject {
3337

0 commit comments

Comments
 (0)