Flutter Engine
flutter::RunConfiguration Class Reference

Specifies all the configuration required by the runtime library to launch the root isolate. This object may be created on any thread but must be given to the |Run| call of the |Engine| on the UI thread. The configuration object is used to specify how the root isolate finds its snapshots, assets, root library and the "main" entrypoint. More...

#include <run_configuration.h>

Public Member Functions

 RunConfiguration (std::unique_ptr< IsolateConfiguration > configuration)
 Creates a run configuration with only an isolate configuration. There is no asset manager and default entrypoint and root library are used ("main" in root library). More...
 
 RunConfiguration (std::unique_ptr< IsolateConfiguration > configuration, std::shared_ptr< AssetManager > asset_manager)
 Creates a run configuration with the specified isolate configuration and asset manager. The default entrypoint and root library are used ("main" in root library). More...
 
 RunConfiguration (RunConfiguration &&config)
 Run configurations cannot be copied because it may not always be possible to copy the underlying isolate snapshots. If multiple run configurations share the same underlying snapshots, creating a configuration from isolate snapshots sharing the same underlying buffers is recommended. More...
 
 ~RunConfiguration ()
 There are no threading restrictions on the destruction of the run configuration. More...
 
bool IsValid () const
 A valid run configuration only guarantees that the engine should be able to find the assets and the isolate snapshots when it attempts to launch the root isolate. The validity of the snapshot cannot be determined yet. That determination can only be made when the configuration is used to run the root isolate in the engine. However, the engine will always reject an invalid run configuration. More...
 
bool AddAssetResolver (std::unique_ptr< AssetResolver > resolver)
 Asset managers maintain a list of resolvers that are checked in order when attempting to locate an asset. This method adds a resolver to the end of the list. More...
 
void SetEntrypoint (std::string entrypoint)
 Updates the main application entrypoint. If this is not set, the "main" method is used as the entrypoint. More...
 
void SetEntrypointAndLibrary (std::string entrypoint, std::string library)
 Specifies the main Dart entrypoint and the library to find that entrypoint in. By default, this is the "main" method in the root library. The root library may be specified by entering the empty string as the second argument. More...
 
std::shared_ptr< AssetManagerGetAssetManager () const
 
const std::string & GetEntrypoint () const
 
const std::string & GetEntrypointLibrary () const
 
std::unique_ptr< IsolateConfigurationTakeIsolateConfiguration ()
 The engine uses this to take the isolate configuration from the run configuration. The run configuration is no longer valid after this call is made. The non-copyable nature of some of the snapshots referenced in the isolate configuration is why the run configuration as a whole is not copyable. More...
 

Static Public Member Functions

static RunConfiguration InferFromSettings (const Settings &settings, fml::RefPtr< fml::TaskRunner > io_worker=nullptr)
 Attempts to infer a run configuration from the settings object. This tries to create a run configuration with sensible defaults for the given Dart VM runtime mode. In JIT mode, this will attempt to look for the VM and isolate snapshots in the assets directory (must be specified in settings). In AOT mode, it will attempt to look for known snapshot symbols in the currently currently loaded process. The entrypoint defaults to the "main" method in the root library. More...
 

Detailed Description

Specifies all the configuration required by the runtime library to launch the root isolate. This object may be created on any thread but must be given to the |Run| call of the |Engine| on the UI thread. The configuration object is used to specify how the root isolate finds its snapshots, assets, root library and the "main" entrypoint.

Definition at line 29 of file run_configuration.h.

Constructor & Destructor Documentation

◆ RunConfiguration() [1/3]

flutter::RunConfiguration::RunConfiguration ( std::unique_ptr< IsolateConfiguration configuration)

Creates a run configuration with only an isolate configuration. There is no asset manager and default entrypoint and root library are used ("main" in root library).

Parameters
[in]configurationThe configuration

Definition at line 37 of file run_configuration.cc.

References flutter::PersistentCache::SetAssetManager().

Referenced by RunConfiguration().

39  : RunConfiguration(std::move(configuration),
40  std::make_shared<AssetManager>()) {
41  PersistentCache::SetAssetManager(asset_manager_);
42 }
RunConfiguration(std::unique_ptr< IsolateConfiguration > configuration)
Creates a run configuration with only an isolate configuration. There is no asset manager and default...
static void SetAssetManager(std::shared_ptr< AssetManager > value)

