Represents an instance of a live isolate. An isolate is a separate Dart execution context. Different Dart isolates don't share memory and can be scheduled concurrently by the Dart VM on one of the Dart VM managed worker pool threads. More...

#include <dart_isolate.h>

Inheritance diagram for flutter::DartIsolate:

Classes
class	Flags

Public Types
enum class	Phase { Unknown , Uninitialized , Initialized , LibrariesSetup , Ready , Running , Shutdown }
	The engine represents all dart isolates as being in one of the known phases. By invoking various methods on the Dart isolate, the engine transition the Dart isolate from one phase to the next. The Dart isolate will only move from one phase to the next in the order specified in the `DartIsolate::Phase` enum. That is, once the isolate has moved out of a particular phase, it can never transition back to that phase in the future. There is no error recovery mechanism and callers that find their isolates in an undesirable phase must discard the isolate and start over. More...

Public Member Functions
	~DartIsolate () override

Phase	GetPhase () const
	The current phase of the isolate. The engine represents all dart isolates as being in one of the known phases. By invoking various methods on the Dart isolate, the engine transitions the Dart isolate from one phase to the next. The Dart isolate will only move from one phase to the next in the order specified in the `DartIsolate::Phase` enum. That is, the once the isolate has moved out of a particular phase, it can never transition back to that phase in the future. There is no error recovery mechanism and callers that find their isolates in an undesirable phase must discard the isolate and start over.

std::string	GetServiceId ()
	Returns the ID for an isolate which is used to query the service protocol.

bool	PrepareForRunningFromPrecompiledCode ()
	Prepare the isolate for running for a precompiled code bundle. The Dart VM must be configured for running precompiled code.

bool	PrepareForRunningFromKernel (const std::shared_ptr< const fml::Mapping > &kernel, bool child_isolate, bool last_piece)
	Prepare the isolate for running for a a list of kernel files.

bool	PrepareForRunningFromKernels (std::vector< std::shared_ptr< const fml::Mapping > > kernels)
	Prepare the isolate for running for a a list of kernel files.

bool	PrepareForRunningFromKernels (std::vector< std::unique_ptr< const fml::Mapping > > kernels)
	Prepare the isolate for running for a a list of kernel files.

bool	RunFromLibrary (std::optional< std::string > library_name, std::optional< std::string > entrypoint, const std::vector< std::string > &args)
	Transition the root isolate to the `Phase::Running` phase and invoke the main entrypoint (the "main" method) in the specified library. The isolate must already be in the `Phase::Ready` phase.

bool	Shutdown ()
	Transition the isolate to the `Phase::Shutdown` phase. The only thing left to do is to collect the isolate.

void	AddIsolateShutdownCallback (const fml::closure &closure)
	Registers a callback that will be invoked in isolate scope just before the isolate transitions to the `Phase::Shutdown` phase.

std::weak_ptr< DartIsolate >	GetWeakIsolatePtr ()
	A weak pointer to the Dart isolate instance. This instance may only be used on the task runner that created the root isolate.

fml::RefPtr< fml::TaskRunner >	GetMessageHandlingTaskRunner () const
	The task runner on which the Dart code for the root isolate is running. For the root isolate, this is the UI task runner for the shell that owns the root isolate.

Dart_Isolate	CreatePlatformIsolate (Dart_Handle entry_point, char **error) override
	Creates a new isolate in the same group as this isolate, which runs on the platform thread. This method can only be invoked on the root isolate.

bool	LoadLoadingUnit (intptr_t loading_unit_id, std::unique_ptr< const fml::Mapping > snapshot_data, std::unique_ptr< const fml::Mapping > snapshot_instructions)

void	LoadLoadingUnitError (intptr_t loading_unit_id, const std::string &error_message, bool transient)

DartIsolateGroupData &	GetIsolateGroupData ()

const DartIsolateGroupData &	GetIsolateGroupData () const

void	SetOwnerToCurrentThread ()

Public Member Functions inherited from flutter::UIDartState
Dart_Port	main_port () const

bool	IsRootIsolate () const

void	SetDebugName (const std::string &name)

const std::string &	debug_name () const

const std::string &	logger_prefix () const

PlatformConfiguration *	platform_configuration () const

void	SetPlatformMessageHandler (std::weak_ptr< PlatformMessageHandler > handler)

Dart_Handle	HandlePlatformMessage (std::unique_ptr< PlatformMessage > message)

const TaskRunners &	GetTaskRunners () const

void	ScheduleMicrotask (Dart_Handle handle)

void	FlushMicrotasksNow ()

bool	HasPendingMicrotasks ()

fml::WeakPtr< IOManager >	GetIOManager () const

fml::RefPtr< flutter::SkiaUnrefQueue >	GetSkiaUnrefQueue () const

std::shared_ptr< fml::ConcurrentTaskRunner >	GetConcurrentTaskRunner () const

fml::TaskRunnerAffineWeakPtr< SnapshotDelegate >	GetSnapshotDelegate () const

fml::TaskRunnerAffineWeakPtr< ImageDecoder >	GetImageDecoder () const

fml::TaskRunnerAffineWeakPtr< ImageGeneratorRegistry >	GetImageGeneratorRegistry () const

std::shared_ptr< IsolateNameServer >	GetIsolateNameServer () const

tonic::DartErrorHandleType	GetLastError ()

void	LogMessage (const std::string &tag, const std::string &message) const

UnhandledExceptionCallback	unhandled_exception_callback () const

int64_t	GetRootIsolateToken () const

bool	IsDeterministicRenderingEnabled () const
	Whether deterministic rendering practices are enabled for this application.

bool	IsImpellerEnabled () const
	Whether Impeller is enabled for this application.

bool	IsFlutterGPUEnabled () const
	Whether Flutter GPU is enabled for this application.

impeller::RuntimeStageBackend	GetRuntimeStageBackend () const
	The runtime stage to use for fragment shaders.

Public Member Functions inherited from tonic::DartState
	DartState (int dirfd=-1, std::function< void(Dart_Handle)> message_epilogue=nullptr)

