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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `DartExecutor.DartCallback` | Configuration options that specify which Dart callback function is executed and where to find that callback and other assets required for Dart execution.
    `static class` | `DartExecutor.DartEntrypoint` | Configuration options that specify which Dart entrypoint function is executed and where to find that entrypoint and other assets required for Dart execution.
    `static interface` | `DartExecutor.IsolateServiceIdListener` | Callback interface invoked when the isolate identifier becomes available.

    - ### Nested classes/interfaces inherited from interface io.flutter.plugin.common.BinaryMessenger

      `BinaryMessenger.BinaryMessageHandler, BinaryMessenger.BinaryReply, BinaryMessenger.TaskQueue, BinaryMessenger.TaskQueueOptions`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DartExecutor​(FlutterJNI flutterJNI, AssetManager assetManager)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `disableBufferingIncomingMessages()` | Deprecated. Use `getBinaryMessenger()` instead.
    `void` | `enableBufferingIncomingMessages()` | Deprecated. Use `getBinaryMessenger()` instead.
    `void` | `executeDartCallback​(DartExecutor.DartCallback dartCallback)` | Starts executing Dart code based on the given `dartCallback`.
    `void` | `executeDartEntrypoint​(DartExecutor.DartEntrypoint dartEntrypoint)` | Starts executing Dart code based on the given `dartEntrypoint`.
    `void` | `executeDartEntrypoint​(DartExecutor.DartEntrypoint dartEntrypoint, List<String> dartEntrypointArgs)` | Starts executing Dart code based on the given `dartEntrypoint` and the `dartEntrypointArgs`.
    `BinaryMessenger` | `getBinaryMessenger()` | Returns a `BinaryMessenger` that can be used to send messages to, and receive messages from, Dart code that this `DartExecutor` is executing.
    `String` | `getIsolateServiceId()` | Returns an identifier for this executor's primary isolate.
    `int` | `getPendingChannelResponseCount()` | Returns the number of pending channel callback replies.
    `boolean` | `isExecutingDart()` | Is this `DartExecutor` currently executing Dart code?
    `BinaryMessenger.TaskQueue` | `makeBackgroundTaskQueue​(BinaryMessenger.TaskQueueOptions options)` | Deprecated. Use `getBinaryMessenger()` instead.
    `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.
    `void` | `onAttachedToJNI()` | Invoked when the `FlutterEngine` that owns this `DartExecutor` attaches to JNI.
    `void` | `onDetachedFromJNI()` | Invoked when the `FlutterEngine` that owns this `DartExecutor` detaches from JNI.
    `void` | `send​(String channel, ByteBuffer message)` | Deprecated. Use `getBinaryMessenger()` instead.
    `void` | `send​(String channel, ByteBuffer message, BinaryMessenger.BinaryReply callback)` | Deprecated. Use `getBinaryMessenger()` instead.
    `void` | `setIsolateServiceIdListener​(DartExecutor.IsolateServiceIdListener listener)` | Set a listener that will be notified when an isolate identifier is available for this executor's primary isolate.
    `void` | `setMessageHandler​(String channel, BinaryMessenger.BinaryMessageHandler handler)` | Deprecated. Use `getBinaryMessenger()` instead.
    `void` | `setMessageHandler​(String channel, BinaryMessenger.BinaryMessageHandler handler, BinaryMessenger.TaskQueue taskQueue)` | Deprecated. Use `getBinaryMessenger()` instead.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface io.flutter.plugin.common.BinaryMessenger

      `makeBackgroundTaskQueue`

- - ### Constructor Detail

    - #### DartExecutor

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

  - ### Method Detail

    - #### 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:

      - `BinaryMessenger`, which sends messages to Dart
      - `PlatformMessageHandler`, which receives messages from Dart

    - #### 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.