Reland isolate platform channels with conditional compilation (#111712)

Author: gaaclarke

dev/integration_tests/channels/android/app/src/main/AndroidManifest.xml

@@ -18,6 +18,7 @@ found in the LICENSE file. -->
          Application and put your custom class here. -->
     <application android:name="${applicationName}" android:label="channels" android:icon="@mipmap/ic_launcher">
         <activity android:name=".MainActivity"
+                  android:exported="true"
                   android:launchMode="singleTop"
                   android:theme="@android:style/Theme.Black.NoTitleBar"
                   android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"

dev/integration_tests/channels/android/app/src/main/java/com/yourcompany/channels/MainActivity.java

@@ -29,6 +29,15 @@ public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
     setupMessageHandshake(new BasicMessageChannel<>(dartExecutor, "std-msg", ExtendedStandardMessageCodec.INSTANCE));
     setupMethodHandshake(new MethodChannel(dartExecutor, "json-method", JSONMethodCodec.INSTANCE));
     setupMethodHandshake(new MethodChannel(dartExecutor, "std-method", new StandardMethodCodec(ExtendedStandardMessageCodec.INSTANCE)));
+
+    BasicMessageChannel echoChannel =
+        new BasicMessageChannel(dartExecutor, "std-echo", ExtendedStandardMessageCodec.INSTANCE);
+    echoChannel.setMessageHandler(new BasicMessageChannel.MessageHandler(){
+      @Override
+      public void onMessage(final Object message, final BasicMessageChannel.Reply reply) {
+        reply.reply(message);
+      }
+    });
   }
 
   private <T> void setupMessageHandshake(final BasicMessageChannel<T> channel) {

dev/integration_tests/channels/ios/Runner/AppDelegate.m

@@ -114,7 +114,18 @@ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(
     [FlutterMethodChannel methodChannelWithName:@"std-method"
                                 binaryMessenger:flutterController
                                           codec:[FlutterStandardMethodCodec codecWithReaderWriter:extendedReaderWriter]]];
-  return [super application:application didFinishLaunchingWithOptions:launchOptions];
+
+  [[FlutterBasicMessageChannel
+      messageChannelWithName:@"std-echo"
+             binaryMessenger:flutterController
+                       codec:[FlutterStandardMessageCodec
+                                 codecWithReaderWriter:extendedReaderWriter]]
+      setMessageHandler:^(id message, FlutterReply reply) {
+        reply(message);
+      }];
+
+  return [super application:application
+      didFinishLaunchingWithOptions:launchOptions];
 }
 
 - (void)setupMessagingHandshakeOnChannel:(FlutterBasicMessageChannel*)channel {

dev/integration_tests/channels/lib/main.dart

@@ -173,6 +173,8 @@ class _TestAppState extends State<TestApp> {
     () => basicStringMessageToUnknownChannel(),
     () => basicJsonMessageToUnknownChannel(),
     () => basicStandardMessageToUnknownChannel(),
+    if (Platform.isIOS || Platform.isAndroid)
+      () => basicBackgroundStandardEcho(123),
   ];
   Future<TestStepResult>? _result;
   int _step = 0;

dev/integration_tests/channels/lib/src/basic_messaging.dart

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:isolate';
 
 import 'package:flutter/services.dart';
 
@@ -78,6 +79,41 @@ Future<TestStepResult> basicStandardHandshake(dynamic message) async {
       'Standard >${toString(message)}<', channel, message);
 }
 
+Future<void> _basicBackgroundStandardEchoMain(List<Object> args) async {
+  final SendPort sendPort = args[2] as SendPort;
+  final Object message = args[1];
+  final String name = 'Background Echo >${toString(message)}<';
+  const String description =
+      'Uses a platform channel from a background isolate.';
+  try {
+    BackgroundIsolateBinaryMessenger.ensureInitialized(
+        args[0] as RootIsolateToken);
+    const BasicMessageChannel<dynamic> channel = BasicMessageChannel<dynamic>(
+      'std-echo',
+      ExtendedStandardMessageCodec(),
+    );
+    final Object response = await channel.send(message) as Object;
+
+    final TestStatus testStatus = TestStepResult.deepEquals(message, response)
+        ? TestStatus.ok
+        : TestStatus.failed;
+    sendPort.send(TestStepResult(name, description, testStatus));
+  } catch (ex) {
+    sendPort.send(TestStepResult(name, description, TestStatus.failed,
+        error: ex.toString()));
+  }
+}
+
+Future<TestStepResult> basicBackgroundStandardEcho(Object message) async {
+  final ReceivePort receivePort = ReceivePort();
+  Isolate.spawn(_basicBackgroundStandardEchoMain, <Object>[
+    ServicesBinding.rootIsolateToken!,
+    message,
+    receivePort.sendPort,
+  ]);
+  return await receivePort.first as TestStepResult;
+}
+
 Future<TestStepResult> basicBinaryMessageToUnknownChannel() async {
   const BasicMessageChannel<ByteData?> channel =
       BasicMessageChannel<ByteData?>(

dev/integration_tests/channels/lib/src/test_step.dart

@@ -90,6 +90,8 @@ class TestStepResult {
       ],
     );
   }