virtual	~DartState ()

std::weak_ptr< DartState >	GetWeakPtr ()

Dart_Isolate	isolate ()

void	SetIsolate (Dart_Isolate isolate)

Dart_PersistentHandle	private_constructor_name ()

DartClassLibrary &	class_library ()

DartMessageHandler &	message_handler ()

FileLoader &	file_loader ()

void	MessageEpilogue (Dart_Handle message_result)

void	SetReturnCode (uint32_t return_code)

void	SetReturnCodeCallback (std::function< void(uint32_t)> callback)

bool	has_set_return_code () const

void	SetIsShuttingDown ()

bool	IsShuttingDown ()

Static Public Member Functions
static std::weak_ptr< DartIsolate >	CreateRunningRootIsolate (const Settings &settings, const fml::RefPtr< const DartSnapshot > &isolate_snapshot, std::unique_ptr< PlatformConfiguration > platform_configuration, Flags flags, const fml::closure &root_isolate_create_callback, const fml::closure &isolate_create_callback, const fml::closure &isolate_shutdown_callback, std::optional< std::string > dart_entrypoint, std::optional< std::string > dart_entrypoint_library, const std::vector< std::string > &dart_entrypoint_args, std::unique_ptr< IsolateConfiguration > isolate_configuration, const UIDartState::Context &context, const DartIsolate *spawning_isolate=nullptr, std::shared_ptr< NativeAssetsManager > native_assets_manager=nullptr)
	Creates an instance of a root isolate and returns a weak pointer to the same. The isolate instance may only be used safely on the engine thread on which it was created. In the shell, this is the UI thread and task runner. Using the isolate on any other thread is user error.

static Dart_Handle	LoadLibraryFromKernel (const std::shared_ptr< const fml::Mapping > &mapping)

Static Public Member Functions inherited from flutter::UIDartState
static UIDartState *	Current ()

static void	ThrowIfUIOperationsProhibited ()

Static Public Member Functions inherited from tonic::DartState
static DartState *	From (Dart_Isolate isolate)

static DartState *	Current ()

static Dart_Handle	HandleLibraryTag (Dart_LibraryTag tag, Dart_Handle library, Dart_Handle url)

Friends
class	IsolateConfiguration

class	DartVM

Additional Inherited Members
Protected Member Functions inherited from flutter::UIDartState
	UIDartState (TaskObserverAdd add_callback, TaskObserverRemove remove_callback, std::string logger_prefix, UnhandledExceptionCallback unhandled_exception_callback, LogMessageCallback log_message_callback, std::shared_ptr< IsolateNameServer > isolate_name_server, bool is_root_isolate_, const UIDartState::Context &context)

	~UIDartState () override

void	SetPlatformConfiguration (std::unique_ptr< PlatformConfiguration > platform_configuration)

const std::string &	GetAdvisoryScriptURI () const

Protected Member Functions inherited from tonic::DartState
Dart_Isolate	isolate () const

	TONIC_DISALLOW_COPY_AND_ASSIGN (DartState)

Detailed Description

Represents an instance of a live isolate. An isolate is a separate Dart execution context. Different Dart isolates don't share memory and can be scheduled concurrently by the Dart VM on one of the Dart VM managed worker pool threads.

The entire lifecycle of a Dart isolate is controlled by the Dart VM. Because of this, the engine never holds a strong pointer to the Dart VM for extended periods of time. This allows the VM (or the isolates themselves) to terminate Dart execution without consulting the engine.

The isolate that the engine creates to act as the host for the Flutter application code with UI bindings is called the root isolate.

The root isolate is special in the following ways:

The root isolate forms a new isolate group. Child isolates are added to their parents groups. When the root isolate dies, all isolates in its group are terminated.
Only root isolates get UI bindings.
Root isolates execute their code on engine managed threads. All other isolates run their Dart code on Dart VM managed thread pool workers that the engine has no control over.
Since the engine does not know the thread on which non-root isolates are run, the engine has no opportunity to get a reference to non-root isolates. Such isolates can only be terminated if they terminate themselves or their isolate group is torn down.

Definition at line 57 of file dart_isolate.h.

Member Enumeration Documentation

◆ Phase

enum class flutter::DartIsolate::Phase

strong

The engine represents all dart isolates as being in one of the known phases. By invoking various methods on the Dart isolate, the engine transition the Dart isolate from one phase to the next. The Dart isolate will only move from one phase to the next in the order specified in the DartIsolate::Phase enum. That is, once the isolate has moved out of a particular phase, it can never transition back to that phase in the future. There is no error recovery mechanism and callers that find their isolates in an undesirable phase must discard the isolate and start over.

Enumerator
Unknown	The initial phase of all Dart isolates. This is an internal phase and callers can never get a reference to a Dart isolate in this phase.
Uninitialized	The Dart isolate has been created but none of the library tag or message handers have been set yet. The is an internal phase and callers can never get a reference to a Dart isolate in this phase.
Initialized	The Dart isolate has been fully initialized but none of the libraries referenced by that isolate have been loaded yet. This is an internal phase and callers can never get a reference to a Dart isolate in this phase.
LibrariesSetup	The isolate has been fully initialized and is waiting for the caller to associate isolate snapshots with the same. The isolate will only be ready to execute Dart code once one of the `Prepare` calls are successfully made.
Ready	The isolate is fully ready to start running Dart code. Callers can transition the isolate to the next state by calling the `Run` or `RunFromLibrary` methods.
Running	The isolate is currently running Dart code.
Shutdown	The isolate is no longer running Dart code and is in the middle of being collected. This is in internal phase and callers can never get a reference to a Dart isolate in this phase.

