Package io.flutter.embedding.engine.dart

Class DartExecutor

java.lang.Object
io.flutter.embedding.engine.dart.DartExecutor
All Implemented Interfaces:
BinaryMessenger
public class DartExecutor extends Object implements BinaryMessenger
Configures, bootstraps, and starts executing Dart code.

To specify a top-level Dart function to execute, use a DartExecutor.DartEntrypoint to tell DartExecutor where to find the Dart code to execute, and which Dart function to use as the entrypoint. To execute the entrypoint, pass the DartExecutor.DartEntrypoint to executeDartEntrypoint(DartEntrypoint).

To specify a Dart callback to execute, use a DartExecutor.DartCallback. A given Dart callback must be registered with the Dart VM to be invoked by a DartExecutor. To execute the callback, pass the DartExecutor.DartCallback to executeDartCallback(DartCallback).

Once started, a DartExecutor cannot be stopped. The associated Dart code will execute until it completes, or until the FlutterEngine that owns this DartExecutor is destroyed.

  • Constructor Details

    • DartExecutor

      @VisibleForTesting public DartExecutor(@NonNull FlutterJNI flutterJNI, @NonNull AssetManager assetManager)

    • DartExecutor

      public DartExecutor(@NonNull FlutterJNI flutterJNI, @NonNull AssetManager assetManager, long engineId)

  • Method Details

    • onAttachedToJNI

      public void onAttachedToJNI()
      Invoked when the FlutterEngine that owns this DartExecutor attaches to JNI.

      When attached to JNI, this DartExecutor begins handling 2-way communication to/from the Dart execution context. This communication is facilitate via 2 APIs:

    • onDetachedFromJNI

      public void onDetachedFromJNI()
      Invoked when the FlutterEngine that owns this DartExecutor detaches from JNI.

      When detached from JNI, this DartExecutor stops handling 2-way communication to/from the Dart execution context.

    • isExecutingDart

      public boolean isExecutingDart()
      Is this DartExecutor currently executing Dart code?
      Returns:
      true if Dart code is being executed, false otherwise

    • executeDartEntrypoint

      public void executeDartEntrypoint(@NonNull DartExecutor.DartEntrypoint dartEntrypoint)
      Starts executing Dart code based on the given dartEntrypoint.

      See DartExecutor.DartEntrypoint for configuration options.

      Parameters:
      dartEntrypoint - specifies which Dart function to run, and where to find it

    • executeDartEntrypoint

      public void executeDartEntrypoint(@NonNull DartExecutor.DartEntrypoint dartEntrypoint, @Nullable List<String> dartEntrypointArgs)
      Starts executing Dart code based on the given dartEntrypoint and the dartEntrypointArgs.

      See DartExecutor.DartEntrypoint for configuration options.

      Parameters:
      dartEntrypoint - specifies which Dart function to run, and where to find it
      dartEntrypointArgs - Arguments passed as a list of string to Dart's entrypoint function.

    • executeDartCallback

      public void executeDartCallback(@NonNull DartExecutor.DartCallback dartCallback)
      Starts executing Dart code based on the given dartCallback.

      See DartExecutor.DartCallback for configuration options.

      Parameters:
      dartCallback - specifies which Dart callback to run, and where to find it

    • getBinaryMessenger

      @NonNull public BinaryMessenger getBinaryMessenger()
      Returns a BinaryMessenger that can be used to send messages to, and receive messages from, Dart code that this DartExecutor is executing.

    • makeBackgroundTaskQueue

      @Deprecated @UiThread public BinaryMessenger.TaskQueue makeBackgroundTaskQueue(BinaryMessenger.TaskQueueOptions options)
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Creates a TaskQueue that executes the tasks serially on a background thread.

      BinaryMessenger.TaskQueueOptions can be used to configure the task queue to execute tasks concurrently. Doing so can be more performant, though users need to ensure that the task handlers are thread-safe.

      Specified by:
      makeBackgroundTaskQueue in interface BinaryMessenger

    • send

      @Deprecated @UiThread public void send(@NonNull String channel, @Nullable ByteBuffer message)
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Sends a binary message to the Flutter application.
      Specified by:
      send in interface BinaryMessenger
      Parameters:
      channel - the name String of the logical channel used for the message.
      message - the message payload, a direct-allocated ByteBuffer with the message bytes between position zero and current position, or null.

    • send

      @Deprecated @UiThread public void send(@NonNull String channel, @Nullable ByteBuffer message, @Nullable BinaryMessenger.BinaryReply callback)
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Sends a binary message to the Flutter application, optionally expecting a reply.

      Any uncaught exception thrown by the reply callback will be caught and logged.

      Specified by:
      send in interface BinaryMessenger
      Parameters:
      channel - the name String of the logical channel used for the message.
      message - the message payload, a direct-allocated ByteBuffer with the message bytes between position zero and current position, or null.
      callback - a BinaryMessenger.BinaryReply callback invoked when the Flutter application responds to the message, possibly null.

    • setMessageHandler

      @Deprecated @UiThread public void setMessageHandler(@NonNull String channel, @Nullable BinaryMessenger.BinaryMessageHandler handler)
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Registers a handler to be invoked when the Flutter application sends a message to its host platform.

      Registration overwrites any previous registration for the same channel name. Use a null handler to deregister.

      If no handler has been registered for a particular channel, any incoming message on that channel will be handled silently by sending a null reply.

      Specified by:
      setMessageHandler in interface BinaryMessenger
      Parameters:
      channel - the name String of the channel.
      handler - a BinaryMessenger.BinaryMessageHandler to be invoked on incoming messages, or null.

    • setMessageHandler

      @Deprecated @UiThread public void setMessageHandler(@NonNull String channel, @Nullable BinaryMessenger.BinaryMessageHandler handler, @Nullable BinaryMessenger.TaskQueue taskQueue)
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Registers a handler to be invoked when the Flutter application sends a message to its host platform.

      Registration overwrites any previous registration for the same channel name. Use a null handler to deregister.

      If no handler has been registered for a particular channel, any incoming message on that channel will be handled silently by sending a null reply.

      Specified by:
      setMessageHandler in interface BinaryMessenger
      Parameters:
      channel - the name String of the channel.
      handler - a BinaryMessenger.BinaryMessageHandler to be invoked on incoming messages, or null.
      taskQueue - a BinaryMessenger.TaskQueue that specifies what thread will execute the handler. Specifying null means execute on the platform thread.

    • enableBufferingIncomingMessages

      @Deprecated public void enableBufferingIncomingMessages()
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Enables the ability to queue messages received from Dart.

      This is useful when there are pending channel handler registrations. For example, Dart may be initialized concurrently, and prior to the registration of the channel handlers. This implies that Dart may start sending messages while plugins are being registered.

      Specified by:
      enableBufferingIncomingMessages in interface BinaryMessenger

    • disableBufferingIncomingMessages

      @Deprecated public void disableBufferingIncomingMessages()
      Deprecated.
      Use getBinaryMessenger() instead.
      Description copied from interface: BinaryMessenger
      Disables the ability to queue messages received from Dart.

      This can be used after all pending channel handlers have been registered.

      Specified by:
      disableBufferingIncomingMessages in interface BinaryMessenger

    • getPendingChannelResponseCount

      @UiThread public int getPendingChannelResponseCount()
      Returns the number of pending channel callback replies.

      When sending messages to the Flutter application using BinaryMessenger.send(String, ByteBuffer, io.flutter.plugin.common.BinaryMessenger.BinaryReply), developers can optionally specify a reply callback if they expect a reply from the Flutter application.

      This method tracks all the pending callbacks that are waiting for response, and is supposed to be called from the main thread (as other methods). Calling from a different thread could possibly capture an indeterministic internal state, so don't do it.

      Currently, it's mainly useful for a testing framework like Espresso to determine whether all the async channel callbacks are handled and the app is idle.

    • getIsolateServiceId

      @Nullable public String getIsolateServiceId()
      Returns an identifier for this executor's primary isolate. This identifier can be used in queries to the Dart service protocol.

    • setIsolateServiceIdListener

      public void setIsolateServiceIdListener(@Nullable DartExecutor.IsolateServiceIdListener listener)
      Set a listener that will be notified when an isolate identifier is available for this executor's primary isolate.

    • notifyLowMemoryWarning

      public void notifyLowMemoryWarning()
      Notify the Dart VM of a low memory event, or that the application is in a state such that now is an appropriate time to free resources, such as going to the background.

      This does not notify a Flutter application about memory pressure. For that, use the SystemChannel.sendMemoryPressureWarning().

      Calling this method may cause jank or latency in the application. Avoid calling it during critical periods like application startup or periods of animation.