Flutter Engine
flutter::IsolateConfiguration Class Referenceabstract

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:
flutter::AppSnapshotIsolateConfiguration flutter::KernelIsolateConfiguration flutter::KernelListIsolateConfiguration

Public Member Functions

 IsolateConfiguration ()
 Create an isolate configuration. This has no threading restrictions. More...
 
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). More...
 
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. More...
 
virtual bool IsNullSafetyEnabled (const DartSnapshot &snapshot)=0
 

Static Public Member Functions

static std::unique_ptr< IsolateConfigurationInferFromSettings (const Settings &settings, std::shared_ptr< AssetManager > asset_manager=nullptr, fml::RefPtr< fml::TaskRunner > io_worker=nullptr)
 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. More...
 
static std::unique_ptr< IsolateConfigurationCreateForAppSnapshot ()
 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. More...
 
static std::unique_ptr< IsolateConfigurationCreateForKernelList (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. More...
 
static std::unique_ptr< IsolateConfigurationCreateForKernel (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. More...
 
static std::unique_ptr< IsolateConfigurationCreateForKernelList (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. More...
 

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 38 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 259 of file isolate_configuration.cc.

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

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

◆ 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]kernelThe kernel snapshot.
Returns
A JIT isolate configuration.

Definition at line 263 of file isolate_configuration.cc.

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

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

◆ 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_piecesThe list of futures to Dart kernel snapshots.
Returns
A JIT isolate configuration.

Definition at line 283 of file isolate_configuration.cc.

Referenced by CreateForKernelList(), and InferFromSettings().

285  {
286  return std::make_unique<KernelListIsolateConfiguration>(
287  std::move(kernel_pieces));
288 }

◆ 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_piecesThe kernel pieces
Returns
{ description_of_the_return_value }

Definition at line 268 of file isolate_configuration.cc.

References CreateForKernelList(), and FML_DLOG.

269  {
270  std::vector<std::future<std::unique_ptr<const fml::Mapping>>> pieces;
271  for (auto& piece : kernel_pieces) {
272  if (!piece) {
273  FML_DLOG(ERROR) << "Invalid kernel piece.";
274  continue;
275  }
276  std::promise<std::unique_ptr<const fml::Mapping>> promise;
277  pieces.push_back(promise.get_future());
278  promise.set_value(std::move(piece));
279  }
280  return CreateForKernelList(std::move(pieces));
281 }
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 s...
#define FML_DLOG(severity)
Definition: logging.h:85

◆ DoPrepareIsolate()

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

◆ InferFromSettings()

std::unique_ptr< IsolateConfiguration > flutter::IsolateConfiguration::InferFromSettings ( const Settings settings,
std::shared_ptr< AssetManager asset_manager = nullptr,
fml::RefPtr< fml::TaskRunner io_worker = nullptr 
)
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]settingsThe settings
[in]asset_managerThe 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_workerAn optional IO worker. Specify nullptr is a worker should not be used or one is not available.
Returns
An isolate configuration if one can be inferred from the settings. If not, returns nullptr.

Definition at line 198 of file isolate_configuration.cc.

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::ParseKernelListPaths(), and flutter::PrepareKernelMappings().

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

201  {
202  // Running in AOT mode.
204  return CreateForAppSnapshot();
205  }
206 
207  if (settings.application_kernels) {
208  return CreateForKernelList(settings.application_kernels());
209  }
210 
211  if (settings.application_kernel_asset.empty() &&
212  settings.application_kernel_list_asset.empty()) {
213  FML_DLOG(ERROR) << "application_kernel_asset or "
214  "application_kernel_list_asset must be set";
215  return nullptr;
216  }
217 
218  if (!asset_manager) {
219  FML_DLOG(ERROR) << "No asset manager specified when attempting to create "
220  "isolate configuration.";
221  return nullptr;
222  }
223 
224  // Running from kernel snapshot. Requires asset manager.
225  {
226  std::unique_ptr<fml::Mapping> kernel =
227  asset_manager->GetAsMapping(settings.application_kernel_asset);
228  if (kernel) {
229  return CreateForKernel(std::move(kernel));
230  }
231  }
232 
233  // Running from kernel divided into several pieces (for sharing). Requires
234  // asset manager and io worker.
235 
236  if (!io_worker) {
237  FML_DLOG(ERROR) << "No IO worker specified to load kernel pieces.";
238  return nullptr;
239  }
240 
241  {
242  std::unique_ptr<fml::Mapping> kernel_list =
243  asset_manager->GetAsMapping(settings.application_kernel_list_asset);
244  if (!kernel_list) {
245  FML_LOG(ERROR) << "Failed to load: "
246  << settings.application_kernel_list_asset;
247  return nullptr;
248  }
249  auto kernel_pieces_paths = ParseKernelListPaths(std::move(kernel_list));
250  auto kernel_mappings = PrepareKernelMappings(std::move(kernel_pieces_paths),
251  asset_manager, io_worker);
252  return CreateForKernelList(std::move(kernel_mappings));
253  }
254 
255  return nullptr;
256 }
static std::unique_ptr< IsolateConfiguration > CreateForAppSnapshot()
Creates an AOT isolate configuration using snapshot symbols present in the currently loaded process...
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 s...
#define FML_LOG(severity)
Definition: logging.h:65
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 th...
static std::vector< std::string > ParseKernelListPaths(std::unique_ptr< fml::Mapping > kernel_list)
static bool IsRunningPrecompiledCode()
Checks if VM instances in the process can run precompiled code. This call can be made at any time and...
Definition: dart_vm.cc:199
static std::vector< std::future< std::unique_ptr< const fml::Mapping > > > PrepareKernelMappings(std::vector< std::string > kernel_pieces_paths, std::shared_ptr< AssetManager > asset_manager, fml::RefPtr< fml::TaskRunner > io_worker)
#define FML_DLOG(severity)
Definition: logging.h:85

◆ IsNullSafetyEnabled()

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

◆ 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
isolateThe 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.

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

16  {
17  if (isolate.GetPhase() != DartIsolate::Phase::LibrariesSetup) {
18  FML_DLOG(ERROR)
19  << "Isolate was in incorrect phase to be prepared for running.";
20  return false;
21  }
22 
23  return DoPrepareIsolate(isolate);
24 }
#define FML_DLOG(severity)
Definition: logging.h:85
virtual bool DoPrepareIsolate(DartIsolate &isolate)=0

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