Definition at line 88 of file dart_isolate.h.

                   {
    // NOLINTBEGIN(readability-identifier-naming)
    //--------------------------------------------------------------------------
    /// The initial phase of all Dart isolates. This is an internal phase and
    /// callers can never get a reference to a Dart isolate in this phase.
    ///
    Unknown,
    //--------------------------------------------------------------------------
    /// The Dart isolate has been created but none of the library tag or message
    /// handers have been set yet. The is an internal phase and callers can
    /// never get a reference to a Dart isolate in this phase.
    ///
    Uninitialized,
    //--------------------------------------------------------------------------
    /// The Dart isolate has been fully initialized but none of the
    /// libraries referenced by that isolate have been loaded yet. This is an
    /// internal phase and callers can never get a reference to a Dart isolate
    /// in this phase.
    ///
    Initialized,
    //--------------------------------------------------------------------------
    /// The isolate has been fully initialized and is waiting for the caller to
    /// associate isolate snapshots with the same. The isolate will only be
    /// ready to execute Dart code once one of the `Prepare` calls are
    /// successfully made.
    ///
    LibrariesSetup,
    //--------------------------------------------------------------------------
    /// The isolate is fully ready to start running Dart code. Callers can
    /// transition the isolate to the next state by calling the `Run` or
    /// `RunFromLibrary` methods.
    ///
    Ready,
    //--------------------------------------------------------------------------
    /// The isolate is currently running Dart code.
    ///
    Running,
    //--------------------------------------------------------------------------
    /// The isolate is no longer running Dart code and is in the middle of being
    /// collected. This is in internal phase and callers can never get a
    /// reference to a Dart isolate in this phase.
    ///
    Shutdown,
    // NOLINTEND(readability-identifier-naming)
  };

Constructor & Destructor Documentation

◆ ~DartIsolate()

flutter::DartIsolate::~DartIsolate ( )

override

Definition at line 480 of file dart_isolate.cc.

                          {
  if (IsRootIsolate() && GetMessageHandlingTaskRunner()) {
    FML_DCHECK(GetMessageHandlingTaskRunner()->RunsTasksOnCurrentThread());
  }
}

References FML_DCHECK, GetMessageHandlingTaskRunner(), and flutter::UIDartState::IsRootIsolate().

Member Function Documentation

◆ AddIsolateShutdownCallback()

void flutter::DartIsolate::AddIsolateShutdownCallback ( const fml::closure & closure )

Registers a callback that will be invoked in isolate scope just before the isolate transitions to the Phase::Shutdown phase.

Parameters

[in] closure The callback to invoke on isolate shutdown.

Definition at line 1388 of file dart_isolate.cc.

                                                                      {
  shutdown_callbacks_.emplace_back(std::make_unique<AutoFireClosure>(closure));
}

◆ CreatePlatformIsolate()

Dart_Isolate flutter::DartIsolate::CreatePlatformIsolate	(	Dart_Handle	entry_point,
		char **	error
	)

overridevirtual

Creates a new isolate in the same group as this isolate, which runs on the platform thread. This method can only be invoked on the root isolate.

Parameters

[in]	entry_point	The entrypoint to invoke once the isolate is spawned. Will be run on the platform thread.
[out]	error	If spawning fails inside the Dart VM, this is set to the error string. The error should be reported to the user. Otherwise it is set to null. It's possible for spawning to fail, but this error still be null. In that case the failure should not be reported to the user.

Returns: The newly created isolate, or null if spawning failed.

Reimplemented from flutter::UIDartState.

