added docstrings

Author: gaaclarke

shell/common/platform_message_handler.h

@@ -10,15 +10,25 @@
 #include "flutter/lib/ui/window/platform_message.h"
 
 namespace flutter {
+
+/// An interface over the ability to handle PlatformMessages that are being sent
+/// from Flutter to the host platform.
 class PlatformMessageHandler {
  public:
   virtual ~PlatformMessageHandler() = default;
+
+  /// Ultimately sends the PlatformMessage to the host platform.
   virtual void HandlePlatformMessage(
       std::unique_ptr<PlatformMessage> message) = 0;
+
+  /// Performs the return procedure for an associated call to
+  /// HandlePlatformMessage.
   virtual void InvokePlatformMessageResponseCallback(
       int response_id,
       std::unique_ptr<fml::Mapping> mapping) = 0;
 
+  /// Performs the return procedure for an associated call to
+  /// HandlePlatformMessage where there is no return value.
   virtual void InvokePlatformMessageEmptyResponseCallback(int response_id) = 0;
 };
 }  // namespace flutter

shell/common/platform_view.cc

@@ -184,4 +184,9 @@ PlatformView::CreateSnapshotSurfaceProducer() {
   return nullptr;
 }
 
+std::shared_ptr<PlatformMessageHandler>
+PlatformView::GetPlatformMessageHandler() const {
+  return nullptr;
+}
+
 }  // namespace flutter

shell/common/platform_view.h

@@ -811,11 +811,16 @@ class PlatformView {
   virtual std::unique_ptr<SnapshotSurfaceProducer>
   CreateSnapshotSurfaceProducer();
 
-  // Returning nullptr means send message to the PlatformView.
+  //--------------------------------------------------------------------------
+  /// @brief Specifies a delegate that will receive PlatformMessages from
+  /// Flutter to the host platform.
+  ///
+  /// @details If this returns `null` that means PlatformMessages should be sent
+  /// to the PlatformView.  That is to protect legacy behavior, any embedder
+  /// that wants to support executing Platform Channel handlers on background
+  /// threads should be returing a thread-safe PlatformMessageHandler instead.
   virtual std::shared_ptr<PlatformMessageHandler> GetPlatformMessageHandler()
-      const {
-    return nullptr;
-  }
+      const;
 
  protected:
   PlatformView::Delegate& delegate_;

shell/common/shell.cc

@@ -1872,4 +1872,9 @@ fml::TimePoint Shell::GetCurrentTimePoint() {
   return fml::TimePoint::Now();
 }
 
+const std::shared_ptr<PlatformMessageHandler>&
+Shell::GetPlatformMessageHandler() const {
+  return platform_message_handler_;
+}
+
 }  // namespace flutter

shell/common/shell.h

@@ -395,10 +395,11 @@ class Shell final : public PlatformView::Delegate,
   /// @see        `CreateCompatibleGenerator`
   void RegisterImageDecoder(ImageGeneratorFactory factory, int32_t priority);
 
+  //----------------------------------------------------------------------------
+  /// @brief Returns the delegate object that handles PlatformMessage's from
+  ///        Flutter to the host platform (and its responses).
   const std::shared_ptr<PlatformMessageHandler>& GetPlatformMessageHandler()
-      const {
-    return platform_message_handler_;
-  }
+      const;
 
  private:
   using ServiceProtocolHandler =

shell/platform/android/io/flutter/embedding/engine/FlutterJNI.java

