Document FIFO ordering guarantee (flutter#89441)

Author: LongCatIsLooong

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

@@ -67,8 +67,11 @@ mixin ServicesBinding on BindingBase, SchedulerBinding {
   /// This is used to send messages from the application to the platform, and
   /// keeps track of which handlers have been registered on each channel so
   /// it may dispatch incoming messages to the registered handler.
+  ///
+  /// The default implementation returns a [BinaryMessenger] that delivers the
+  /// messages in the same order in which they are sent.
   BinaryMessenger get defaultBinaryMessenger => _defaultBinaryMessenger;
-  late BinaryMessenger _defaultBinaryMessenger;
+  late final BinaryMessenger _defaultBinaryMessenger;
 
   /// The low level buffering and dispatch mechanism for messages sent by
   /// plugins on the engine side to their corresponding plugin code on
@@ -94,6 +97,11 @@ mixin ServicesBinding on BindingBase, SchedulerBinding {
 
   /// Creates a default [BinaryMessenger] instance that can be used for sending
   /// platform messages.
+  ///
+  /// Many Flutter framework components that communicate with the platform
+  /// assume messages are received by the platform in the same order in which
+  /// they are sent. When overriding this method, be sure the [BinaryMessenger]
+  /// implementation guarantees FIFO delivery.
   @protected
   BinaryMessenger createBinaryMessenger() {
     return const _DefaultBinaryMessenger._();

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

@@ -27,6 +27,10 @@ import 'message_codecs.dart';
 /// The logical identity of the channel is given by its name. Identically named
 /// channels will interfere with each other's communication.
 ///
+/// All [BasicMessageChannel]s provided by the Flutter framework guarantee FIFO
+/// ordering. Applications can assume messages sent via a built-in
+/// [BasicMessageChannel] are delivered in the same order as they're sent.
+///
 /// See: <https://flutter.dev/platform-channels/>
 class BasicMessageChannel<T> {
   /// Creates a [BasicMessageChannel] with the specified [name], [codec] and [binaryMessenger].
@@ -95,6 +99,13 @@ class BasicMessageChannel<T> {
 /// The logical identity of the channel is given by its name. Identically named
 /// channels will interfere with each other's communication.
 ///
+/// {@template flutter.services.method_channel.FIFO}
+/// All [MethodChannel]s provided by the Flutter framework guarantee FIFO
+/// ordering. Applications can assume method calls sent via a built-in
+/// [MethodChannel] are received by the platform plugins in the same order as
+/// they're sent.
+/// {@endtemplate}
+///
 /// See: <https://flutter.dev/platform-channels/>
 class MethodChannel {
   /// Creates a [MethodChannel] with the specified [name].
@@ -412,6 +423,8 @@ class MethodChannel {
 ///
 /// When [invokeMethod] fails to find the platform plugin, it returns null
 /// instead of throwing an exception.
+///
+/// {@macro flutter.services.method_channel.FIFO}
 class OptionalMethodChannel extends MethodChannel {
   /// Creates a [MethodChannel] that ignores missing platform plugins.
   const OptionalMethodChannel(String name, [MethodCodec codec = const StandardMethodCodec(), BinaryMessenger? binaryMessenger])