Definition at line 294 of file dart_isolate.cc.

                                                              {
  *error = nullptr;
  PlatformConfiguration* platform_config = platform_configuration();
  FML_DCHECK(platform_config != nullptr);
  std::shared_ptr<PlatformIsolateManager> platform_isolate_manager =
      platform_config->client()->GetPlatformIsolateManager();
  std::weak_ptr<PlatformIsolateManager> weak_platform_isolate_manager =
      platform_isolate_manager;
  if (platform_isolate_manager->HasShutdownMaybeFalseNegative()) {
    // Don't set the error string. We want to silently ignore this error,
    // because the engine is shutting down.
    FML_LOG(INFO) << "CreatePlatformIsolate called after shutdown";
    return nullptr;
  }
 
  Dart_Isolate parent_isolate = isolate();
  Dart_ExitIsolate();  // Exit parent_isolate.
 
  const TaskRunners& task_runners = GetTaskRunners();
  fml::RefPtr<fml::TaskRunner> platform_task_runner =
      task_runners.GetPlatformTaskRunner();
  FML_DCHECK(platform_task_runner);
 
  auto isolate_group_data = std::shared_ptr<DartIsolateGroupData>(
      *static_cast<std::shared_ptr<DartIsolateGroupData>*>(
          Dart_IsolateGroupData(parent_isolate)));
 
  Settings settings(isolate_group_data->GetSettings());
 
  // PlatformIsolate.spawn should behave like Isolate.spawn when unhandled
  // exceptions happen (log the exception, but don't terminate the app). But the
  // default unhandled_exception_callback may terminate the app, because it is
  // only called for the root isolate (child isolates are managed by the VM and
  // have a different error code path). So override it to simply log the error.
  settings.unhandled_exception_callback = [](const std::string& error,
                                             const std::string& stack_trace) {
    FML_LOG(ERROR) << "Unhandled exception:\n" << error << "\n" << stack_trace;
    return true;
  };
 
  // The platform isolate task observer must be added on the platform thread. So
  // schedule the add function on the platform task runner.
  TaskObserverAdd old_task_observer_add = settings.task_observer_add;
  settings.task_observer_add = [old_task_observer_add, platform_task_runner,
                                weak_platform_isolate_manager](
                                   intptr_t key, const fml::closure& callback) {
    platform_task_runner->PostTask([old_task_observer_add,
                                    weak_platform_isolate_manager, key,
                                    callback]() {
      std::shared_ptr<PlatformIsolateManager> platform_isolate_manager =
          weak_platform_isolate_manager.lock();
      if (platform_isolate_manager == nullptr ||
          platform_isolate_manager->HasShutdown()) {
        // Shutdown happened in between this task being posted, and it running.
        // platform_isolate has already been shut down. Do nothing.
        FML_LOG(INFO) << "Shutdown before platform isolate task observer added";
        return;
      }
      old_task_observer_add(key, callback);
    });
    return platform_task_runner->GetTaskQueueId();
  };
 
  UIDartState::Context context(task_runners);
  context.advisory_script_uri = isolate_group_data->GetAdvisoryScriptURI();
  context.advisory_script_entrypoint =
      isolate_group_data->GetAdvisoryScriptEntrypoint();
  auto isolate_data = std::make_unique<std::shared_ptr<DartIsolate>>(
      std::shared_ptr<DartIsolate>(
          new DartIsolate(settings, context, platform_isolate_manager)));
 
  IsolateMaker isolate_maker =
      [parent_isolate](
          std::shared_ptr<DartIsolateGroupData>* unused_isolate_group_data,
          std::shared_ptr<DartIsolate>* isolate_data, Dart_IsolateFlags* flags,
          char** error) {
        return Dart_CreateIsolateInGroup(
            /*group_member=*/parent_isolate,
            /*name=*/"PlatformIsolate",
            /*shutdown_callback=*/
            reinterpret_cast<Dart_IsolateShutdownCallback>(
                DartIsolate::SpawnIsolateShutdownCallback),
            /*cleanup_callback=*/
            reinterpret_cast<Dart_IsolateCleanupCallback>(
                DartIsolateCleanupCallback),
            /*child_isolate_data=*/isolate_data,
            /*error=*/error);
      };
  Dart_Isolate platform_isolate = CreateDartIsolateGroup(
      nullptr, std::move(isolate_data), nullptr, error, isolate_maker);
 
  Dart_EnterIsolate(parent_isolate);
 
  if (*error) {
    return nullptr;
  }
 
  if (!platform_isolate_manager->RegisterPlatformIsolate(platform_isolate)) {
    // The PlatformIsolateManager was shutdown while we were creating the
    // isolate. This means that we're shutting down the engine. We need to
    // shutdown the platform isolate.
    FML_LOG(INFO) << "Shutdown during platform isolate creation";
    tonic::DartIsolateScope isolate_scope(platform_isolate);
    Dart_ShutdownIsolate();
    return nullptr;
  }
 
  tonic::DartApiScope api_scope;
  Dart_PersistentHandle entry_point_handle =
      Dart_NewPersistentHandle(entry_point);
 
  platform_task_runner->PostTask([entry_point_handle, platform_isolate,
                                  weak_platform_isolate_manager]() {
    std::shared_ptr<PlatformIsolateManager> platform_isolate_manager =
        weak_platform_isolate_manager.lock();
    if (platform_isolate_manager == nullptr ||
        platform_isolate_manager->HasShutdown()) {
      // Shutdown happened in between this task being posted, and it running.
      // platform_isolate has already been shut down. Do nothing.
      FML_LOG(INFO) << "Shutdown before platform isolate entry point";
      return;
    }
 
    tonic::DartIsolateScope isolate_scope(platform_isolate);
    tonic::DartApiScope api_scope;
    Dart_Handle entry_point = Dart_HandleFromPersistent(entry_point_handle);
    Dart_DeletePersistentHandle(entry_point_handle);
 
    // Disable Isolate.exit().
    Dart_Handle isolate_lib = Dart_LookupLibrary(tonic::ToDart("dart:isolate"));
    FML_CHECK(!tonic::CheckAndHandleError(isolate_lib));
    Dart_Handle isolate_type = Dart_GetNonNullableType(
        isolate_lib, tonic::ToDart("Isolate"), 0, nullptr);
    FML_CHECK(!tonic::CheckAndHandleError(isolate_type));
    Dart_Handle result =
        Dart_SetField(isolate_type, tonic::ToDart("_mayExit"), Dart_False());
    FML_CHECK(!tonic::CheckAndHandleError(result));
 
    tonic::DartInvokeVoid(entry_point);
  });
 
  return platform_isolate;
}

References flutter::UIDartState::Context::advisory_script_entrypoint, flutter::UIDartState::Context::advisory_script_uri, callback, tonic::CheckAndHandleError(), flutter::PlatformConfiguration::client(), tonic::DartInvokeVoid(), error, FML_CHECK, FML_DCHECK, FML_LOG, flutter::PlatformConfigurationClient::GetPlatformIsolateManager(), flutter::TaskRunners::GetPlatformTaskRunner(), flutter::UIDartState::GetTaskRunners(), tonic::DartState::isolate(), key, flutter::UIDartState::platform_configuration(), flutter::Settings::task_observer_add, tonic::ToDart(), and flutter::Settings::unhandled_exception_callback.

◆ CreateRunningRootIsolate()

std::weak_ptr< DartIsolate > flutter::DartIsolate::CreateRunningRootIsolate	(	const Settings &	settings,
		const fml::RefPtr< const DartSnapshot > &	isolate_snapshot,
		std::unique_ptr< PlatformConfiguration >	platform_configuration,
		Flags	flags,
		const fml::closure &	root_isolate_create_callback,
		const fml::closure &	isolate_create_callback,
		const fml::closure &	isolate_shutdown_callback,
		std::optional< std::string >	dart_entrypoint,
		std::optional< std::string >	dart_entrypoint_library,
		const std::vector< std::string > &	dart_entrypoint_args,
		std::unique_ptr< IsolateConfiguration >	isolate_configuration,
		const UIDartState::Context &	context,
		const DartIsolate *	spawning_isolate = `nullptr`,
		std::shared_ptr< NativeAssetsManager >	native_assets_manager = `nullptr`
	)

static

Creates an instance of a root isolate and returns a weak pointer to the same. The isolate instance may only be used safely on the engine thread on which it was created. In the shell, this is the UI thread and task runner. Using the isolate on any other thread is user error.

The isolate that the engine creates to act as the host for the Flutter application code with UI bindings is called the root isolate.

The root isolate is special in the following ways:

The root isolate forms a new isolate group. Child isolates are added to their parents groups. When the root isolate dies, all isolates in its group are terminated.
Only root isolates get UI bindings.
Root isolates execute their code on engine managed threads. All other isolates run their Dart code on Dart VM managed thread pool workers that the engine has no control over.
Since the engine does not know the thread on which non-root isolates are run, the engine has no opportunity to get a reference to non-root isolates. Such isolates can only be terminated if they terminate themselves or their isolate group is torn down.

