Add PlatformDispatcher.engineId (#163476)

Fixes flutter/flutter#163430.

This PR adds `engineId` field to `PlatformDispatcher`. When provided by
the engine, this can be used to retrieve the engine instance from native
code.

Dart code:
```dart
final identifier = PlatformDispatcher.instance.engineId!;
```

macOS, iOS: 
```objc
FlutterEngine *engine = [FlutterEngine engineForIdentifier: identifier];
```

Android:
```java
FlutterEngine engine = FlutterEngine.engineForId(identifier);
```

Linux
```cpp
FlEngine *engine = fl_engine_for_id(identifier);
```

Windows
```cpp
FlutterDesktopEngineRef engine = FlutterDesktopEngineForId(identifier);
```

*If you had to change anything in the [flutter/tests] repo, include a
link to the migration guide as per the [breaking change policy].*

## Pre-launch Checklist

- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [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].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[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

Author: knopp

dev/integration_tests/android_engine_test/lib/engine_handle.dart

@@ -0,0 +1,23 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:convert';
+
+import 'package:android_driver_extensions/extension.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_driver/driver_extension.dart';
+
+import 'src/allow_list_devices.dart';
+
+void main() {
+  ensureAndroidDevice();
+  enableFlutterDriverExtension(
+    handler: (String? command) async {
+      return json.encode(<String, Object?>{'engineId': PlatformDispatcher.instance.engineId});
+    },
+    commands: <CommandExtension>[nativeDriverCommands],
+  );
+  runApp(const SizedBox());
+}

dev/integration_tests/android_engine_test/test_driver/engine_handle_test.dart

@@ -0,0 +1,37 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:convert';
+
+import 'package:android_driver_extensions/native_driver.dart';
+import 'package:flutter_driver/flutter_driver.dart';
+import 'package:test/test.dart';
+
+late final FlutterDriver flutterDriver;
+late final NativeDriver nativeDriver;
+
+void main() async {
+  setUpAll(() async {
+    flutterDriver = await FlutterDriver.connect();
+    nativeDriver = await AndroidNativeDriver.connect(flutterDriver);
+  });
+
+  tearDownAll(() async {
+    await nativeDriver.close();
+    await flutterDriver.close();
+  });
+
+  // TODO(matanlurey): Convert to use package:integration_test
+  test('verify that engineId is set and works', () async {
+    final Map<String, Object?> response =
+        json.decode(await flutterDriver.requestData('')) as Map<String, Object?>;
+    expect(
+      response['engineId'],
+      1,
+      // Valid engine ids start at 1 to make detecting uninitialized
+      // values easier.
+      reason: 'engineId of first engine instance should be 1',
+    );
+  }, timeout: Timeout.none);
+}

engine/src/flutter/lib/ui/hooks.dart

@@ -68,6 +68,11 @@ void _sendViewFocusEvent(int viewId, int viewFocusState, int viewFocusDirection)
   PlatformDispatcher.instance._sendViewFocusEvent(viewFocusEvent);
 }
 
+@pragma('vm:entry-point')
+void _setEngineId(int engineId) {
+  PlatformDispatcher.instance._engineId = engineId;
+}
+
 @pragma('vm:entry-point')
 void _updateDisplays(
   List<int> ids,

engine/src/flutter/lib/ui/platform_dispatcher.dart

@@ -305,6 +305,13 @@ class PlatformDispatcher {
     _invoke1<ViewFocusEvent>(onViewFocusChange, _onViewFocusChangeZone, event);
   }
 
+  /// Opaque engine identifier for the engine running current isolate. Can be used
+  /// in native code to retrieve the engine instance.
+  /// The identifier is valid while the isolate is running.
+  int? get engineId => _engineId;
+
+  int? _engineId;
+
   // Called from the engine, via hooks.dart.
   //
   // Updates the available displays.

engine/src/flutter/lib/ui/window/platform_configuration.cc

@@ -49,6 +49,8 @@ void PlatformConfiguration::DidCreateIsolate() {
   send_view_focus_event_.Set(
       tonic::DartState::Current(),
       Dart_GetField(library, tonic::ToDart("_sendViewFocusEvent")));
+  set_engine_id_.Set(tonic::DartState::Current(),
+                     Dart_GetField(library, tonic::ToDart("_setEngineId")));
   update_window_metrics_.Set(
       tonic::DartState::Current(),
       Dart_GetField(library, tonic::ToDart("_updateWindowMetrics")));
@@ -168,6 +170,20 @@ bool PlatformConfiguration::SendFocusEvent(const ViewFocusEvent& event) {
   return true;
 }
 
+bool PlatformConfiguration::SetEngineId(int64_t engine_id) {
+  std::shared_ptr<tonic::DartState> dart_state =
+      set_engine_id_.dart_state().lock();
+  if (!dart_state) {
+    return false;
+  }
+  tonic::DartState::Scope scope(dart_state);
+  tonic::CheckAndHandleError(
+      tonic::DartInvoke(set_engine_id_.Get(), {
+                                                  tonic::ToDart(engine_id),
+                                              }));
+  return true;
+}
+
 bool PlatformConfiguration::UpdateViewMetrics(
     int64_t view_id,
     const ViewportMetrics& view_metrics) {

engine/src/flutter/lib/ui/window/platform_configuration.h

@@ -356,6 +356,14 @@ class PlatformConfiguration final {
   /// @return     Whether the focus event was sent.
   bool SendFocusEvent(const ViewFocusEvent& event);
 
+  /// @brief     Sets the opaque identifier of the engine.
+  ///
+  ///            The identifier can be passed from Dart to native code to
+  ///            retrieve the engine instance.
+  ///
+  /// @return    Whether the identifier was set.
+  bool SetEngineId(int64_t engine_id);
+
   //----------------------------------------------------------------------------
   /// @brief      Update the view metrics for the specified view.
   ///
@@ -548,6 +556,7 @@ class PlatformConfiguration final {
   tonic::DartPersistentValue add_view_;
   tonic::DartPersistentValue remove_view_;
   tonic::DartPersistentValue send_view_focus_event_;
+  tonic::DartPersistentValue set_engine_id_;
   tonic::DartPersistentValue update_window_metrics_;
   tonic::DartPersistentValue update_displays_;
   tonic::DartPersistentValue update_locales_;

engine/src/flutter/lib/web_ui/lib/platform_dispatcher.dart

@@ -37,6 +37,8 @@ abstract class PlatformDispatcher {
 
   FlutterView? get implicitView;
 
+  int? get engineId;
+
   VoidCallback? get onMetricsChanged;
   set onMetricsChanged(VoidCallback? callback);
 

engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher.dart

@@ -140,6 +140,9 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
   @override
   EngineFlutterWindow? get implicitView => viewManager[kImplicitViewId] as EngineFlutterWindow?;
 
+  @override
+  int? get engineId => null;
+
   /// A callback that is invoked whenever the platform's [devicePixelRatio],
   /// [physicalSize], [padding], [viewInsets], or [systemGestureInsets]
   /// values change, for example when the device is rotated or when the

engine/src/flutter/runtime/runtime_controller.cc

@@ -537,7 +537,8 @@ bool RuntimeController::LaunchRootIsolate(
     std::optional<std::string> dart_entrypoint_library,
     const std::vector<std::string>& dart_entrypoint_args,
     std::unique_ptr<IsolateConfiguration> isolate_configuration,
-    std::shared_ptr<NativeAssetsManager> native_assets_manager) {
+    std::shared_ptr<NativeAssetsManager> native_assets_manager,
+    std::optional<int64_t> engine_id) {
   if (root_isolate_.lock()) {
     FML_LOG(ERROR) << "Root isolate was already running.";
     return false;
@@ -586,6 +587,11 @@ bool RuntimeController::LaunchRootIsolate(
     if (!FlushRuntimeStateToIsolate()) {
       FML_DLOG(ERROR) << "Could not set up initial isolate state.";
     }
+    if (engine_id) {
+      if (!platform_configuration->SetEngineId(*engine_id)) {
+        FML_DLOG(ERROR) << "Could not set engine identifier.";
+      }
+    }
   } else {
     FML_DCHECK(false) << "RuntimeController created without window binding.";
   }

engine/src/flutter/runtime/runtime_controller.h

@@ -156,6 +156,8 @@ class RuntimeController : public PlatformConfigurationClient,
   /// @param[in]  dart_entrypoint_args     Arguments passed as a List<String>
   ///                                      to Dart's entrypoint function.
   /// @param[in]  isolate_configuration    The isolate configuration
+  /// @param[in]  engine_id.               Engine identifier to be passed to the
+  ///                                      platform dispatcher.
   ///
   /// @return     If the isolate could be launched and guided to the
   ///             `DartIsolate::Phase::Running` phase.
@@ -167,7 +169,8 @@ class RuntimeController : public PlatformConfigurationClient,
       std::optional<std::string> dart_entrypoint_library,
       const std::vector<std::string>& dart_entrypoint_args,
       std::unique_ptr<IsolateConfiguration> isolate_configuration,
-      std::shared_ptr<NativeAssetsManager> native_assets_manager);
+      std::shared_ptr<NativeAssetsManager> native_assets_manager,
+      std::optional<int64_t> engine_id);
 
   //----------------------------------------------------------------------------
   /// @brief      Clone the runtime controller. Launching an isolate with a