◆ RunConfiguration() [2/3]

flutter::RunConfiguration::RunConfiguration ( std::unique_ptr< IsolateConfiguration configuration,
std::shared_ptr< AssetManager asset_manager 
)

Creates a run configuration with the specified isolate configuration and asset manager. The default entrypoint and root library are used ("main" in root library).

Parameters
[in]configurationThe configuration
[in]asset_managerThe asset manager

Definition at line 44 of file run_configuration.cc.

References RunConfiguration(), flutter::PersistentCache::SetAssetManager(), and ~RunConfiguration().

47  : isolate_configuration_(std::move(configuration)),
48  asset_manager_(std::move(asset_manager)) {
49  PersistentCache::SetAssetManager(asset_manager_);
50 }
static void SetAssetManager(std::shared_ptr< AssetManager > value)

◆ RunConfiguration() [3/3]

flutter::RunConfiguration::RunConfiguration ( RunConfiguration &&  config)
default

Run configurations cannot be copied because it may not always be possible to copy the underlying isolate snapshots. If multiple run configurations share the same underlying snapshots, creating a configuration from isolate snapshots sharing the same underlying buffers is recommended.

Parameters
configThe run configuration to move.

◆ ~RunConfiguration()

flutter::RunConfiguration::~RunConfiguration ( )
default

There are no threading restrictions on the destruction of the run configuration.

Referenced by RunConfiguration().

Member Function Documentation

◆ AddAssetResolver()

bool flutter::RunConfiguration::AddAssetResolver ( std::unique_ptr< AssetResolver resolver)

Asset managers maintain a list of resolvers that are checked in order when attempting to locate an asset. This method adds a resolver to the end of the list.

Parameters
[in]resolverThe asset resolver to add to the engine of the list resolvers maintained by the asset manager.
Returns
Returns whether the resolver was successfully registered. The resolver must be valid for its registration to be successful.

Definition at line 60 of file run_configuration.cc.

Referenced by flutter::ServiceProtocolFailureError().

61  {
62  if (!resolver || !resolver->IsValid()) {
63  return false;
64  }
65 
66  asset_manager_->PushBack(std::move(resolver));
67  return true;
68 }

◆ GetAssetManager()

std::shared_ptr< AssetManager > flutter::RunConfiguration::GetAssetManager ( ) const
Returns
The asset manager referencing all previously registered asset resolvers.

Definition at line 80 of file run_configuration.cc.

Referenced by flutter::Engine::Run().

80  {
81  return asset_manager_;
82 }

◆ GetEntrypoint()

const std::string & flutter::RunConfiguration::GetEntrypoint ( ) const
Returns
The main Dart entrypoint to be used for the root isolate.

Definition at line 84 of file run_configuration.cc.

Referenced by flutter::Engine::Run().

84  {
85  return entrypoint_;
86 }

◆ GetEntrypointLibrary()

const std::string & flutter::RunConfiguration::GetEntrypointLibrary ( ) const
Returns
The name of the library in which the main entrypoint resides. If empty, the root library is used.

Definition at line 88 of file run_configuration.cc.

Referenced by flutter::Engine::Run().

88  {
89  return entrypoint_library_;
90 }

◆ InferFromSettings()

RunConfiguration flutter::RunConfiguration::InferFromSettings ( const Settings settings,
fml::RefPtr< fml::TaskRunner io_worker = nullptr 
)
static

Attempts to infer a run configuration from the settings object. This tries to create a run configuration with sensible defaults for the given Dart VM runtime mode. In JIT mode, this will attempt to look for the VM and isolate snapshots in the assets directory (must be specified in settings). In AOT mode, it will attempt to look for known snapshot symbols in the currently currently loaded process. The entrypoint defaults to the "main" method in the root library.

Parameters
[in]settingsThe settings object used to look for the various snapshots and settings. This is usually initialized from command line arguments.
[in]io_workerAn optional IO worker. Resolving and reading the various snapshots may be slow. Providing an IO worker will ensure that realization of these snapshots happens on a worker thread instead of the calling thread. Note that the work done to realize the snapshots may occur after this call returns. If is the embedder's responsibility to make sure the serial worker is kept alive for the lifetime of the shell associated with the engine that this run configuration is given to.
Returns
A run configuration. Depending on the completeness of the settings, This object may potentially be invalid.

Definition at line 17 of file run_configuration.cc.