Parameters

[in]	settings	The settings used to create the isolate.
[in]	platform_configuration	The platform configuration for handling communication with the framework.
[in]	flags	The Dart isolate flags for this isolate instance.
[in]	dart_entrypoint	The name of the dart entrypoint function to invoke.
[in]	dart_entrypoint_library	The name of the dart library containing the entrypoint.
[in]	dart_entrypoint_args	Arguments passed as a List<String> to Dart's entrypoint function.
[in]	isolate_configuration	The isolate configuration used to configure the isolate before invoking the entrypoint.
[in]	root_isolate_create_callback	A callback called after the root isolate is created, without isolate scope. This gives the caller a chance to finish any setup before running the Dart program, and after any embedder callbacks in the settings object.
[in]	isolate_create_callback	The isolate create callback. This will be called when the before the main Dart entrypoint is invoked in the root isolate. The isolate is already in the running state at this point and an isolate scope is current.
[in]	isolate_shutdown_callback	The isolate shutdown callback. This will be called before the isolate is about to transition into the Shutdown phase. The isolate is still running at this point and an isolate scope is current.
[in]	context	Engine-owned state which is accessed by the root dart isolate.
[in]	spawning_isolate	The isolate that is spawning the new isolate.

Returns: A weak pointer to the root Dart isolate. The caller must ensure that the isolate is not referenced for long periods of time as it prevents isolate collection when the isolate terminates itself. The caller may also only use the isolate on the thread on which the isolate was created.

Definition at line 87 of file dart_isolate.cc.

                                                              {
  if (!isolate_snapshot) {
    FML_LOG(ERROR) << "Invalid isolate snapshot.";
    return {};
  }
 
  if (!isolate_configuration) {
    FML_LOG(ERROR) << "Invalid isolate configuration.";
    return {};
  }
 
  isolate_flags.SetNullSafetyEnabled(
      isolate_configuration->IsNullSafetyEnabled(*isolate_snapshot));
  isolate_flags.SetIsDontNeedSafe(isolate_snapshot->IsDontNeedSafe());
 
  auto isolate = CreateRootIsolate(settings,                           //
                                   isolate_snapshot,                   //
                                   std::move(platform_configuration),  //
                                   isolate_flags,                      //
                                   isolate_create_callback,            //
                                   isolate_shutdown_callback,          //
                                   context,                            //
                                   spawning_isolate,                   //
                                   std::move(native_assets_manager)    //
                                   )
                     .lock();
 
  if (!isolate) {
    FML_LOG(ERROR) << "Could not create root isolate.";
    return {};
  }
 
  fml::ScopedCleanupClosure shutdown_on_error([isolate]() {
    if (!isolate->Shutdown()) {
      FML_DLOG(ERROR) << "Could not shutdown transient isolate.";
    }
  });
 
  if (isolate->GetPhase() != DartIsolate::Phase::LibrariesSetup) {
    FML_LOG(ERROR) << "Root isolate was created in an incorrect phase: "
                   << static_cast<int>(isolate->GetPhase());
    return {};
  }
 
  if (!isolate_configuration->PrepareIsolate(*isolate.get())) {
    FML_LOG(ERROR) << "Could not prepare isolate.";
    return {};
  }
 
  if (isolate->GetPhase() != DartIsolate::Phase::Ready) {
    FML_LOG(ERROR) << "Root isolate not in the ready phase for Dart entrypoint "
                      "invocation.";
    return {};
  }
 
  {
    tonic::DartState::Scope scope(isolate.get());
    if (settings.merged_platform_ui_thread !=
        Settings::MergedPlatformUIThread::kMergeAfterLaunch) {
      Dart_SetCurrentThreadOwnsIsolate();
    }
 
    if (settings.root_isolate_create_callback) {
      // Isolate callbacks always occur in isolate scope and before user code
      // has had a chance to run.
      settings.root_isolate_create_callback(*isolate.get());
    }
  }
 
  if (root_isolate_create_callback) {
    root_isolate_create_callback();
  }
 
  if (!isolate->RunFromLibrary(std::move(dart_entrypoint_library),  //
                               std::move(dart_entrypoint),          //
                               dart_entrypoint_args)) {
    FML_LOG(ERROR) << "Could not run the run main Dart entrypoint.";
    return {};
  }
 
  if (settings.root_isolate_shutdown_callback) {
    isolate->AddIsolateShutdownCallback(
        settings.root_isolate_shutdown_callback);
  }
 
  shutdown_on_error.Release();
 
  return isolate;
}

References FML_LOG, tonic::DartState::isolate(), flutter::Settings::kMergeAfterLaunch, LibrariesSetup, flutter::Settings::merged_platform_ui_thread, flutter::UIDartState::platform_configuration(), Ready, flutter::Settings::root_isolate_create_callback, flutter::Settings::root_isolate_shutdown_callback, flutter::DartIsolate::Flags::SetIsDontNeedSafe(), and flutter::DartIsolate::Flags::SetNullSafetyEnabled().

Referenced by flutter::testing::CreateAndRunRootIsolate(), flutter::RuntimeController::LaunchRootIsolate(), flutter::testing::RunDartCodeInIsolateOnUITaskRunner(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), and flutter::testing::PlatformIsolateManagerTest::TestWithRootIsolate().

◆ GetIsolateGroupData() [1/2]

DartIsolateGroupData & flutter::DartIsolate::GetIsolateGroupData ( )

Definition at line 1052 of file dart_isolate.cc.

                                                       {
  std::shared_ptr<DartIsolateGroupData>* isolate_group_data =
      static_cast<std::shared_ptr<DartIsolateGroupData>*>(
          Dart_IsolateGroupData(isolate()));
  return **isolate_group_data;
}

References tonic::DartState::isolate().

Referenced by GetIsolateGroupData(), PrepareForRunningFromKernel(), and PrepareForRunningFromPrecompiledCode().

◆ GetIsolateGroupData() [2/2]

const DartIsolateGroupData & flutter::DartIsolate::GetIsolateGroupData ( ) const

