Skip to content
This repository was archived by the owner on Feb 25, 2025. It is now read-only.

Commit 734f5d8

Browse files
committed
added docstrings
1 parent 30ca22e commit 734f5d8

File tree

12 files changed

+98
-10
lines changed

12 files changed

+98
-10
lines changed

shell/common/platform_message_handler.h

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,25 @@
1010
#include "flutter/lib/ui/window/platform_message.h"
1111

1212
namespace flutter {
13+
14+
/// An interface over the ability to handle PlatformMessages that are being sent
15+
/// from Flutter to the host platform.
1316
class PlatformMessageHandler {
1417
public:
1518
virtual ~PlatformMessageHandler() = default;
19+
20+
/// Ultimately sends the PlatformMessage to the host platform.
1621
virtual void HandlePlatformMessage(
1722
std::unique_ptr<PlatformMessage> message) = 0;
23+
24+
/// Performs the return procedure for an associated call to
25+
/// HandlePlatformMessage.
1826
virtual void InvokePlatformMessageResponseCallback(
1927
int response_id,
2028
std::unique_ptr<fml::Mapping> mapping) = 0;
2129

30+
/// Performs the return procedure for an associated call to
31+
/// HandlePlatformMessage where there is no return value.
2232
virtual void InvokePlatformMessageEmptyResponseCallback(int response_id) = 0;
2333
};
2434
} // namespace flutter

shell/common/platform_view.cc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,4 +184,9 @@ PlatformView::CreateSnapshotSurfaceProducer() {
184184
return nullptr;
185185
}
186186

187+
std::shared_ptr<PlatformMessageHandler>
188+
PlatformView::GetPlatformMessageHandler() const {
189+
return nullptr;
190+
}
191+
187192
} // namespace flutter

shell/common/platform_view.h

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -811,11 +811,16 @@ class PlatformView {
811811
virtual std::unique_ptr<SnapshotSurfaceProducer>
812812
CreateSnapshotSurfaceProducer();
813813

814-
// Returning nullptr means send message to the PlatformView.
814+
//--------------------------------------------------------------------------
815+
/// @brief Specifies a delegate that will receive PlatformMessages from
816+
/// Flutter to the host platform.
817+
///
818+
/// @details If this returns `null` that means PlatformMessages should be sent
819+
/// to the PlatformView. That is to protect legacy behavior, any embedder
820+
/// that wants to support executing Platform Channel handlers on background
821+
/// threads should be returing a thread-safe PlatformMessageHandler instead.
815822
virtual std::shared_ptr<PlatformMessageHandler> GetPlatformMessageHandler()
816-
const {
817-
return nullptr;
818-
}
823+
const;
819824

820825
protected:
821826
PlatformView::Delegate& delegate_;

shell/common/shell.cc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1872,4 +1872,9 @@ fml::TimePoint Shell::GetCurrentTimePoint() {
18721872
return fml::TimePoint::Now();
18731873
}
18741874

1875+
const std::shared_ptr<PlatformMessageHandler>&
1876+
Shell::GetPlatformMessageHandler() const {
1877+
return platform_message_handler_;
1878+
}
1879+
18751880
} // namespace flutter

shell/common/shell.h

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -395,10 +395,11 @@ class Shell final : public PlatformView::Delegate,
395395
/// @see `CreateCompatibleGenerator`
396396
void RegisterImageDecoder(ImageGeneratorFactory factory, int32_t priority);
397397

398+
//----------------------------------------------------------------------------
399+
/// @brief Returns the delegate object that handles PlatformMessage's from
400+
/// Flutter to the host platform (and its responses).
398401
const std::shared_ptr<PlatformMessageHandler>& GetPlatformMessageHandler()
399-
const {
400-
return platform_message_handler_;
401-
}
402+
const;
402403

