An isolate configuration is a collection of snapshots and asset managers that the engine will use to configure the isolate before invoking its root entrypoint. The set of snapshots must be sufficient for the engine to move the isolate from the |DartIsolate::Phase::LibrariesSetup| phase to the |DartIsolate::Phase::Ready| phase. Note that the isolate configuration will not be collected till the isolate tied to the configuration as well as any and all child isolates of that isolate are collected. The engine may ask the configuration to prepare multiple isolates. All subclasses of this class must be thread safe as the configuration may be created, collected and used on multiple threads. Usually these threads are engine or VM managed so care must be taken to ensure that subclasses do not reference any thread local state. More...

#include <isolate_configuration.h>

Inheritance diagram for flutter::IsolateConfiguration:

Public Member Functions
	IsolateConfiguration ()
	Create an isolate configuration. This has no threading restrictions.

virtual	~IsolateConfiguration ()
	Destroys an isolate configuration. This has no threading restrictions and may be collection of configurations may occur on any thread (and usually happens on an internal VM managed thread pool thread).

bool	PrepareIsolate (DartIsolate &isolate)
	When an isolate is created and sufficiently initialized to move it into the `DartIsolate::Phase::LibrariesSetup` phase, this method is invoked on the isolate to then move the isolate into the `DartIsolate::Phase::Ready` phase. Then isolate's main entrypoint is then invoked to move it into the `DartIsolate::Phase::Running` phase. This method will be called each time the root isolate is launched (which may be multiple times in cold-restart scenarios) as well as one each for any child isolates referenced by that isolate.

virtual bool	IsNullSafetyEnabled (const DartSnapshot &snapshot)=0

Static Public Member Functions
static std::unique_ptr< IsolateConfiguration >	InferFromSettings (const Settings &settings, const std::shared_ptr< AssetManager > &asset_manager=nullptr, const fml::RefPtr< fml::TaskRunner > &io_worker=nullptr, IsolateLaunchType launch_type=IsolateLaunchType::kNewGroup)
	Attempts to infer the isolate configuration from the `Settings` object. If the VM is configured for AOT mode, snapshot resolution is attempted with predefined symbols present in the currently loaded process. In JIT mode, Dart kernel file resolution is attempted in the assets directory. If an IO worker is specified, snapshot resolution may be attempted on the serial worker task runner. The worker task runner thread must remain valid and running till after the shell associated with the engine used to launch the isolate for which this run configuration is used is collected.

static std::unique_ptr< IsolateConfiguration >	CreateForAppSnapshot ()
	Creates an AOT isolate configuration using snapshot symbols present in the currently loaded process. These symbols need to be given to the Dart VM on bootstrap and hence have already been resolved.

static std::unique_ptr< IsolateConfiguration >	CreateForKernelList (std::vector< std::future< std::unique_ptr< const fml::Mapping > > > kernel_pieces)
	Creates a JIT isolate configuration using a list of futures to snapshots defining the ready isolate state. In environments where snapshot resolution is extremely expensive, embedders attempt to resolve snapshots on worker thread(s) and return the future of the promise of snapshot resolution to this method. That way, snapshot resolution begins well before isolate launch is attempted by the engine.

static std::unique_ptr< IsolateConfiguration >	CreateForKernel (std::unique_ptr< const fml::Mapping > kernel)
	Creates a JIT isolate configuration using the specified snapshot. This is a convenience method for the `CreateForKernelList` method that takes a list of futures to Dart kernel snapshots.

static std::unique_ptr< IsolateConfiguration >	CreateForKernelList (std::vector< std::unique_ptr< const fml::Mapping > > kernel_pieces)
	Creates a JIT isolate configuration using the specified snapshots. This is a convenience method for the `CreateForKernelList` method that takes a list of futures to Dart kernel snapshots.

Protected Member Functions
virtual bool	DoPrepareIsolate (DartIsolate &isolate)=0

Detailed Description

An isolate configuration is a collection of snapshots and asset managers that the engine will use to configure the isolate before invoking its root entrypoint. The set of snapshots must be sufficient for the engine to move the isolate from the |DartIsolate::Phase::LibrariesSetup| phase to the |DartIsolate::Phase::Ready| phase. Note that the isolate configuration will not be collected till the isolate tied to the configuration as well as any and all child isolates of that isolate are collected. The engine may ask the configuration to prepare multiple isolates. All subclasses of this class must be thread safe as the configuration may be created, collected and used on multiple threads. Usually these threads are engine or VM managed so care must be taken to ensure that subclasses do not reference any thread local state.

Definition at line 47 of file isolate_configuration.h.

Constructor & Destructor Documentation

◆ IsolateConfiguration()

flutter::IsolateConfiguration::IsolateConfiguration ( )

default

Create an isolate configuration. This has no threading restrictions.

◆ ~IsolateConfiguration()