+
+  static bool deepEquals(dynamic a, dynamic b) => _deepEquals(a, b);
 }
 
 Future<TestStepResult> resultOfHandshake(

packages/flutter/lib/src/services/_background_isolate_binary_messenger_io.dart

@@ -0,0 +1,97 @@
+// 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:async' show Completer;
+import 'dart:isolate' show ReceivePort;
+import 'dart:ui' as ui;
+
+import 'package:flutter/foundation.dart';
+import 'binary_messenger.dart';
+import 'binding.dart';
+
+/// A [BinaryMessenger] for use on background (non-root) isolates.
+class BackgroundIsolateBinaryMessenger extends BinaryMessenger {
+  BackgroundIsolateBinaryMessenger._();
+
+  final ReceivePort _receivePort = ReceivePort();
+  final Map<int, Completer<ByteData?>> _completers =
+      <int, Completer<ByteData?>>{};
+  int _messageCount = 0;
+
+  /// The existing instance of this class, if any.
+  ///
+  /// Throws if [ensureInitialized] has not been called at least once.
+  static BinaryMessenger get instance {
+    if (_instance == null) {
+      throw StateError(
+          'The BackgroundIsolateBinaryMessenger.instance value is invalid '
+          'until BackgroundIsolateBinaryMessenger.ensureInitialized is '
+          'executed.');
+    }
+    return _instance!;
+  }
+
+  static BinaryMessenger? _instance;
+
+  /// Ensures that [BackgroundIsolateBinaryMessenger.instance] has been initialized.
+  ///
+  /// The argument should be the value obtained from [ServicesBinding.rootIsolateToken]
+  /// on the root isolate.
+  ///
+  /// This function is idempotent (calling it multiple times is harmless but has no effect).
+  static void ensureInitialized(ui.RootIsolateToken token) {
+    if (_instance == null) {
+      ui.PlatformDispatcher.instance.registerBackgroundIsolate(token);
+      final BackgroundIsolateBinaryMessenger portBinaryMessenger =
+          BackgroundIsolateBinaryMessenger._();
+      _instance = portBinaryMessenger;
+      portBinaryMessenger._receivePort.listen((dynamic message) {
+        try {
+          final List<dynamic> args = message as List<dynamic>;
+          final int identifier = args[0] as int;
+          final Uint8List bytes = args[1] as Uint8List;
+          final ByteData byteData = ByteData.sublistView(bytes);
+          portBinaryMessenger._completers
+              .remove(identifier)!
+              .complete(byteData);
+        } catch (exception, stack) {
+          FlutterError.reportError(FlutterErrorDetails(
+            exception: exception,
+            stack: stack,
+            library: 'services library',
+            context:
+                ErrorDescription('during a platform message response callback'),
+          ));
+        }
+      });
+    }
+  }
+
+  @override
+  Future<void> handlePlatformMessage(String channel, ByteData? data,
+      ui.PlatformMessageResponseCallback? callback) {
+    throw UnimplementedError('handlePlatformMessage is deprecated.');
+  }
+
+  @override
+  Future<ByteData?>? send(String channel, ByteData? message) {
+    final Completer<ByteData?> completer = Completer<ByteData?>();
+    _messageCount += 1;
+    final int messageIdentifier = _messageCount;
+    _completers[messageIdentifier] = completer;
+    ui.PlatformDispatcher.instance.sendPortPlatformMessage(
+      channel,
+      message,
+      messageIdentifier,
+      _receivePort.sendPort,
+    );
+    return completer.future;
+  }
+
+  @override
+  void setMessageHandler(String channel, MessageHandler? handler) {
+    throw UnsupportedError(
+        'Background isolates do not support setMessageHandler(). Messages from the host platform always go to the root isolate.');
+  }
+}

packages/flutter/lib/src/services/_background_isolate_binary_messenger_web.dart

@@ -0,0 +1,14 @@
+// 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 'binding.dart';
+
+// ignore: avoid_classes_with_only_static_members
+/// Stand-in for non-web platforms' [BackgroundIsolateBinaryMessenger].
+class BackgroundIsolateBinaryMessenger {
+  /// Throws an [UnsupportedError].
+  static BinaryMessenger get instance {
+    throw UnsupportedError('Isolates not supported on web.');
+  }
+}

packages/flutter/lib/src/services/binding.dart

@@ -19,7 +19,7 @@ import 'service_extensions.dart';
 import 'system_channels.dart';
 import 'text_input.dart';
 
-export 'dart:ui' show ChannelBuffers;
+export 'dart:ui' show ChannelBuffers, RootIsolateToken;
 
 export 'binary_messenger.dart' show BinaryMessenger;
 export 'hardware_keyboard.dart' show HardwareKeyboard, KeyEventManager;
@@ -83,6 +83,15 @@ mixin ServicesBinding on BindingBase, SchedulerBinding {
   BinaryMessenger get defaultBinaryMessenger => _defaultBinaryMessenger;
   late final BinaryMessenger _defaultBinaryMessenger;
 
+  /// A token that represents the root isolate, used for coordinating with background
+  /// isolates.
+  ///
+  /// This property is primarily intended for use with
+  /// [BackgroundIsolateBinaryMessenger.ensureInitialized], which takes a
+  /// [RootIsolateToken] as its argument. The value `null` is returned when
+  /// executed from background isolates.
+  static ui.RootIsolateToken? get rootIsolateToken => ui.RootIsolateToken.instance;
+
   /// The low level buffering and dispatch mechanism for messages sent by
   /// plugins on the engine side to their corresponding plugin code on
   /// the framework side.

packages/flutter/lib/src/services/platform_channel.dart

@@ -7,13 +7,20 @@ import 'dart:developer';
 
 import 'package:flutter/foundation.dart';
 
+import '_background_isolate_binary_messenger_io.dart'
+  if (dart.library.html) '_background_isolate_binary_messenger_web.dart';
+
 import 'binary_messenger.dart';
 import 'binding.dart';
 import 'debug.dart' show debugProfilePlatformChannels;
 import 'message_codec.dart';
 import 'message_codecs.dart';
 
+export '_background_isolate_binary_messenger_io.dart'
+  if (dart.library.html) '_background_isolate_binary_messenger_web.dart';
+
 export 'binary_messenger.dart' show BinaryMessenger;
+export 'binding.dart' show RootIsolateToken;
 export 'message_codec.dart' show MessageCodec, MethodCall, MethodCodec;
 
 bool _debugProfilePlatformChannelsIsRunning = false;
@@ -123,6 +130,12 @@ void _debugRecordDownStream(String channelTypeName, String name,
   _debugLaunchProfilePlatformChannels();
 }
 
+BinaryMessenger _findBinaryMessenger() {
+  return !kIsWeb && ServicesBinding.rootIsolateToken == null
+      ? BackgroundIsolateBinaryMessenger.instance
+      : ServicesBinding.instance.defaultBinaryMessenger;
+}
+
 /// A named channel for communicating with platform plugins using asynchronous
 /// message passing.
 ///
@@ -160,10 +173,14 @@ class BasicMessageChannel<T> {
   /// The message codec used by this channel, not null.
   final MessageCodec<T> codec;
 
-  /// The messenger which sends the bytes for this channel, not null.
+  /// The messenger which sends the bytes for this channel.
+  ///
+  /// On the root isolate or web, this defaults to the
+  /// [ServicesBinding.defaultBinaryMessenger]. In other contexts the default
+  /// value is a [BackgroundIsolateBinaryMessenger] from
+  /// [BackgroundIsolateBinaryMessenger.ensureInitialized].
   BinaryMessenger get binaryMessenger {
-    final BinaryMessenger result =
-        _binaryMessenger ?? ServicesBinding.instance.defaultBinaryMessenger;
+    final BinaryMessenger result = _binaryMessenger ?? _findBinaryMessenger();
     return !kReleaseMode && debugProfilePlatformChannels
         ? _debugBinaryMessengers[this] ??= _ProfiledBinaryMessenger(
             // ignore: no_runtimetype_tostring
@@ -246,12 +263,14 @@ class MethodChannel {
   /// The message codec used by this channel, not null.
   final MethodCodec codec;
 
-  /// The messenger used by this channel to send platform messages.
+  /// The messenger which sends the bytes for this channel.
   ///
-  /// The messenger may not be null.
+  /// On the root isolate or web, this defaults to the
+  /// [ServicesBinding.defaultBinaryMessenger]. In other contexts the default
+  /// value is a [BackgroundIsolateBinaryMessenger] from
+  /// [BackgroundIsolateBinaryMessenger.ensureInitialized].
   BinaryMessenger get binaryMessenger {
-    final BinaryMessenger result =
-        _binaryMessenger ?? ServicesBinding.instance.defaultBinaryMessenger;
+    final BinaryMessenger result = _binaryMessenger ?? _findBinaryMessenger();
     return !kReleaseMode && debugProfilePlatformChannels
         ? _debugBinaryMessengers[this] ??= _ProfiledBinaryMessenger(
             // ignore: no_runtimetype_tostring
@@ -600,8 +619,14 @@ class EventChannel {
   /// The message codec used by this channel, not null.
   final MethodCodec codec;
 
-  /// The messenger used by this channel to send platform messages, not null.
-  BinaryMessenger get binaryMessenger => _binaryMessenger ?? ServicesBinding.instance.defaultBinaryMessenger;
+  /// The messenger which sends the bytes for this channel.
+  ///
+  /// On the root isolate or web, this defaults to the
+  /// [ServicesBinding.defaultBinaryMessenger]. In other contexts the default
+  /// value is a [BackgroundIsolateBinaryMessenger] from
+  /// [BackgroundIsolateBinaryMessenger.ensureInitialized].
+  BinaryMessenger get binaryMessenger =>
+      _binaryMessenger ?? _findBinaryMessenger();
   final BinaryMessenger? _binaryMessenger;
 
   /// Sets up a broadcast stream for receiving events on this channel.