Definition at line 1059 of file dart_isolate.cc.

                                                                   {
  DartIsolate* non_const_this = const_cast<DartIsolate*>(this);
  return non_const_this->GetIsolateGroupData();
}

References GetIsolateGroupData().

◆ GetMessageHandlingTaskRunner()

fml::RefPtr< fml::TaskRunner > flutter::DartIsolate::GetMessageHandlingTaskRunner ( ) const

The task runner on which the Dart code for the root isolate is running. For the root isolate, this is the UI task runner for the shell that owns the root isolate.

Returns: The message handling task runner.

Definition at line 548 of file dart_isolate.cc.

                                                                         {
  return message_handling_task_runner_;
}

Referenced by ~DartIsolate().

◆ GetPhase()

DartIsolate::Phase flutter::DartIsolate::GetPhase ( ) const

The current phase of the isolate. The engine represents all dart isolates as being in one of the known phases. By invoking various methods on the Dart isolate, the engine transitions the Dart isolate from one phase to the next. The Dart isolate will only move from one phase to the next in the order specified in the DartIsolate::Phase enum. That is, the once the isolate has moved out of a particular phase, it can never transition back to that phase in the future. There is no error recovery mechanism and callers that find their isolates in an undesirable phase must discard the isolate and start over.

Returns: The current isolate phase.

Definition at line 486 of file dart_isolate.cc.

                                             {
  return phase_;
}

Referenced by flutter::IsolateConfiguration::PrepareIsolate().

◆ GetServiceId()

std::string flutter::DartIsolate::GetServiceId ( )

Returns the ID for an isolate which is used to query the service protocol.

Returns: The service identifier for this isolate.

Definition at line 490 of file dart_isolate.cc.

                                    {
  const char* service_id_buf = Dart_IsolateServiceId(isolate());
  std::string service_id(service_id_buf);
  free(const_cast<char*>(service_id_buf));
  return service_id;
}

References tonic::DartState::isolate().

◆ GetWeakIsolatePtr()

std::weak_ptr< DartIsolate > flutter::DartIsolate::GetWeakIsolatePtr ( )

A weak pointer to the Dart isolate instance. This instance may only be used on the task runner that created the root isolate.

Returns: The weak isolate pointer.

Definition at line 1379 of file dart_isolate.cc.

                                                        {
  return std::static_pointer_cast<DartIsolate>(shared_from_this());
}

◆ LoadLibraryFromKernel()

Dart_Handle flutter::DartIsolate::LoadLibraryFromKernel ( const std::shared_ptr< const fml::Mapping > & mapping )

static

Returns the "main" entrypoint of the library contained in the kernel data in mapping.

Definition at line 1434 of file dart_isolate.cc.

                                                    {
  if (DartVM::IsRunningPrecompiledCode()) {
    return Dart_Null();
  }
 
  auto* isolate_group_data =
      static_cast<std::shared_ptr<DartIsolateGroupData>*>(
          Dart_CurrentIsolateGroupData());
  // Mapping must be retained until isolate shutdown.
  (*isolate_group_data)->AddKernelBuffer(mapping);
 
  auto lib =
      Dart_LoadLibraryFromKernel(mapping->GetMapping(), mapping->GetSize());
  if (tonic::CheckAndHandleError(lib)) {
    return Dart_Null();
  }
  auto result = Dart_FinalizeLoading(false);
  if (Dart_IsError(result)) {
    return result;
  }
  return Dart_GetField(lib, Dart_NewStringFromCString("main"));
}

References tonic::CheckAndHandleError(), and flutter::DartVM::IsRunningPrecompiledCode().

Referenced by flutter::LoadLibraryFromKernel().

◆ LoadLoadingUnit()

bool flutter::DartIsolate::LoadLoadingUnit	(	intptr_t	loading_unit_id,
		std::unique_ptr< const fml::Mapping >	snapshot_data,
		std::unique_ptr< const fml::Mapping >	snapshot_instructions
	)

Definition at line 552 of file dart_isolate.cc.

                                                           {
  tonic::DartState::Scope scope(this);
 
  fml::RefPtr<DartSnapshot> dart_snapshot =
      DartSnapshot::IsolateSnapshotFromMappings(
          std::move(snapshot_data), std::move(snapshot_instructions));
 
  Dart_Handle result = Dart_DeferredLoadComplete(
      loading_unit_id, dart_snapshot->GetDataMapping(),
      dart_snapshot->GetInstructionsMapping());
  if (tonic::CheckAndHandleError(result)) {
    LoadLoadingUnitError(loading_unit_id, Dart_GetError(result),
                         /*transient*/ true);
    return false;
  }
  loading_unit_snapshots_.insert(dart_snapshot);
  return true;
}

References tonic::CheckAndHandleError(), flutter::DartSnapshot::IsolateSnapshotFromMappings(), and LoadLoadingUnitError().

◆ LoadLoadingUnitError()

void flutter::DartIsolate::LoadLoadingUnitError	(	intptr_t	loading_unit_id,
		const std::string &	error_message,
		bool	transient
	)

Definition at line 574 of file dart_isolate.cc.

                                                       {
  tonic::DartState::Scope scope(this);
  Dart_Handle result = Dart_DeferredLoadCompleteError(
      loading_unit_id, error_message.c_str(), transient);
  tonic::CheckAndHandleError(result);
}

References tonic::CheckAndHandleError().

Referenced by LoadLoadingUnit().

◆ PrepareForRunningFromKernel()

bool flutter::DartIsolate::PrepareForRunningFromKernel	(	const std::shared_ptr< const fml::Mapping > &	kernel,
		bool	child_isolate,
		bool	last_piece
	)

Prepare the isolate for running for a a list of kernel files.

        The Dart VM must be configured for running from kernel
        snapshots.

        The isolate must already be in the `Phase::LibrariesSetup`
        phase. This call can be made multiple times. After a series of
        successful calls to this method, the caller can specify the
        last kernel file mapping by specifying `last_piece` to `true`.
        On success, the isolate will transition to the `Phase::Ready`
        phase.

