Expose Flutter Engine address to be used with FFI

[knopp]

Currently, when writing FFI plugins there is no good way to interact with the engine. One options is to write a Flutter plugin, that either stores reference to the engine statically to be used with FFI, or uses platform channels to let the isolate access engine address and then possibly use it through FFI calls. Both of these are problematic, because a) storing reference to engine statically assumes that there's only one engine running b) using platform channels requires asynchronous call to get engine address.

Neither of these workarounds would help us if we want to use FFI inside our embedders, which is something we might want to do in future, i.e. for #150460 or multi-window.

Better solution would be to provide engine handle to the root isolate at startup. Dart code can then pass this value to FFI calls which could then obtain the Flutter engine.

How exactly the engine is obtained depends on the platform.

• iOS, macOS - [FlutterEngine engineForHandle:handle].
• Windows - FlutterDesktopEngineForHandle(handle)
• Linux - fl_engine_for_handle(handle).
• Android - io.flutter.embedding.engine.FlutterEngine.forHandle(handle) (static method).

On dart side this could be accessed from PlatformDispatcher, i.e. PlatformDispatcher.instance.engineHandle. The value would be null for web and custom embedders that don't set the value.

The value would be set through embedder API by the engine and available from isolate start.

[dcharkes]

@HosseinYousefi Would this help with dart-lang/native#1865 (comment) ?

Also @stuartmorgan might have ideas about the interaction between FFI code and the engine.

[HosseinYousefi]

Yes, that's exactly what I need as well!

[stuartmorgan-g]

#110353 has some earlier related discussion, but is focused on the plugin API surface specifically.

There's been some discussion that wasn't captured there about how exactly we would vend things, given that the types are platform-specific. I like this handle proposal; it sidesteps the problems of what types we would use, how we would do generation of shared objects without adding framework dependencies on the *gen packages, and would allow arbitrary embedders to support it by adding a corresponding API to the embedding surface.

[stuartmorgan-g]

Capturing from Discord, Chinmay pointed out that there will be some inherent danger for anyone using this system. E.g., if someone writes a plugin right now against the plugin registry APIs, and then those change, then someone trying to use the plugin with a new version of Flutter will get compilation errors.

If they write equivalent code using FFI generation of the Flutter plugin API surface, getting to the instance via this handle, then if the API surface changes it will instead explode at runtime.

The only way I see to avoid that would be if we did FFI generation as part of the framework, but then we get back to all of the same problems mentioned in my previous comment.

[knopp]

@stuartmorgan, I think the danger mentioned was mostly for my original proposal which would be providing raw engine pointer directly instead of handle. That was probably not the best idea. Using handle instead means that you have to call actual embedder API to get the engine pointer. And if you manage to do that, chances are you are able to call the other engine method safely as well.

Our embedder API is so far has been pretty stable. I would not expect this to change much. Once #163476 and #162935 land (and the new threading model gets enabled by default, which would be the next PR) it should be possible to write a file picker plugin completely in Dart.

[stuartmorgan-g]

Using handle instead means that you have to call actual embedder API to get the engine pointer. And if you manage to do that, chances are you are able to call the other engine method safely as well.

How would one follow from the other? The fact that the static get-engine-from-handle function still exists doesn't mean that the entire public embedding API on that platform is unchanged since the package did FFI generation.

Our embedder API is so far has been pretty stable. I would not expect this to change much.

Sure, but "pretty stable" and formally stable are not the same thing. For plugin-visible APIs in particular we try to be very conservative with breaking changes, because they are potentially very disruptive to the ecosystem, but they do still happen. Android's removal of the v1 embedding APIs, for instance.

Once #163476 and #162935 land (and the new threading model gets enabled by default, which would be the next PR) it should be possible to write a file picker plugin completely in Dart.

And doing so on will (on several platforms) involve a call to a method that we will be deprecating for multi-view support. A native plugin could get deprecation warnings from annotations, and if we do ever remove that deprecated method (unlikely in this particular case, but possible) a native plugin would get a compile-time error. A Dart version, on the other hand, would never get any deprecation warning, and would fail at runtime if we removed the method.

I'm not saying this is a blocker, but it is the case that the Dart version of this code would have pitfalls that the native version does not, and in providing this API we need to recognize that we will be creating new failures modes that will not be obvious to most developers, and we need to consider the consequences.

[HosseinYousefi]

a native plugin would get a compile-time error. A Dart version, on the other hand, would never get any deprecation warning, and would fail at runtime if we removed the method.

We should maintain and ship the generated bindings for Flutter APIs either as a separate package or as part of the SDK to avoid this problem. The *gen tools could generate @Deprecated from the native annotations as well.

[knopp]

Well, yes, that is a downside with FFI and something to keep in mind. Fortunately the API surface is not huge. And for plugins written completely in Dart we would probably want to have official Dart bindings for engine.