References flutter::Settings::assets_dir, flutter::Settings::assets_path, fml::Duplicate(), flutter::IsolateConfiguration::InferFromSettings(), fml::internal::os_unix::UniqueFDTraits::IsValid(), fml::kRead, and fml::OpenDirectory().

Referenced by flutter_runner::Engine::Engine(), FlutterEngineInitialize(), FlutterDartProject::initWithPrecompiledDartBundle:, flutter::testing::TEST_F(), and flutter::testing::TestSimulatedInputEvents().

19  {
20  auto asset_manager = std::make_shared<AssetManager>();
21 
22  if (fml::UniqueFD::traits_type::IsValid(settings.assets_dir)) {
23  asset_manager->PushBack(std::make_unique<DirectoryAssetBundle>(
24  fml::Duplicate(settings.assets_dir), true));
25  }
26 
27  asset_manager->PushBack(std::make_unique<DirectoryAssetBundle>(
28  fml::OpenDirectory(settings.assets_path.c_str(), false,
30  true));
31 
32  return {IsolateConfiguration::InferFromSettings(settings, asset_manager,
33  io_worker),
34  asset_manager};
35 }
fml::UniqueFD Duplicate(fml::UniqueFD::element_type descriptor)
Definition: file_posix.cc:120
static bool IsValid(int value)
Definition: unique_fd.h:39
fml::UniqueFD OpenDirectory(const char *path, bool create_if_necessary, FilePermission permission)
Definition: file_posix.cc:94
static std::unique_ptr< IsolateConfiguration > InferFromSettings(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...

◆ IsValid()

bool flutter::RunConfiguration::IsValid ( ) const

A valid run configuration only guarantees that the engine should be able to find the assets and the isolate snapshots when it attempts to launch the root isolate. The validity of the snapshot cannot be determined yet. That determination can only be made when the configuration is used to run the root isolate in the engine. However, the engine will always reject an invalid run configuration.

Attention
A valid run configuration does not mean that the root isolate will always be launched. It only indicates that the various snapshots are isolate snapshots and asset managers are present and accounted for. The validity of the snapshots will only be checked when the engine attempts to launch the root isolate.
Returns
Returns whether the snapshots and asset manager registrations are valid.

Definition at line 56 of file run_configuration.cc.

Referenced by flutter::Engine::Restart(), flutter::Engine::Run(), and flutter::EmbedderEngine::RunRootIsolate().

56  {
57  return asset_manager_ && isolate_configuration_;
58 }

◆ SetEntrypoint()

void flutter::RunConfiguration::SetEntrypoint ( std::string  entrypoint)

Updates the main application entrypoint. If this is not set, the "main" method is used as the entrypoint.

Parameters
[in]entrypointThe entrypoint to use.

Definition at line 70 of file run_configuration.cc.

Referenced by flutter::RunBundleAndSnapshotFromLibrary(), SetEntrypointAndLibrary(), and flutter::testing::TEST_F().

70  {
71  entrypoint_ = std::move(entrypoint);
72 }

◆ SetEntrypointAndLibrary()

void flutter::RunConfiguration::SetEntrypointAndLibrary ( std::string  entrypoint,
std::string  library 
)

Specifies the main Dart entrypoint and the library to find that entrypoint in. By default, this is the "main" method in the root library. The root library may be specified by entering the empty string as the second argument.

See also
SetEntrypoint()
Parameters
[in]entrypointThe entrypoint
[in]libraryThe library

Definition at line 74 of file run_configuration.cc.

References SetEntrypoint().

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

75  {
76  SetEntrypoint(entrypoint);
77  entrypoint_library_ = std::move(library);
78 }
void SetEntrypoint(std::string entrypoint)
Updates the main application entrypoint. If this is not set, the "main" method is used as the entrypo...

◆ TakeIsolateConfiguration()

std::unique_ptr< IsolateConfiguration > flutter::RunConfiguration::TakeIsolateConfiguration ( )

The engine uses this to take the isolate configuration from the run configuration. The run configuration is no longer valid after this call is made. The non-copyable nature of some of the snapshots referenced in the isolate configuration is why the run configuration as a whole is not copyable.

Returns
The run configuration if one is present.

Definition at line 93 of file run_configuration.cc.

Referenced by flutter::Engine::Run().

93  {
94  return std::move(isolate_configuration_);
95 }

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