Parameters

[in]	kernel	The kernel mapping.
[in]	last_piece	Indicates if this is the last kernel mapping expected. After this point, the isolate will attempt a transition to the `Phase::Ready` phase.

Returns: If the kernel mapping supplied was successfully used to prepare the isolate.

Definition at line 755 of file dart_isolate.cc.

                     {
  TRACE_EVENT0("flutter", "DartIsolate::PrepareForRunningFromKernel");
  if (phase_ != Phase::LibrariesSetup) {
    return false;
  }
 
  if (DartVM::IsRunningPrecompiledCode()) {
    return false;
  }
 
  tonic::DartState::Scope scope(this);
 
  if (!child_isolate && !is_spawning_in_group_) {
    if (!mapping || mapping->GetSize() == 0) {
      return false;
    }
 
    // Use root library provided by kernel in favor of one provided by snapshot.
    Dart_SetRootLibrary(Dart_Null());
 
    if (!LoadKernel(mapping, last_piece)) {
      return false;
    }
  }
 
  if (!last_piece) {
    // More to come.
    return true;
  }
 
  if (Dart_IsNull(Dart_RootLibrary())) {
    return false;
  }
 
  if (!MarkIsolateRunnable()) {
    return false;
  }
 
  // Child isolate shares root isolate embedder_isolate (lines 691 and 693
  // below). Re-initializing child_isolate_preparer_ lambda while it is being
  // executed leads to crashes.
  if (GetIsolateGroupData().GetChildIsolatePreparer() == nullptr) {
    GetIsolateGroupData().SetChildIsolatePreparer(
        [buffers =
             GetIsolateGroupData().GetKernelBuffers()](DartIsolate* isolate) {
          for (uint64_t i = 0; i < buffers.size(); i++) {
            bool last_piece = i + 1 == buffers.size();
            const std::shared_ptr<const fml::Mapping>& buffer = buffers.at(i);
            if (!isolate->PrepareForRunningFromKernel(buffer,
                                                      /*child_isolate=*/true,
                                                      last_piece)) {
              return false;
            }
          }
          return true;
        });
  }
 
  const fml::closure& isolate_create_callback =
      GetIsolateGroupData().GetIsolateCreateCallback();
  if (isolate_create_callback) {
    isolate_create_callback();
  }
 
  phase_ = Phase::Ready;
 
  return true;
}

References flutter::buffer, flutter::DartIsolateGroupData::GetIsolateCreateCallback(), GetIsolateGroupData(), i, tonic::DartState::isolate(), flutter::DartVM::IsRunningPrecompiledCode(), LibrariesSetup, Ready, flutter::DartIsolateGroupData::SetChildIsolatePreparer(), and TRACE_EVENT0.

Referenced by flutter::KernelIsolateConfiguration::DoPrepareIsolate(), flutter::KernelListIsolateConfiguration::DoPrepareIsolate(), and PrepareForRunningFromKernels().

◆ PrepareForRunningFromKernels() [1/2]

bool flutter::DartIsolate::PrepareForRunningFromKernels ( std::vector< std::shared_ptr< const fml::Mapping > > kernels )

Prepare the isolate for running for a a list of kernel files.

        The Dart VM must be configured for running from kernel
        snapshots.

        The isolate must already be in the `Phase::LibrariesSetup`
        phase. After a successful call to this method, the isolate
        will transition to the `Phase::Ready` phase.

Parameters

[in] kernels The kernels

Returns: If the kernel mappings supplied were successfully used to prepare the isolate.

Definition at line 827 of file dart_isolate.cc.

                                                        {
  const auto count = kernels.size();
  if (count == 0) {
    return false;
  }
 
  for (size_t i = 0; i < count; ++i) {
    bool last = (i == (count - 1));
    if (!PrepareForRunningFromKernel(kernels[i], /*child_isolate=*/false,
                                     last)) {
      return false;
    }
  }
 
  return true;
}

References i, and PrepareForRunningFromKernel().

Referenced by PrepareForRunningFromKernels().

◆ PrepareForRunningFromKernels() [2/2]

bool flutter::DartIsolate::PrepareForRunningFromKernels ( std::vector< std::unique_ptr< const fml::Mapping > > kernels )

Prepare the isolate for running for a a list of kernel files.

        The Dart VM must be configured for running from kernel
        snapshots.

        The isolate must already be in the `Phase::LibrariesSetup`
        phase. After a successful call to this method, the isolate
        will transition to the `Phase::Ready` phase.

Parameters

[in] kernels The kernels

Returns: If the kernel mappings supplied were successfully used to prepare the isolate.

Definition at line 845 of file dart_isolate.cc.

                                                        {
  std::vector<std::shared_ptr<const fml::Mapping>> shared_kernels;
  shared_kernels.reserve(kernels.size());
  for (auto& kernel : kernels) {
    shared_kernels.emplace_back(std::move(kernel));
  }
  return PrepareForRunningFromKernels(shared_kernels);
}

References PrepareForRunningFromKernels().

◆ PrepareForRunningFromPrecompiledCode()

bool flutter::DartIsolate::PrepareForRunningFromPrecompiledCode ( )

Prepare the isolate for running for a precompiled code bundle. The Dart VM must be configured for running precompiled code.

The isolate must already be in the Phase::LibrariesSetup phase. After a successful call to this method, the isolate will transition to the Phase::Ready phase.

Returns: Whether the isolate was prepared and the described phase transition made.

Definition at line 696 of file dart_isolate.cc.

                                                       {
  TRACE_EVENT0("flutter", "DartIsolate::PrepareForRunningFromPrecompiledCode");
  if (phase_ != Phase::LibrariesSetup) {
    return false;
  }
 
  tonic::DartState::Scope scope(this);
 
  if (Dart_IsNull(Dart_RootLibrary())) {
    return false;
  }
 
  if (!MarkIsolateRunnable()) {
    return false;
  }
 
  if (GetIsolateGroupData().GetChildIsolatePreparer() == nullptr) {
    GetIsolateGroupData().SetChildIsolatePreparer([](DartIsolate* isolate) {
      return isolate->PrepareForRunningFromPrecompiledCode();
    });
  }
 
  const fml::closure& isolate_create_callback =
      GetIsolateGroupData().GetIsolateCreateCallback();
  if (isolate_create_callback) {
    isolate_create_callback();
  }
 
  phase_ = Phase::Ready;
  return true;
}