403404
private:
404405
using ServiceProtocolHandler =

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -877,6 +877,13 @@ public void setPlatformMessageHandler(@Nullable PlatformMessageHandler platformM
877877

878878
private native void nativeCleanupMessageData(long messageData);
879879

880+
/**
881+
* Destroys the resources provided sent to `handlePlatformMessage`.
882+
*
883+
* <p>This can be called on any thread.
884+
*
885+
* @param messageData the argument sent to handlePlatformMessage.
886+
*/
880887
public void cleanupMessageData(long messageData) {
881888
// This doesn't rely on being attached like other methods.
882889
nativeCleanupMessageData(messageData);

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
*
2626
* <p>See {@link PlatformMessageHandler}, which handles messages to Android from Dart
2727
*/
28-
public class DartMessenger implements BinaryMessenger, PlatformMessageHandler {
28+
class DartMessenger implements BinaryMessenger, PlatformMessageHandler {
2929
private static final String TAG = "DartMessenger";
3030

3131
@NonNull private final FlutterJNI flutterJNI;

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import androidx.annotation.NonNull;
1010
import io.flutter.plugin.common.BinaryMessenger;
1111

12+
/** A BinaryMessenger.TaskQueue that posts to the platform thread (aka main thread). */
1213
public class PlatformTaskQueue implements BinaryMessenger.TaskQueue {
1314
@NonNull private final Handler handler = new Handler(Looper.getMainLooper());
1415

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

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ public final class BasicMessageChannel<T> {
3636
@NonNull private final BinaryMessenger messenger;
3737
@NonNull private final String name;
3838
@NonNull private final MessageCodec<T> codec;
39+
@Nullable private final BinaryMessenger.TaskQueue taskQueue;
3940

4041
/**
4142
* Creates a new channel associated with the specified {@link BinaryMessenger} and with the
@@ -47,6 +48,24 @@ public final class BasicMessageChannel<T> {
4748
*/
4849
public BasicMessageChannel(
4950
@NonNull BinaryMessenger messenger, @NonNull String name, @NonNull MessageCodec<T> codec) {
51+
this(messenger, name, codec, null);
52+
}
53+
54+
/**
55+
* Creates a new channel associated with the specified {@link BinaryMessenger} and with the
56+
* specified name and {@link MessageCodec}.
57+
*
58+
* @param messenger a {@link BinaryMessenger}.
59+
* @param name a channel name String.
60+
* @param codec a {@link MessageCodec}.
61+
* @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
62+
* the handler. Specifying null mean execute on the platform thread.
63+
*/
64+
public BasicMessageChannel(
65+
@NonNull BinaryMessenger messenger,
66+
@NonNull String name,
67+
@NonNull MessageCodec<T> codec,
68+
BinaryMessenger.TaskQueue taskQueue) {
5069
if (BuildConfig.DEBUG) {
5170
if (messenger == null) {
5271
Log.e(TAG, "Parameter messenger must not be null.");
@@ -61,6 +80,7 @@ public BasicMessageChannel(
6180
this.messenger = messenger;
6281
this.name = name;
6382
this.codec = codec;
83+
this.taskQueue = taskQueue;
6484
}
6585

6686
/**
@@ -102,7 +122,7 @@ public void send(@Nullable T message, @Nullable final Reply<T> callback) {
102122
@UiThread
103123
public void setMessageHandler(@Nullable final MessageHandler<T> handler) {
104124
messenger.setMessageHandler(
105-
name, handler == null ? null : new IncomingMessageHandler(handler), null);
125+
name, handler == null ? null : new IncomingMessageHandler(handler), taskQueue);
106126
}
107127

108128
/**

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
* @see EventChannel , which supports communication using event streams.
2727
*/
2828
public interface BinaryMessenger {
29+
/** An abstraction over dispatching a Runnable to be executed on some thread. */
2930
public interface TaskQueue {
3031
void dispatch(@NonNull Runnable runnable);
3132
}
@@ -69,6 +70,8 @@ public interface TaskQueue {
6970
*
7071
* @param channel the name {@link String} of the channel.
7172
* @param handler a {@link BinaryMessageHandler} to be invoked on incoming messages, or null.
73+
* @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
74+
* the handler. Specifying null mean execute on the platform thread.
7275
*/
7376
@UiThread
7477
void setMessageHandler(

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

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
package io.flutter.plugin.common;
66

7+
import androidx.annotation.Nullable;
78
import androidx.annotation.UiThread;
89
import io.flutter.BuildConfig;
910
import io.flutter.Log;
@@ -34,6 +35,7 @@ public final class EventChannel {
3435
private final BinaryMessenger messenger;
3536
private final String name;
3637
private final MethodCodec codec;
38+
@Nullable private final BinaryMessenger.TaskQueue taskQueue;
3739

3840
/**
3941
* Creates a new channel associated with the specified {@link BinaryMessenger} and with the
@@ -55,6 +57,24 @@ public EventChannel(BinaryMessenger messenger, String name) {
5557
* @param codec a {@link MessageCodec}.
5658
*/
5759
public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
60+
this(messenger, name, codec, null);
61+
}
62+
63+
/**
64+
* Creates a new channel associated with the specified {@link BinaryMessenger} and with the
65+
* specified name and {@link MethodCodec}.
66+
*
67+
* @param messenger a {@link BinaryMessenger}.
68+
* @param name a channel name String.
69+
* @param codec a {@link MessageCodec}.
70+
* @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
71+
* the handler. Specifying null mean execute on the platform thread.
72+
*/
73+
public EventChannel(
74+
BinaryMessenger messenger,
75+
String name,
76+
MethodCodec codec,
77+
BinaryMessenger.TaskQueue taskQueue) {
5878
if (BuildConfig.DEBUG) {
5979
if (messenger == null) {
6080
Log.e(TAG, "Parameter messenger must not be null.");
@@ -69,6 +89,7 @@ public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
6989
this.messenger = messenger;
7090
this.name = name;
7191
this.codec = codec;
92+
this.taskQueue = taskQueue;
7293
}
7394

7495
/**
@@ -84,7 +105,7 @@ public EventChannel(BinaryMessenger messenger, String name, MethodCodec codec) {
84105
@UiThread
85106
public void setStreamHandler(final StreamHandler handler) {
86107
messenger.setMessageHandler(
87-
name, handler == null ? null : new IncomingStreamRequestHandler(handler), null);
108+
name, handler == null ? null : new IncomingStreamRequestHandler(handler), taskQueue);
88109
}
89110

90111
/**

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,16 @@ public MethodChannel(BinaryMessenger messenger, String name, MethodCodec codec)
6060
this(messenger, name, codec, null);
6161
}
6262

63+
/**
64+
* Creates a new channel associated with the specified {@link BinaryMessenger} and with the
65+
* specified name and {@link MethodCodec}.
66+
*
67+
* @param messenger a {@link BinaryMessenger}.
68+
* @param name a channel name String.
69+
* @param codec a {@link MessageCodec}.
70+
* @param taskQueue a {@link BinaryMessenger.TaskQueue} that specifies what thread will execute
71+
* the handler. Specifying null mean execute on the platform thread.
72+
*/
6373
public MethodChannel(
6474
BinaryMessenger messenger,
6575
String name,

0 commit comments

Comments
 (0)