flutter::IsolateConfiguration::~IsolateConfiguration ( )

virtualdefault

Destroys an isolate configuration. This has no threading restrictions and may be collection of configurations may occur on any thread (and usually happens on an internal VM managed thread pool thread).

Member Function Documentation

◆ CreateForAppSnapshot()

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::CreateForAppSnapshot ( )

static

Creates an AOT isolate configuration using snapshot symbols present in the currently loaded process. These symbols need to be given to the Dart VM on bootstrap and hence have already been resolved.

Returns: An AOT isolate configuration.

Definition at line 269 of file isolate_configuration.cc.

                                           {
  return std::make_unique<AppSnapshotIsolateConfiguration>();
}

Referenced by InferFromSettings().

◆ CreateForKernel()

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::CreateForKernel ( std::unique_ptr< const fml::Mapping > kernel )

static

Creates a JIT isolate configuration using the specified snapshot. This is a convenience method for the CreateForKernelList method that takes a list of futures to Dart kernel snapshots.

See also: CreateForKernelList()

Parameters

[in] kernel The kernel snapshot.

Returns: A JIT isolate configuration.

Definition at line 273 of file isolate_configuration.cc.

                                            {
  return std::make_unique<KernelIsolateConfiguration>(std::move(kernel));
}

Referenced by InferFromSettings(), and flutter::RunTester().

◆ CreateForKernelList() [1/2]

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::CreateForKernelList ( std::vector< std::future< std::unique_ptr< const fml::Mapping > > > kernel_pieces )

static

Creates a JIT isolate configuration using a list of futures to snapshots defining the ready isolate state. In environments where snapshot resolution is extremely expensive, embedders attempt to resolve snapshots on worker thread(s) and return the future of the promise of snapshot resolution to this method. That way, snapshot resolution begins well before isolate launch is attempted by the engine.

Parameters

[in] kernel_pieces The list of futures to Dart kernel snapshots.

Returns: A JIT isolate configuration.

Definition at line 293 of file isolate_configuration.cc.

                       {
  return std::make_unique<KernelListIsolateConfiguration>(
      std::move(kernel_pieces));
}

Referenced by CreateForKernelList(), and InferFromSettings().

◆ CreateForKernelList() [2/2]

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::CreateForKernelList ( std::vector< std::unique_ptr< const fml::Mapping > > kernel_pieces )

static

Creates a JIT isolate configuration using the specified snapshots. This is a convenience method for the CreateForKernelList method that takes a list of futures to Dart kernel snapshots.

See also: CreateForKernelList()

Parameters

[in] kernel_pieces The kernel pieces

Returns: { description_of_the_return_value }

Definition at line 278 of file isolate_configuration.cc.

                                                              {
  std::vector<std::future<std::unique_ptr<const fml::Mapping>>> pieces;
  for (auto& piece : kernel_pieces) {
    if (!piece) {
      FML_DLOG(ERROR) << "Invalid kernel piece.";
      continue;
    }
    std::promise<std::unique_ptr<const fml::Mapping>> promise;
    pieces.push_back(promise.get_future());
    promise.set_value(std::move(piece));
  }
  return CreateForKernelList(std::move(pieces));
}

References CreateForKernelList(), and FML_DLOG.

◆ DoPrepareIsolate()

virtual bool flutter::IsolateConfiguration::DoPrepareIsolate ( DartIsolate & isolate )

protectedpure virtual

Implemented in flutter::AppSnapshotIsolateConfiguration, flutter::KernelIsolateConfiguration, and flutter::KernelListIsolateConfiguration.

Referenced by PrepareIsolate().

◆ InferFromSettings()

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::InferFromSettings	(	const Settings &	settings,
		const std::shared_ptr< AssetManager > &	asset_manager = `nullptr`,
		const fml::RefPtr< fml::TaskRunner > &	io_worker = `nullptr`,
		IsolateLaunchType	launch_type = `IsolateLaunchType::kNewGroup`
	)

static

Attempts to infer the isolate configuration from the Settings object. If the VM is configured for AOT mode, snapshot resolution is attempted with predefined symbols present in the currently loaded process. In JIT mode, Dart kernel file resolution is attempted in the assets directory. If an IO worker is specified, snapshot resolution may be attempted on the serial worker task runner. The worker task runner thread must remain valid and running till after the shell associated with the engine used to launch the isolate for which this run configuration is used is collected.

Parameters

[in]	settings	The settings
[in]	asset_manager	The optional asset manager. This is used when using the legacy settings fields that specify the asset by name instead of a mappings callback.
[in]	io_worker	An optional IO worker. Specify `nullptr` if a worker should not be used or one is not available.
[in]	launch_type	Whether the isolate is launching to form a new group or as part of an existing group. If it is part of an existing group, the isolate will reuse resources if it can.

Returns: An isolate configuration if one can be inferred from the settings. If not, returns nullptr.

