Skip to content

Commit 371f772

Browse files
authored
[beta] Expose engineId on native plugin bindings and registrars on Android, iOS, and macOS (flutter#196145)
### Issue Link: flutter#195876 ### Impact Description: Native plugins using JNI/FFI (such as plugins generated with Pigeon's native interop support) register directly in native memory rather than on a per-engine `BinaryMessenger`, and have no non-deprecated public API on `FlutterPluginBinding` (Android) or `FlutterPluginRegistrar` (iOS/macOS) to obtain the engine identifier during plugin attachment and detachment. In apps running multiple `FlutterEngine` instances in the same process (such as background engines alongside the main UI engine), one engine attaching or detaching can overwrite or unregister another engine's JNI/FFI host API instance (flutter#194920). This blocks shipping multi-engine-safe FFI/JNI plugins (flutter/packages#13359) against the 3.50 stable release. **Scope of the API break:** This supersedes flutter#195991, which was closed as a breaking change. As [@stuartmorgan noted](flutter#195991 (comment)), the `@required` `engineIdentifier` property on `FlutterBaseRegistrar` (iOS) and `FlutterPluginRegistrar` (macOS) only affects hand-written native unit-test fakes that conform to those protocols directly. Production plugin and app code only consumes registrars provided by the engine and is unaffected. Following that, [@zanderso commented](flutter#195991 (comment)) that if the change is safer than the earlier signals indicated, it should be considered for a hotfix release in this cycle. Affected test fakes can add `var engineIdentifier: Int64 = 0` (Swift) or `@synthesize engineIdentifier;` (Objective-C), which compiles both before and after this change. First-party fakes were already updated in flutter/packages#13574. On Android, `FlutterPluginBinding` is a concrete class, so adding `getEngineId()` does not affect mocks. ### Changelog Description: [flutter/195876] When running multiple `FlutterEngine`s on Android, iOS, or macOS, FFI/JNI plugins could not determine which engine a `FlutterPluginBinding` or `FlutterPluginRegistrar` belonged to. ### Workaround: On Android, plugins can call the deprecated `FlutterPluginBinding.getFlutterEngine().getEngineId()`. On iOS and macOS, there is no public API workaround (`engineIdentifier` is only declared in internal headers, and the registrar's weak engine reference is already `nil` during `detachFromEngineForRegistrar:`). ### Risk: What is the risk level of this cherry-pick? ### Test Coverage: Are you confident that your fix is well-tested by automated tests? ### Validation Steps: 1. On Android, verify `FlutterPluginBinding.getEngineId()` returns the associated `FlutterEngine.getEngineId()`. 2. On iOS, verify `registrar.engineIdentifier` on `FlutterPluginRegistrar` and `FlutterApplicationRegistrar` matches the owning `FlutterEngine.engineIdentifier`, both during registration and during `detachFromEngineForRegistrar:`. 3. On macOS, verify `registrar.engineIdentifier` on `FlutterPluginRegistrar` matches the owning `FlutterEngine.engineIdentifier`.
1 parent 4586fbd commit 371f772

10 files changed

Lines changed: 102 additions & 1 deletion

File tree

‎engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/plugins/FlutterPlugin.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,15 @@ public FlutterEngine getFlutterEngine() {
143143
return flutterEngine;
144144
}
145145

146+
/**
147+
* Returns the unique identifier for the {@link FlutterEngine} associated with this binding.
148+
*
149+
* <p>This corresponds to {@code PlatformDispatcher.instance.engineId} in Dart.
150+
*/
151+
public long getEngineId() {
152+
return flutterEngine.getEngineId();
153+
}
154+
146155
@NonNull
147156
public BinaryMessenger getBinaryMessenger() {
148157
return binaryMessenger;

‎engine/src/flutter/shell/platform/android/test/io/flutter/embedding/engine/PluginComponentTest.java‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,56 @@ public void pluginsCanAccessOtherPlugins() {
106106
assertEquals(accessedPlugin, plugin.getAccessedPlugin());
107107
}
108108

109+
@Test
110+
public void pluginsCanAccessEngineId() {
111+
FlutterJNI mockFlutterJNI = mock(FlutterJNI.class);
112+
FlutterJNI flutterJNI = mock(FlutterJNI.class);
113+
jniAttached = false;
114+
when(flutterJNI.isAttached()).thenAnswer(invocation -> jniAttached);
115+
doAnswer(invocation -> jniAttached = true).when(flutterJNI).attachToNative();
116+
117+
FlutterLoader flutterLoader = new FlutterLoader(mockFlutterJNI);
118+
119+
FlutterEngine flutterEngine1 =
120+
new FlutterEngine(ApplicationProvider.getApplicationContext(), flutterLoader, flutterJNI);
121+
FlutterEngine flutterEngine2 =
122+
new FlutterEngine(ApplicationProvider.getApplicationContext(), flutterLoader, flutterJNI);
123+
124+
PluginThatRecordsEngineId plugin1 = new PluginThatRecordsEngineId();
125+
PluginThatRecordsEngineId plugin2 = new PluginThatRecordsEngineId();
126+
flutterEngine1.getPlugins().add(plugin1);
127+
flutterEngine2.getPlugins().add(plugin2);
128+
129+
assertEquals(flutterEngine1.getEngineId(), plugin1.getAttachedEngineId());
130+
assertEquals(flutterEngine2.getEngineId(), plugin2.getAttachedEngineId());
131+
132+
flutterEngine1.getPlugins().remove(PluginThatRecordsEngineId.class);
133+
assertEquals(flutterEngine1.getEngineId(), plugin1.getDetachedEngineId());
134+
}
135+
136+
private static class PluginThatRecordsEngineId implements FlutterPlugin {
137+
private long attachedEngineId;
138+
private long detachedEngineId;
139+
140+
public long getAttachedEngineId() {
141+
return attachedEngineId;
142+
}
143+
144+
public long getDetachedEngineId() {
145+
return detachedEngineId;
146+
}
147+
148+
@Override
149+
public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
150+
attachedEngineId = binding.getEngineId();
151+
}
152+
153+
@Override
154+
public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
155+
detachedEngineId = binding.getEngineId();
156+
}
157+
}
158+
109159
private static class PluginThatAccessesAssets implements FlutterPlugin {
110160
private String assetPathBasedOnName;
111161
private String assetPathBasedOnNameAndPackage;

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -288,6 +288,14 @@ typedef enum {
288288
* Provides registration context for the application or plugins.
289289
*/
290290
@protocol FlutterBaseRegistrar <NSObject>
291+
292+
/**
293+
* The unique identifier for the `FlutterEngine` associated with this registrar.
294+
*
295+
* This corresponds to `PlatformDispatcher.instance.engineId` in Dart.
296+
*/
297+
@property(nonatomic, readonly) int64_t engineIdentifier;
298+
291299
/**
292300
* Returns a `FlutterBinaryMessenger` for creating Dart/iOS communication
293301
* channels to be used by the application or a plugin.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1781,6 +1781,10 @@ - (instancetype)initWithKey:(NSString*)key flutterEngine:(FlutterEngine*)flutter
17811781
return self;
17821782
}
17831783

1784+
- (int64_t)engineIdentifier {
1785+
return _flutterEngine.engineIdentifier;
1786+
}
1787+
17841788
- (NSObject<FlutterBinaryMessenger>*)messenger {
17851789
return _flutterEngine.binaryMessenger;
17861790
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,11 +421,15 @@ - (void)testEngineId {
421421
[engine run];
422422
int64_t id1 = engine.engineIdentifier;
423423
XCTAssertTrue(id1 != 0);
424+
NSObject<FlutterPluginRegistrar>* registrar1 = [engine registrarForPlugin:@"foo"];
425+
XCTAssertEqual(registrar1.engineIdentifier, id1);
424426
FlutterEngine* spawn = [engine spawnWithEntrypoint:nil
425427
libraryURI:nil
426428
initialRoute:nil
427429
entrypointArgs:nil];
428430
int64_t id2 = spawn.engineIdentifier;
431+
NSObject<FlutterPluginRegistrar>* registrar2 = [spawn registrarForPlugin:@"foo"];
432+
XCTAssertEqual(registrar2.engineIdentifier, id2);
429433
XCTAssertEqual([FlutterEngine engineForIdentifier:id1], engine);
430434
XCTAssertEqual([FlutterEngine engineForIdentifier:id2], spawn);
431435
}
@@ -1158,6 +1162,8 @@ - (void)testRegistrarForApplication {
11581162

11591163
NSObject<FlutterApplicationRegistrar>* registrar = [mockEngine registrarForApplication:pluginKey];
11601164

1165+
XCTAssertTrue([registrar respondsToSelector:@selector(engineIdentifier)]);
1166+
XCTAssertEqual(registrar.engineIdentifier, engine.engineIdentifier);
11611167
XCTAssertTrue([registrar respondsToSelector:@selector(messenger)]);
11621168
XCTAssertTrue([registrar respondsToSelector:@selector(textures)]);
11631169
XCTAssertTrue([registrar respondsToSelector:@selector(registerViewFactory:withId:)]);

‎engine/src/flutter/shell/platform/darwin/macos/framework/Headers/FlutterPluginRegistrarMacOS.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@
2727
FLUTTER_DARWIN_EXPORT
2828
@protocol FlutterPluginRegistrar <NSObject>
2929

30+
/**
31+
* The unique identifier for the `FlutterEngine` associated with this registrar.
32+
*
33+
* This corresponds to `PlatformDispatcher.instance.engineId` in Dart.
34+
*/
35+
@property(nonatomic, readonly) int64_t engineIdentifier;
36+
3037
/**
3138
* The binary messenger used for creating channels to communicate with the Flutter engine.
3239
*/

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

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,10 @@ - (instancetype)initWithPlugin:(NSString*)pluginKey flutterEngine:(FlutterEngine
340340

341341
#pragma mark - FlutterPluginRegistrar
342342

343+
- (int64_t)engineIdentifier {
344+
return _flutterEngine.engineIdentifier;
345+
}
346+
343347
- (id<FlutterBinaryMessenger>)messenger {
344348
return _flutterEngine.binaryMessenger;
345349
}
@@ -738,7 +742,7 @@ - (BOOL)runWithEntrypoint:(NSString*)entrypoint {
738742
[FlutterLogger logDirect:[NSString stringWithUTF8String:log.c_str()]];
739743
};
740744

741-
flutterArguments.engine_id = reinterpret_cast<int64_t>((__bridge void*)self);
745+
flutterArguments.engine_id = self.engineIdentifier;
742746
BOOL enableWideGamut = _project.enableWideGamut;
743747
if (std::find(switches.begin(), switches.end(), "--enable-impeller=false") != switches.end()) {
744748
enableWideGamut = NO;
@@ -1382,6 +1386,10 @@ - (void)shutDownEngine {
13821386
_engine = nullptr;
13831387
}
13841388

1389+
- (int64_t)engineIdentifier {
1390+
return reinterpret_cast<int64_t>((__bridge void*)self);
1391+
}
1392+
13851393
+ (FlutterEngine*)engineForIdentifier:(int64_t)identifier {
13861394
NSAssert([[NSThread currentThread] isMainThread], @"Must be called on the main thread.");
13871395
return (__bridge FlutterEngine*)reinterpret_cast<void*>(identifier);

‎engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngineTest.mm‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -951,6 +951,9 @@ @implementation MockableFlutterEngine
951951
if (!engineId.has_value()) {
952952
return;
953953
}
954+
id<FlutterPluginRegistrar> registrar = [engine registrarForPlugin:@"MyPlugin"];
955+
EXPECT_EQ(engine.engineIdentifier, *engineId);
956+
EXPECT_EQ(registrar.engineIdentifier, *engineId);
954957
EXPECT_EQ(engine, [FlutterEngine engineForIdentifier:*engineId]);
955958
ShutDownEngine();
956959
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,11 @@ typedef NS_ENUM(NSInteger, FlutterAppExitResponse) {
262262
*/
263263
- (NSArray<NSScreen*>*)screens;
264264

265+
/**
266+
* The unique identifier for this engine.
267+
*/
268+
@property(nonatomic, readonly) int64_t engineIdentifier;
269+
265270
/**
266271
* Returns engine for the identifier. The identifier must be valid for an engine
267272
* that is currently running, otherwise the behavior is undefined.

‎engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPluginTest.mm‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ @interface FakePluginRegistrar : NSObject <FlutterPluginRegistrar>
2727
@implementation FakePluginRegistrar
2828

2929
// Synthesize properties declared in FlutterPluginRegistrar protocol.
30+
@synthesize engineIdentifier;
3031
@synthesize messenger;
3132
@synthesize textures;
3233
@synthesize view;

0 commit comments

Comments
 (0)