@@ -877,6 +877,13 @@ public void setPlatformMessageHandler(@Nullable PlatformMessageHandler platformM
 
   private native void nativeCleanupMessageData(long messageData);
 
+  /**
+   * Destroys the resources provided sent to `handlePlatformMessage`.
+   *
+   * <p>This can be called on any thread.
+   *
+   * @param messageData the argument sent to handlePlatformMessage.
+   */
   public void cleanupMessageData(long messageData) {
     // This doesn't rely on being attached like other methods.
     nativeCleanupMessageData(messageData);

shell/platform/android/io/flutter/embedding/engine/dart/DartMessenger.java

@@ -25,7 +25,7 @@
  *
  * <p>See {@link PlatformMessageHandler}, which handles messages to Android from Dart
  */
-public class DartMessenger implements BinaryMessenger, PlatformMessageHandler {
+class DartMessenger implements BinaryMessenger, PlatformMessageHandler {
   private static final String TAG = "DartMessenger";
 
   @NonNull private final FlutterJNI flutterJNI;

shell/platform/android/io/flutter/embedding/engine/dart/PlatformTaskQueue.java

@@ -9,6 +9,7 @@
 import androidx.annotation.NonNull;
 import io.flutter.plugin.common.BinaryMessenger;
 
+/** A BinaryMessenger.TaskQueue that posts to the platform thread (aka main thread). */
 public class PlatformTaskQueue implements BinaryMessenger.TaskQueue {
   @NonNull private final Handler handler = new Handler(Looper.getMainLooper());
 

shell/platform/android/io/flutter/plugin/common/BasicMessageChannel.java

@@ -36,6 +36,7 @@ public final class BasicMessageChannel<T> {
   @NonNull private final BinaryMessenger messenger;
   @NonNull private final String name;
   @NonNull private final MessageCodec<T> codec;
+  @Nullable private final BinaryMessenger.TaskQueue taskQueue;
 
   /**
    * Creates a new channel associated with the specified {@link BinaryMessenger} and with the
@@ -47,6 +48,24 @@ public final class BasicMessageChannel<T> {
    */
   public BasicMessageChannel(
       @NonNull BinaryMessenger messenger, @NonNull String name, @NonNull MessageCodec<T> codec) {
+    this(messenger, name, codec, null);
+  }
+
+  /**
+   * Creates a new channel associated with the specified {@link BinaryMessenger} and with the
+   * specified name and {@link MessageCodec}.
+   *
+   * @param messenger a {@link BinaryMessenger}.
+   * @param name a channel name String.
+   * @param codec a {@link MessageCodec}.
+   * @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
+   *     the handler. Specifying null mean execute on the platform thread.
+   */
+  public BasicMessageChannel(
+      @NonNull BinaryMessenger messenger,
+      @NonNull String name,
+      @NonNull MessageCodec<T> codec,
+      BinaryMessenger.TaskQueue taskQueue) {
     if (BuildConfig.DEBUG) {
       if (messenger == null) {
         Log.e(TAG, "Parameter messenger must not be null.");
@@ -61,6 +80,7 @@ public BasicMessageChannel(
     this.messenger = messenger;
     this.name = name;
     this.codec = codec;
+    this.taskQueue = taskQueue;
   }
 
   /**
@@ -102,7 +122,7 @@ public void send(@Nullable T message, @Nullable final Reply<T> callback) {
   @UiThread
   public void setMessageHandler(@Nullable final MessageHandler<T> handler) {
     messenger.setMessageHandler(
-        name, handler == null ? null : new IncomingMessageHandler(handler), null);
+        name, handler == null ? null : new IncomingMessageHandler(handler), taskQueue);
   }
 
   /**

shell/platform/android/io/flutter/plugin/common/BinaryMessenger.java

@@ -26,6 +26,7 @@
  * @see EventChannel , which supports communication using event streams.
  */
 public interface BinaryMessenger {
+  /** An abstraction over dispatching a Runnable to be executed on some thread. */
   public interface TaskQueue {
     void dispatch(@NonNull Runnable runnable);
   }
@@ -69,6 +70,8 @@ public interface TaskQueue {
    *
    * @param channel the name {@link String} of the channel.
    * @param handler a {@link BinaryMessageHandler} to be invoked on incoming messages, or null.
+   * @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
+   *     the handler. Specifying null mean execute on the platform thread.
    */
   @UiThread
   void setMessageHandler(

shell/platform/android/io/flutter/plugin/common/EventChannel.java

@@ -4,6 +4,7 @@
 
 package io.flutter.plugin.common;
 
+import androidx.annotation.Nullable;
 import androidx.annotation.UiThread;
 import io.flutter.BuildConfig;
 import io.flutter.Log;
@@ -34,6 +35,7 @@ public final class EventChannel {
   private final BinaryMessenger messenger;
   private final String name;
   private final MethodCodec codec;
+  @Nullable private final BinaryMessenger.TaskQueue taskQueue;
 
   /**
    * Creates a new channel associated with the specified {@link BinaryMessenger} and with the
@@ -55,6 +57,24 @@ public EventChannel(BinaryMessenger messenger, String name) {
    * @param codec a {@link MessageCodec}.
    */
   public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
+    this(messenger, name, codec, null);
+  }
+
+  /**
+   * Creates a new channel associated with the specified {@link BinaryMessenger} and with the
+   * specified name and {@link MethodCodec}.
+   *
+   * @param messenger a {@link BinaryMessenger}.
+   * @param name a channel name String.
+   * @param codec a {@link MessageCodec}.
+   * @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
+   *     the handler. Specifying null mean execute on the platform thread.
+   */
+  public EventChannel(
+      BinaryMessenger messenger,
+      String name,
+      MethodCodec codec,
+      BinaryMessenger.TaskQueue taskQueue) {
     if (BuildConfig.DEBUG) {
       if (messenger == null) {
         Log.e(TAG, "Parameter messenger must not be null.");
@@ -69,6 +89,7 @@ public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
     this.messenger = messenger;
     this.name = name;
     this.codec = codec;
+    this.taskQueue = taskQueue;
   }
 
   /**
@@ -84,7 +105,7 @@ public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
   @UiThread
   public void setStreamHandler(final StreamHandler handler) {
     messenger.setMessageHandler(
-        name, handler == null ? null : new IncomingStreamRequestHandler(handler), null);
+        name, handler == null ? null : new IncomingStreamRequestHandler(handler), taskQueue);
   }
 
   /**

shell/platform/android/io/flutter/plugin/common/MethodChannel.java

@@ -60,6 +60,16 @@ public MethodChannel(BinaryMessenger messenger, String name, MethodCodec codec)
     this(messenger, name, codec, null);
   }
 
+  /**
+   * Creates a new channel associated with the specified {@link BinaryMessenger} and with the
+   * specified name and {@link MethodCodec}.
+   *
+   * @param messenger a {@link BinaryMessenger}.
+   * @param name a channel name String.
+   * @param codec a {@link MessageCodec}.
+   * @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
+   *     the handler. Specifying null mean execute on the platform thread.
+   */
   public MethodChannel(
       BinaryMessenger messenger,
       String name,