ChannelBuffers class Null safety

The buffering and dispatch mechanism for messages sent by plugins on the engine side to their corresponding plugin code on the framework side.

Messages for a channel are stored until a listener is provided for that channel, using setListener. Only one listener may be configured per channel.

Typically these buffers are drained once a callback is set up on the BinaryMessenger in the Flutter framework. (See setListener.)

Buffer capacity and overflow

Each channel has a finite buffer capacity and messages will be deleted in a first-in-first-out (FIFO) manner if the capacity is exceeded.

By default buffers store one message per channel, and when a message overflows, in debug mode, a message is printed to the console. The message looks like the following:

A message on the com.example channel was discarded before it could be
handled.
This happens when a plugin sends messages to the framework side before the
framework has had an opportunity to register a listener. See the
ChannelBuffers API documentation for details on how to configure the channel
to expect more messages, or to expect messages to get discarded:
  https://api.flutter.cn/flutter/dart-ui/ChannelBuffers-class.html

There are tradeoffs associated with any size. The correct size should be chosen for the semantics of the channel. To change the size a plugin can send a message using the control channel, as described below.

Size 0 is appropriate for channels where channels sent before the engine and framework are ready should be ignored. For example, a plugin that notifies the framework any time a radiation sensor detects an ionization event might set its size to zero since past ionization events are typically not interesting, only instantaneous readings are worth tracking.

Size 1 is appropriate for level-triggered plugins. For example, a plugin that notifies the framework of the current value of a pressure sensor might leave its size at one (the default), while sending messages continually; once the framework side of the plugin registers with the channel, it will immediately receive the most up to date value and earlier messages will have been discarded.

Sizes greater than one are appropriate for plugins where every message is important. For example, a plugin that itself registers with another system that has been buffering events, and immediately forwards all the previously-buffered events, would likely wish to avoid having any messages dropped on the floor. In such situations, it is important to select a size that will avoid overflows. It is also important to consider the potential for the framework side to never fully initialize (e.g. if the user starts the application, but terminates it soon afterwards, leaving time for the platform side of a plugin to run but not the framework side).

The control channel

A plugin can configure its channel's buffers by sending messages to the control channel, dev.flutter/channel-buffers (see kControlChannelName).

There are two messages that can be sent to this control channel, to adjust the buffer size and to disable the overflow warnings. See handleMessage for details on these messages.

Constructors

ChannelBuffers()
Create a buffer pool for platform messages. [...]

Properties

hashCode int
The hash code for this object. [...]
read-only, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

allowOverflow(String name, bool allowed) → void
Toggles whether the channel should show warning messages when discarding messages due to overflow. [...]
clearListener(String name) → void
Clears the listener for the specified channel. [...]
drain(String name, DrainChannelCallback callback) Future<void>
Remove and process all stored messages for a given channel. [...]
handleMessage(ByteData data) → void
Handle a control message. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
push(String name, ByteData? data, PlatformMessageResponseCallback callback) → void
Adds a message (data) to the named channel buffer (name). [...]
resize(String name, int newSize) → void
Changes the capacity of the queue associated with the given channel. [...]
setListener(String name, ChannelCallback callback) → void
Sets the listener for the specified channel. [...]
toString() String
A string representation of this object. [...]
inherited

Operators

operator ==(Object other) bool
The equality operator. [...]
inherited

Constants

kControlChannelName → const String
The name of the channel that plugins can use to communicate with the channel buffers system. [...]
'dev.flutter/channel-buffers'
kDefaultBufferSize → const int
The number of messages that channel buffers will store by default.
1