Skip to content

Commit a75bde3

Browse files
authored
[pigeon] Support multi-engine Native Interop registration and instance-aware unregistration (#13576)
Associates Native Interop (`useJni` / `useFfi`) `@HostApi` and `@FlutterApi` registrations with the Flutter engine that made them. Lookups route to the calling engine's registration when the engine is known, and detaching one engine removes only that engine's registration. Previously, attaching a secondary `FlutterEngine` overwrote any existing registration under the same `name`. Detaching that engine via `register(null)` then cleared the entry for all remaining engines in the process. For example, `shared_preferences_android` failed in the main engine after a background engine detached (flutter/flutter#194920). > [!NOTE] > Per review, the standalone `@FlutterApi` fixes (the `pigeonVar_` prefix for internal `_<Api>Registrar` members so `register` / `dartApi` no longer collide on JNI, `implement` with an empty `name`, and the `objective_c <9.6.3` test pin) are split out into #13609 so they can land on 29.x first. This PR contains only the unregistration and multi-engine changes, which depend on each other. ### Engine identity without deprecated APIs or new stable requirements `register` / `unregister` now take the engine handle that plugins and apps already have. Pigeon derives an engine key from it, so moving to `engineId` once flutter/flutter#195881 reaches `stable` is an internal change, not another breaking change: | Caller | Engine key | |---|---| | Kotlin app: `MyApiRegistrar().register(api, flutterEngine)` | `FlutterEngine.engineId` (public on stable; exact) | | Kotlin plugin: `MyApiRegistrar().register(api, binding)` | `binding.getEngineId()` when the embedding provides a non-zero value (#195881, detected at runtime, survives R8). Otherwise a per-engine key from `binding.binaryMessenger`. | | Swift: `MyApiSetup.register(api:registrar:)` | `registrar.engineIdentifier` when available and non-zero (detected at runtime). Otherwise a per-engine key from the registrar's messenger. | Generated code never calls deprecated embedding APIs such as `FlutterPluginBinding.getFlutterEngine()`. An engine ID of `0` is treated as unknown, because real IDs are never `0`. `0` shows up for registrars whose engine is already deallocating, and for unstubbed test doubles, and must not be shared between engines. Dart lookups (`createWithNativeInteropApi()` / `<HostApi>ForNativeInterop.getInstance()`) choose a registration in this order: 1. The one whose key matches `PlatformDispatcher.instance.engineId`. 2. Otherwise, if the isolate has no engine ID, one from the engine this isolate first resolved a handle from. This is tracked per generated Pigeon file. 3. Otherwise, the most recent registration. Native `@FlutterApi` lookups use the same keys through `<FlutterApi>Registrar` `getInstance(binding | flutterEngine)` in Kotlin and `getInstance(registrar:)` in Swift. **Exact vs. best-effort routing.** Routing is exact whenever native code knows the engine identifier: Kotlin `register(api, flutterEngine)` always, and plugin bindings / registrars on Flutter versions that expose it. Otherwise it is best-effort. It is correct when each engine's Dart resolves its first handle from each Pigeon file at startup, but it can pick another engine's registration when: - Engines are created back-to-back before their Dart starts. - A file's first lookup happens lazily while another engine is attached. - Lookups come from `Isolate.spawn` / `Isolate.run` isolates. macOS plugins receive no detach callback, so macOS registrations currently outlive their engine. The README and guides document these limits and recommend platform channels / `@ProxyApi` for engine-stateful APIs in those cases. Full engine routing remains tracked in flutter/flutter#195877. ### Summary of Changes * **Engine-keyed registration stacks & `unregister`**: Each `name` keeps an ordered stack of `(engine key, instance)` entries. * Re-registering the same instance for the same engine moves it to the top and keeps its existing wrapper. * `unregister(api, engine)` removes only that engine's entry, even out of order. If the engine key can't be resolved, it falls back to matching by instance identity, but only when a single engine holds that instance. * **Detached `@HostApi` safety**: Calls through a handle whose instance was unregistered throw `unregistered-instance` (Kotlin/Swift) instead of crashing. Swift `Setup` wrappers use `resolveApi() throws` instead of `api!`. * **Engine teardown safety (Swift)**: Engine keys are cached per registrar. `unregister` from `detachFromEngine(for:)` therefore works while the engine is deallocating and its messenger is already gone. * **Registry thread safety**: Native Interop calls from background isolates run on worker threads. Registration maps, wrapper API references, and engine-key caches are therefore guarded internally: * Kotlin uses `synchronized` / `@Synchronized` and `@Volatile`. * Swift uses `NSLock` / `NSRecursiveLock`. Removed entries are released after unlocking, so their `deinit` doesn't run while the lock is held. * This doesn't make registration a thread-safe API contract. Registration is still expected on the main thread. * **Dart `@FlutterApi`**: * `<FlutterApi>.setUp(null)` deregisters only the current isolate's native callback. * Registering via `setUp(a)` or the registrar, then calling `setUp(null)`, now correctly removes `a`. * Adds `<FlutterApi>Registrar.unregister`. * Registrations are tagged with the isolate's engine so native lookups reach the right isolate. * **Documentation**: * Updates the README, Native Interop guide, migration guide, migration skill, and `CHANGELOG.md`, including the routing guarantees and limits above. * Notes that `registrar.publish(instance)` is required for iOS to call `detachFromEngine(for:)`. * **Tests**: * Generator unit tests for Dart, Kotlin, and Swift. * Kotlin `NativeInteropRegistrarTest`, iOS `RunnerTests`, and macOS `BasicCompileTest`. These cover: * the same API on two engines * out-of-order unregister * the identity fallback * resolve order * `@FlutterApi` lookup by engine * Real secondary-engine and multi-isolate integration tests. * An integration test asserting that registrations use the exact `PlatformDispatcher.instance.engineId` when the platform exposes it. It runs in minified Android release builds to cover R8. ### Breaking Native Interop API Changes (`30.0.0`) * **Engine-aware registration**: * `@HostApi` `register` / `unregister` take the engine: `MyApiRegistrar().register(api, binding)` / `register(api, flutterEngine)` in Kotlin, and `MyApiSetup.register(api:registrar:)` in Swift. `unregister` follows the same shape. * Native `@FlutterApi` lookup takes the engine: `getInstance(binding | flutterEngine)` in Kotlin and `getInstance(registrar:)` in Swift. The name-only native `getInstance` is removed. * **Explicit deregistration**: * Replaces `register(null)` / `register(api: nil)` / `registerInstance(null | nil)` with `unregister` / `unregisterInstance`, which remove only the given instance for the given engine. * `register` / `registerInstance` require a non-null API and return `void` / `Unit` / `Void`. * **Swift `@HostApi` `AnyObject` constraint**: FFI Swift `@HostApi` protocols are constrained to `AnyObject` so instances can be matched by identity. * **Reserved names**: `pigeonResolveInstance`, `pigeonEngineKey`, and `pigeonEngineKeyOf` are reserved as `@HostApi` method names. Part of flutter/flutter#195877 Part of flutter/flutter#194920 ## Pre-Review Checklist **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. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 75094a6 commit a75bde3

45 files changed

Lines changed: 16030 additions & 2366 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/pigeon/CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
## 30.0.0
2+
3+
* **BREAKING CHANGE**: [kotlin,swift] Native Interop registration now supports multiple engines:
4+
* `register` and `unregister` take the engine the instance belongs to (a plugin binding or `FlutterEngine` in Kotlin, a registrar in Swift). Use `unregister` instead of `register(null)`.
5+
* Native `@FlutterApi` lookups take the engine (`getInstance(binding)` / `getInstance(registrar:)`) instead of a name, and the native `@HostApi` `getInstance(name)` is removed.
6+
* Swift FFI `@HostApi` implementations must be classes.
7+
* See the [Native Interop migration guide](./native_interop_migration_guide.md) for details.
8+
* [dart,kotlin,swift] Fixes detaching one engine clearing Native Interop APIs for all other engines.
9+
* [dart,kotlin,swift] Native Interop calls now go to the calling engine's instance where possible.
10+
* [kotlin,swift] Calling a Native Interop API whose instance was unregistered now throws a `PlatformException` instead of crashing.
11+
112
## 29.2.0
213

314
* [dart] [kotlin] [swift] Passes data class, `List`, `Map` and `Object` values

‎packages/pigeon/README.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,27 @@ Pigeon supports two distinct models for communication between Dart and native co
109109
2. **Native Interop (Direct FFI & JNI) \*Preview\***: A direct, memory-bound function call model utilizing Dart FFI (for Swift/Objective-C on iOS/macOS) and JNI (for Kotlin/Java on Android).
110110

111111
> [!WARNING]
112-
> Native Interop `@HostApi` registrations are process-wide, not per-engine. In apps that run multiple
113-
> `FlutterEngine`s, one engine can overwrite or unregister another engine's implementation. See
114-
> [flutter/flutter#195877](https://github.com/flutter/flutter/issues/195877).
112+
> Native Interop associates each registration with the `FlutterEngine` that made it, but in apps
113+
> that run multiple engines, routing on an engine's root isolate is only exact when the engine
114+
> identifier is available to native code (always for Kotlin `register(api, flutterEngine)`; for
115+
> plugin bindings and registrars, only on Flutter versions that expose it). See
116+
> [Multi-Engine Routing](./native_interop_guide.md#multi-engine-routing) and
117+
> [flutter/flutter#195877](https://github.com/flutter/flutter/issues/195877). Known limitations:
118+
> - Until engine identifiers are available to plugins on stable Flutter, each generated Pigeon file
119+
> binds to the engine of its first resolved `@HostApi` handle. If that first lookup happens while
120+
> another engine's registration is the most recent one, for example when engines are created
121+
> back-to-back before their Dart code starts, or when an API is first used lazily while a
122+
> secondary engine is attached, that file's APIs may be bound to the other engine's instance and
123+
> throw `unregistered-instance` after that engine detaches.
124+
> - Background isolates (`Isolate.spawn` / `Isolate.run`) do not have a `PlatformDispatcher.engineId`,
125+
> so in multi-engine apps their lookups may resolve another engine's registration.
126+
> - APIs that hold engine-specific state (such as an Android `Activity`, a `TextureRegistry`, or a
127+
> `UIViewController`) may act on the wrong engine; use a distinct `messageChannelSuffix` per
128+
> engine, or platform channels / `@ProxyApi`, for those APIs.
129+
> - On macOS, plugins receive no detach callback, so registrations outlive their engine.
130+
> - `@FlutterApi` registrations are only removed when Dart calls `setUp(null)` / `unregister`. If an
131+
> isolate goes away without doing so (for example, after a hot restart or when its engine is
132+
> destroyed), native lookups can still return its stale registration, and calls to it fail.
115133
116134
#### Quick Comparison
117135

‎packages/pigeon/example/native_interop_app/android/app/src/main/kotlin/dev/flutter/pigeonnativeinteropapp/MainActivity.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,6 @@ class MainActivity : FlutterActivity() {
2020
super.configureFlutterEngine(flutterEngine)
2121

2222
val api = PigeonApiImplementation()
23-
NativeInteropExampleApiRegistrar().register(api)
23+
NativeInteropExampleApiRegistrar().register(api, flutterEngine)
2424
}
2525
}

‎packages/pigeon/example/native_interop_app/android/app/src/main/kotlin/dev/flutter/pigeonnativeinteropapp/NativeInteropExample.g.kt‎

Lines changed: 222 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ package dev.flutter.pigeonnativeinteropapp
99

1010
import android.util.Log
1111
import androidx.annotation.Keep
12+
import io.flutter.embedding.engine.FlutterEngine
13+
import io.flutter.embedding.engine.plugins.FlutterPlugin
1214
import io.flutter.plugin.common.StandardMessageCodec
1315
import java.io.ByteArrayOutputStream
1416
import java.nio.ByteBuffer
@@ -47,6 +49,75 @@ class FlutterError(
4749

4850
private const val defaultInstanceName = "PigeonDefaultClassName32uh4ui3lh445uh4h3l2l455g4y34u"
4951

52+
/** Computes keys that identify the Flutter engine a registration belongs to. */
53+
private object NativeInteropExamplePigeonEngineKeys {
54+
/** Sentinel meaning that no engine key is known. */
55+
const val NO_KEY: Long = Long.MIN_VALUE
56+
57+
/** `FlutterPluginBinding.getEngineId`, which is missing on older Flutter versions. */
58+
private val getEngineIdMethod: java.lang.reflect.Method? by lazy {
59+
try {
60+
FlutterPlugin.FlutterPluginBinding::class.java.getMethod("getEngineId")
61+
} catch (e: Exception) {
62+
null
63+
}
64+
}
65+
66+
/** Keys for engine messengers, used when an exact engine id is unavailable. */
67+
private val messengerKeys = java.util.WeakHashMap<Any, Long>()
68+
69+
/**
70+
* Keys already computed for each binding, so `register` and `unregister` with the same binding
71+
* always agree even if [keyOf] for its engine later records an exact key for the messenger.
72+
*/
73+
private val bindingKeys = java.util.WeakHashMap<FlutterPlugin.FlutterPluginBinding, Long>()
74+
75+
private var nextSyntheticKey: Long = -1L
76+
77+
/** Returns the key for the engine that [binding] belongs to. */
78+
@Synchronized
79+
fun keyOf(binding: FlutterPlugin.FlutterPluginBinding): Long {
80+
return bindingKeys.getOrPut(binding) { computeKey(binding) }
81+
}
82+
83+
private fun computeKey(binding: FlutterPlugin.FlutterPluginBinding): Long {
84+
val method = getEngineIdMethod
85+
if (method != null) {
86+
try {
87+
// Real engine ids are never 0, but an engine without one, or a test
88+
// double, reports 0, which must not be shared between engines.
89+
val engineId = method.invoke(binding) as Long
90+
if (engineId != 0L) {
91+
return engineId
92+
}
93+
} catch (e: Exception) {
94+
// Fall back to a messenger-based key.
95+
}
96+
}
97+
return keyOfMessenger(binding.binaryMessenger)
98+
}
99+
100+
/** Returns the key for [engine]. */
101+
@Synchronized
102+
fun keyOf(engine: FlutterEngine): Long {
103+
val key = engine.engineId
104+
if (key == 0L) {
105+
// Real engine ids are never 0, but an engine without one, or a test
106+
// double, reports 0, which must not be shared between engines.
107+
return keyOfMessenger(engine.dartExecutor)
108+
}
109+
// Record the exact key so later lookups through a binding for this engine
110+
// agree with it even when the binding cannot report the engine id.
111+
messengerKeys[engine.dartExecutor] = key
112+
return key
113+
}
114+
115+
@Synchronized
116+
private fun keyOfMessenger(messenger: Any): Long {
117+
return messengerKeys.getOrPut(messenger) { nextSyntheticKey-- }
118+
}
119+
}
120+
50121
private open class NativeInteropExamplePigeonCodec : StandardMessageCodec() {
51122
override fun readValueOfType(type: Byte, buffer: ByteBuffer): Any? {
52123
return super.readValueOfType(type, buffer)
@@ -81,7 +152,8 @@ private object NativeInteropExamplePigeonInteropCodec : NativeInteropExamplePige
81152
}
82153
}
83154

84-
val NativeInteropExampleApiInstances: MutableMap<String, NativeInteropExampleApiRegistrar> =
155+
val NativeInteropExampleApiInstances:
156+
MutableMap<String, MutableList<NativeInteropExampleApiRegistrar>> =
85157
mutableMapOf()
86158

87159
@Keep
@@ -90,29 +162,164 @@ interface NativeInteropExampleApi {
90162
}
91163

92164
@Keep
93-
class NativeInteropExampleApiRegistrar {
94-
private var api: NativeInteropExampleApi? = null
165+
class NativeInteropExampleApiRegistrar private constructor(private val engineKey: Long) {
166+
@Volatile private var api: NativeInteropExampleApi? = null
167+
168+
constructor() : this(NativeInteropExamplePigeonEngineKeys.NO_KEY)
95169

170+
/**
171+
* Registers [api] under [name] (or the default instance when [name] is omitted) for the engine of
172+
* the plugin binding [binding].
173+
*
174+
* The registration is tied to that engine: unregistering it for this engine leaves other engines'
175+
* registrations in place, and Dart code running on an engine uses the instance registered for
176+
* that engine when it is known.
177+
*/
178+
@Keep
96179
fun register(
97-
api: NativeInteropExampleApi?,
180+
api: NativeInteropExampleApi,
181+
binding: FlutterPlugin.FlutterPluginBinding,
98182
name: String = defaultInstanceName
99-
): NativeInteropExampleApiRegistrar {
100-
if (api != null) {
101-
this.api = api
102-
NativeInteropExampleApiInstances[name] = this
103-
} else {
104-
NativeInteropExampleApiInstances.remove(name)
105-
}
106-
return this
183+
) {
184+
registerWithKey(api, NativeInteropExamplePigeonEngineKeys.keyOf(binding), name)
185+
}
186+
187+
/**
188+
* Registers [api] under [name] (or the default instance when [name] is omitted) for the engine of
189+
* [engine].
190+
*
191+
* The registration is tied to that engine: unregistering it for this engine leaves other engines'
192+
* registrations in place, and Dart code running on an engine uses the instance registered for
193+
* that engine when it is known.
194+
*/
195+
@Keep
196+
fun register(
197+
api: NativeInteropExampleApi,
198+
engine: FlutterEngine,
199+
name: String = defaultInstanceName
200+
) {
201+
registerWithKey(api, NativeInteropExamplePigeonEngineKeys.keyOf(engine), name)
107202
}
108203

204+
/**
205+
* Removes [api] from the registrations under [name] (or the default instance when [name] is
206+
* omitted) for the engine of the plugin binding [binding], leaving other registrations in place.
207+
*
208+
* Instances are matched by identity. If [api] is not registered for that engine but is registered
209+
* for exactly one other engine, that registration is removed. Does nothing if [api] is not
210+
* registered, or is only registered for several other engines.
211+
*/
109212
@Keep
110-
fun getInstance(name: String): NativeInteropExampleApiRegistrar? {
111-
return NativeInteropExampleApiInstances[name]
213+
fun unregister(
214+
api: NativeInteropExampleApi,
215+
binding: FlutterPlugin.FlutterPluginBinding,
216+
name: String = defaultInstanceName
217+
) {
218+
unregisterWithKey(api, NativeInteropExamplePigeonEngineKeys.keyOf(binding), name)
219+
}
220+
221+
/**
222+
* Removes [api] from the registrations under [name] (or the default instance when [name] is
223+
* omitted) for the engine of [engine], leaving other registrations in place.
224+
*
225+
* Instances are matched by identity. If [api] is not registered for that engine but is registered
226+
* for exactly one other engine, that registration is removed. Does nothing if [api] is not
227+
* registered, or is only registered for several other engines.
228+
*/
229+
@Keep
230+
fun unregister(
231+
api: NativeInteropExampleApi,
232+
engine: FlutterEngine,
233+
name: String = defaultInstanceName
234+
) {
235+
unregisterWithKey(api, NativeInteropExamplePigeonEngineKeys.keyOf(engine), name)
236+
}
237+
238+
private fun registerWithKey(api: NativeInteropExampleApi, engineKey: Long, name: String) {
239+
kotlin.synchronized(NativeInteropExampleApiInstances) {
240+
val list = NativeInteropExampleApiInstances.getOrPut(name) { mutableListOf() }
241+
val index = list.indexOfFirst { it.api === api && it.engineKey == engineKey }
242+
if (index >= 0) {
243+
list.add(list.removeAt(index))
244+
} else {
245+
val wrapper = NativeInteropExampleApiRegistrar(engineKey)
246+
wrapper.api = api
247+
list.add(wrapper)
248+
}
249+
}
250+
}
251+
252+
private fun unregisterWithKey(api: NativeInteropExampleApi, engineKey: Long, name: String) {
253+
kotlin.synchronized(NativeInteropExampleApiInstances) {
254+
val list = NativeInteropExampleApiInstances[name] ?: return
255+
val removeKey =
256+
if (list.any { it.api === api && it.engineKey == engineKey }) {
257+
engineKey
258+
} else {
259+
list.filter { it.api === api }.map { it.engineKey }.distinct().singleOrNull() ?: return
260+
}
261+
val iterator = list.iterator()
262+
while (iterator.hasNext()) {
263+
val entry = iterator.next()
264+
if (entry.api === api && entry.engineKey == removeKey) {
265+
entry.api = null
266+
iterator.remove()
267+
}
268+
}
269+
if (list.isEmpty()) {
270+
NativeInteropExampleApiInstances.remove(name)
271+
}
272+
}
273+
}
274+
275+
companion object {
276+
/**
277+
* Returns the instance registered under [name] for the engine identified by [engineId].
278+
*
279+
* Falls back to the most recent instance registered for [affinityKey], then to the most recent
280+
* instance overall. Either key may be `Long.MIN_VALUE` when it is unknown.
281+
*
282+
* This is called by the generated Dart code and is not intended for direct use.
283+
*/
284+
@JvmStatic
285+
@Keep
286+
fun pigeonResolveInstance(
287+
engineId: Long,
288+
affinityKey: Long,
289+
name: String = defaultInstanceName
290+
): NativeInteropExampleApiRegistrar? {
291+
return kotlin.synchronized(NativeInteropExampleApiInstances) {
292+
val list = NativeInteropExampleApiInstances[name] ?: return null
293+
val exact =
294+
if (engineId != NativeInteropExamplePigeonEngineKeys.NO_KEY)
295+
list.lastOrNull { it.engineKey == engineId }
296+
else null
297+
val affine =
298+
if (affinityKey != NativeInteropExamplePigeonEngineKeys.NO_KEY)
299+
list.lastOrNull { it.engineKey == affinityKey }
300+
else null
301+
exact ?: affine ?: list.lastOrNull()
302+
}
303+
}
304+
305+
/**
306+
* Returns the engine key that [instance] was registered with, or `Long.MIN_VALUE` if it is
307+
* unknown.
308+
*
309+
* This is called by the generated Dart code and is not intended for direct use.
310+
*/
311+
@JvmStatic
312+
@Keep
313+
fun pigeonEngineKeyOf(instance: NativeInteropExampleApiRegistrar): Long {
314+
return instance.engineKey
315+
}
112316
}
113317

114318
fun doSomething() {
115-
val pigeonVar_api = this.api ?: error("NativeInteropExampleApi has not been registered")
319+
val pigeonVar_api =
320+
this.api
321+
?: throw FlutterError(
322+
"unregistered-instance", "NativeInteropExampleApi has not been registered.")
116323
try {
117324
pigeonVar_api.doSomething()
118325
} catch (e: FlutterError) {

‎packages/pigeon/example/native_interop_app/ios/Runner/AppDelegate.swift‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ private class PigeonApiImplementation: NativeInteropExampleApi {
1919
GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
2020

2121
let api = PigeonApiImplementation()
22-
NativeInteropExampleApiSetup.register(api: api)
22+
if let registrar = engineBridge.pluginRegistry.registrar(forPlugin: "NativeInteropExampleApi") {
23+
NativeInteropExampleApiSetup.register(api: api, registrar: registrar)
24+
}
2325
}
2426
}

0 commit comments

Comments
 (0)