Definition at line 203 of file isolate_configuration.cc.

                                   {
  // Running in AOT mode.
  if (DartVM::IsRunningPrecompiledCode()) {
    return CreateForAppSnapshot();
  }
 
  if (launch_type == IsolateLaunchType::kExistingGroup) {
    return CreateForKernel(nullptr);
  }
 
  if (settings.application_kernels) {
    return CreateForKernelList(settings.application_kernels());
  }
 
  if (settings.application_kernel_asset.empty() &&
      settings.application_kernel_list_asset.empty()) {
    FML_DLOG(ERROR) << "application_kernel_asset or "
                       "application_kernel_list_asset must be set";
    return nullptr;
  }
 
  if (!asset_manager) {
    FML_DLOG(ERROR) << "No asset manager specified when attempting to create "
                       "isolate configuration.";
    return nullptr;
  }
 
  // Running from kernel snapshot. Requires asset manager.
  {
    std::unique_ptr<fml::Mapping> kernel =
        asset_manager->GetAsMapping(settings.application_kernel_asset);
    if (kernel) {
      return CreateForKernel(std::move(kernel));
    }
  }
 
  // Running from kernel divided into several pieces (for sharing). Requires
  // asset manager and io worker.
 
  if (!io_worker) {
    FML_DLOG(ERROR) << "No IO worker specified to load kernel pieces.";
    return nullptr;
  }
 
  {
    std::unique_ptr<fml::Mapping> kernel_list =
        asset_manager->GetAsMapping(settings.application_kernel_list_asset);
    if (!kernel_list) {
      FML_LOG(ERROR) << "Failed to load: "
                     << settings.application_kernel_list_asset;
      return nullptr;
    }
    auto kernel_pieces_paths = ParseKernelListPaths(std::move(kernel_list));
    auto kernel_mappings =
        PrepareKernelMappings(kernel_pieces_paths, asset_manager, io_worker);
    return CreateForKernelList(std::move(kernel_mappings));
  }
 
  return nullptr;
}

References flutter::Settings::application_kernel_asset, flutter::Settings::application_kernel_list_asset, flutter::Settings::application_kernels, CreateForAppSnapshot(), CreateForKernel(), CreateForKernelList(), FML_DLOG, FML_LOG, flutter::DartVM::IsRunningPrecompiledCode(), flutter::kExistingGroup, flutter::ParseKernelListPaths(), and flutter::PrepareKernelMappings().

Referenced by flutter::testing::CreateAndRunRootIsolate(), flutter::RunConfiguration::InferFromSettings(), flutter::testing::RunDartCodeInIsolateOnUITaskRunner(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), and flutter::testing::PlatformIsolateManagerTest::TestWithRootIsolate().

◆ IsNullSafetyEnabled()

virtual bool flutter::IsolateConfiguration::IsNullSafetyEnabled ( const DartSnapshot & snapshot )

pure virtual

Implemented in flutter::AppSnapshotIsolateConfiguration, flutter::KernelIsolateConfiguration, and flutter::KernelListIsolateConfiguration.

◆ PrepareIsolate()

bool flutter::IsolateConfiguration::PrepareIsolate ( DartIsolate & isolate )

When an isolate is created and sufficiently initialized to move it into the DartIsolate::Phase::LibrariesSetup phase, this method is invoked on the isolate to then move the isolate into the DartIsolate::Phase::Ready phase. Then isolate's main entrypoint is then invoked to move it into the DartIsolate::Phase::Running phase. This method will be called each time the root isolate is launched (which may be multiple times in cold-restart scenarios) as well as one each for any child isolates referenced by that isolate.

Parameters

isolate The isolate which is already in the DartIsolate::Phase::LibrariesSetup phase.

Returns: Returns true if the isolate could be configured. Unless this returns true, the engine will not move the isolate to the DartIsolate::Phase::Ready phase for subsequent run.

Definition at line 16 of file isolate_configuration.cc.

                                                              {
  if (isolate.GetPhase() != DartIsolate::Phase::LibrariesSetup) {
    FML_DLOG(ERROR)
        << "Isolate was in incorrect phase to be prepared for running.";
    return false;
  }
 
  return DoPrepareIsolate(isolate);
}

References DoPrepareIsolate(), FML_DLOG, flutter::DartIsolate::GetPhase(), and flutter::DartIsolate::LibrariesSetup.

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

runtime/isolate_configuration.h
runtime/isolate_configuration.cc

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IsolateConfiguration()

◆ ~IsolateConfiguration()

Member Function Documentation

◆ CreateForAppSnapshot()

◆ CreateForKernel()

◆ CreateForKernelList() [1/2]

◆ CreateForKernelList() [2/2]

◆ DoPrepareIsolate()

◆ InferFromSettings()

◆ IsNullSafetyEnabled()

◆ PrepareIsolate()