References flutter::DartIsolateGroupData::GetIsolateCreateCallback(), GetIsolateGroupData(), tonic::DartState::isolate(), LibrariesSetup, Ready, flutter::DartIsolateGroupData::SetChildIsolatePreparer(), and TRACE_EVENT0.

Referenced by flutter::AppSnapshotIsolateConfiguration::DoPrepareIsolate().

◆ RunFromLibrary()

bool flutter::DartIsolate::RunFromLibrary	(	std::optional< std::string >	library_name,
		std::optional< std::string >	entrypoint,
		const std::vector< std::string > &	args
	)

Transition the root isolate to the Phase::Running phase and invoke the main entrypoint (the "main" method) in the specified library. The isolate must already be in the Phase::Ready phase.

Parameters

[in]	library_name	The name of the library in which to invoke the supplied entrypoint.
[in]	entrypoint	The entrypoint in `library_name`
[in]	args	A list of string arguments to the entrypoint.

Returns: If the isolate successfully transitioned to the running phase and the main entrypoint was invoked.

Definition at line 909 of file dart_isolate.cc.

                                                                   {
  TRACE_EVENT0("flutter", "DartIsolate::RunFromLibrary");
  if (phase_ != Phase::Ready) {
    return false;
  }
 
  tonic::DartState::Scope scope(this);
 
  auto library_handle =
      library_name.has_value() && !library_name.value().empty()
          ? ::Dart_LookupLibrary(tonic::ToDart(library_name.value().c_str()))
          : ::Dart_RootLibrary();
  auto entrypoint_handle = entrypoint.has_value() && !entrypoint.value().empty()
                               ? tonic::ToDart(entrypoint.value().c_str())
                               : tonic::ToDart("main");
 
  if (!FindAndInvokeDartPluginRegistrant()) {
    // TODO(gaaclarke): Remove once the framework PR lands that uses `--source`
    // to compile the Dart Plugin Registrant
    // (https://github.com/flutter/flutter/pull/100572).
    InvokeDartPluginRegistrantIfAvailable(library_handle);
  }
 
  auto user_entrypoint_function =
      ::Dart_GetField(library_handle, entrypoint_handle);
 
  auto entrypoint_args = tonic::ToDart(args);
 
  if (!InvokeMainEntrypoint(user_entrypoint_function, entrypoint_args)) {
    return false;
  }
 
  phase_ = Phase::Running;
 
  return true;
}

References args, flutter::FindAndInvokeDartPluginRegistrant(), flutter::InvokeDartPluginRegistrantIfAvailable(), flutter::InvokeMainEntrypoint(), Ready, Running, tonic::ToDart(), and TRACE_EVENT0.

◆ SetOwnerToCurrentThread()

void flutter::DartIsolate::SetOwnerToCurrentThread ( )

Definition at line 1383 of file dart_isolate.cc.

                                          {
  tonic::DartIsolateScope isolate_scope(isolate());
  Dart_SetCurrentThreadOwnsIsolate();
}

References tonic::DartState::isolate().

◆ Shutdown()

bool flutter::DartIsolate::Shutdown ( )

Transition the isolate to the Phase::Shutdown phase. The only thing left to do is to collect the isolate.

Returns: If the isolate successfully transitioned to the shutdown phase.

Definition at line 948 of file dart_isolate.cc.

                           {
  TRACE_EVENT0("flutter", "DartIsolate::Shutdown");
  // This call may be re-entrant since Dart_ShutdownIsolate can invoke the
  // cleanup callback which deletes the embedder side object of the dart isolate
  // (a.k.a. this).
  if (phase_ == Phase::Shutdown) {
    return false;
  }
  phase_ = Phase::Shutdown;
  Dart_Isolate vm_isolate = isolate();
  // The isolate can be nullptr if this instance is the stub isolate data used
  // during root isolate creation.
  if (vm_isolate != nullptr) {
    // We need to enter the isolate because Dart_ShutdownIsolate does not take
    // the isolate to shutdown as a parameter.
    FML_DCHECK(Dart_CurrentIsolate() == nullptr);
    Dart_EnterIsolate(vm_isolate);
    Dart_ShutdownIsolate();
    FML_DCHECK(Dart_CurrentIsolate() == nullptr);
  }
  return true;
}

References FML_DCHECK, tonic::DartState::isolate(), Shutdown, and TRACE_EVENT0.

Friends And Related Symbol Documentation

◆ DartVM

friend class DartVM

friend

Definition at line 430 of file dart_isolate.h.

◆ IsolateConfiguration

friend class IsolateConfiguration

friend

Definition at line 419 of file dart_isolate.h.

The documentation for this class was generated from the following files:

runtime/dart_isolate.h
runtime/dart_isolate.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Phase

Constructor & Destructor Documentation

◆ ~DartIsolate()

Member Function Documentation

◆ AddIsolateShutdownCallback()

◆ CreatePlatformIsolate()

◆ CreateRunningRootIsolate()

◆ GetIsolateGroupData() [1/2]

◆ GetIsolateGroupData() [2/2]

◆ GetMessageHandlingTaskRunner()

◆ GetPhase()

◆ GetServiceId()

◆ GetWeakIsolatePtr()

◆ LoadLibraryFromKernel()

◆ LoadLoadingUnit()

◆ LoadLoadingUnitError()

◆ PrepareForRunningFromKernel()

◆ PrepareForRunningFromKernels() [1/2]

◆ PrepareForRunningFromKernels() [2/2]

◆ PrepareForRunningFromPrecompiledCode()

◆ RunFromLibrary()

◆ SetOwnerToCurrentThread()

◆ Shutdown()

Friends And Related Symbol Documentation

◆ DartVM

◆ IsolateConfiguration