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

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

	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.

	~RunConfiguration ()
	There are no threading restrictions on the destruction of the run configuration.

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.

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.

void	SetEntrypoint (std::string entrypoint)
	Updates the main application entrypoint. If this is not set, the "main" method is used as the entrypoint.

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.

void	SetEntrypointArgs (std::vector< std::string > entrypoint_args)
	Updates the main application entrypoint arguments.

std::shared_ptr< AssetManager >	GetAssetManager () const

const std::string &	GetEntrypoint () const

const std::string &	GetEntrypointLibrary () const

const std::vector< std::string > &	GetEntrypointArgs () const

std::unique_ptr< IsolateConfiguration >	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.

Static Public Member Functions
static RunConfiguration	InferFromSettings (const Settings &settings, const fml::RefPtr< fml::TaskRunner > &io_worker=nullptr, IsolateLaunchType launch_type=IsolateLaunchType::kNewGroup)
	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 loaded process. The entrypoint defaults to the "main" method in the root library.

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 )

explicit

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] configuration The configuration

Definition at line 40 of file run_configuration.cc.

    : RunConfiguration(std::move(configuration),
                       std::make_shared<AssetManager>()) {
  PersistentCache::SetAssetManager(asset_manager_);
}

◆ 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]	configuration	The configuration
[in]	asset_manager	The asset manager

Definition at line 47 of file run_configuration.cc.

    : isolate_configuration_(std::move(configuration)),
      asset_manager_(std::move(asset_manager)) {
  PersistentCache::SetAssetManager(asset_manager_);
}

◆ 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

config The run configuration to move.

◆ ~RunConfiguration()

flutter::RunConfiguration::~RunConfiguration ( )

default

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

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] resolver The 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 63 of file run_configuration.cc.

                                           {
  if (!resolver || !resolver->IsValid()) {
    return false;
  }
 
  asset_manager_->PushBack(std::move(resolver));
  return true;
}

◆ GetAssetManager()

std::shared_ptr< AssetManager > flutter::RunConfiguration::GetAssetManager ( ) const

Returns: The asset manager referencing all previously registered asset resolvers.

Definition at line 88 of file run_configuration.cc.

                                                                    {
  return asset_manager_;
}

◆ GetEntrypoint()

const std::string & flutter::RunConfiguration::GetEntrypoint ( ) const

Returns: The main Dart entrypoint to be used for the root isolate.

Definition at line 92 of file run_configuration.cc.

                                                       {
  return entrypoint_;
}

◆ GetEntrypointArgs()

const std::vector< std::string > & flutter::RunConfiguration::GetEntrypointArgs ( ) const

Returns: Arguments passed as a List<String> to Dart's entrypoint function.

Definition at line 100 of file run_configuration.cc.

                                                                      {
  return entrypoint_args_;
}

◆ 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 96 of file run_configuration.cc.

                                                              {
  return entrypoint_library_;
}

◆ InferFromSettings()

RunConfiguration flutter::RunConfiguration::InferFromSettings	(	const Settings &	settings,
		const fml::RefPtr< fml::TaskRunner > &	io_worker = `nullptr`,
		IsolateLaunchType	launch_type = `IsolateLaunchType::kNewGroup`
	)

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 loaded process. The entrypoint defaults to the "main" method in the root library.

Parameters

[in]	settings	The settings object used to look for the various snapshots and settings. This is usually initialized from command line arguments.
[in]	io_worker	An 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.
[in]	launch_type	Whether to launch the new isolate into an existing group or a new one.

Returns: A run configuration. Depending on the completeness of the settings, This object may potentially be invalid.

Definition at line 19 of file run_configuration.cc.

                                   {
  auto asset_manager = std::make_shared<AssetManager>();
 
  if (fml::UniqueFD::traits_type::IsValid(settings.assets_dir)) {
    asset_manager->PushBack(std::make_unique<DirectoryAssetBundle>(
        fml::Duplicate(settings.assets_dir), true));
  }
 
  asset_manager->PushBack(std::make_unique<DirectoryAssetBundle>(
      fml::OpenDirectory(settings.assets_path.c_str(), false,
                         fml::FilePermission::kRead),
      true));
 
  return {IsolateConfiguration::InferFromSettings(settings, asset_manager,
                                                  io_worker, launch_type),
          asset_manager};
}

◆ 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 59 of file run_configuration.cc.

                                     {
  return asset_manager_ && isolate_configuration_;
}

◆ 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] entrypoint The entrypoint to use.

Definition at line 73 of file run_configuration.cc.

                                                         {
  entrypoint_ = std::move(entrypoint);
}

◆ 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]	entrypoint	The entrypoint
[in]	library	The library

Definition at line 77 of file run_configuration.cc.

                                                                  {
  SetEntrypoint(std::move(entrypoint));
  entrypoint_library_ = std::move(library);
}

◆ SetEntrypointArgs()

void flutter::RunConfiguration::SetEntrypointArgs ( std::vector< std::string > entrypoint_args )

Updates the main application entrypoint arguments.

Parameters

[in] entrypoint_args The entrypoint arguments to use.

Definition at line 83 of file run_configuration.cc.

                                          {
  entrypoint_args_ = std::move(entrypoint_args);
}

◆ 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 105 of file run_configuration.cc.

                                           {
  return std::move(isolate_configuration_);
}

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

shell/common/run_configuration.h
shell/common/run_configuration.cc

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RunConfiguration() [1/3]

◆ RunConfiguration() [2/3]

◆ RunConfiguration() [3/3]

◆ ~RunConfiguration()

Member Function Documentation

◆ AddAssetResolver()

◆ GetAssetManager()

◆ GetEntrypoint()

◆ GetEntrypointArgs()

◆ GetEntrypointLibrary()

◆ InferFromSettings()

◆ IsValid()

◆ SetEntrypoint()

◆ SetEntrypointAndLibrary()

◆ SetEntrypointArgs()

◆ TakeIsolateConfiguration()