#include <runtime_controller.h>

Inheritance diagram for flutter::RuntimeController:

Public Types
using	AddViewCallback = std::function< void(bool added)>

Public Member Functions
	RuntimeController (RuntimeDelegate &p_client, DartVM *vm, fml::RefPtr< const DartSnapshot > p_isolate_snapshot, const std::function< void(int64_t)> &idle_notification_callback, const PlatformData &platform_data, const fml::closure &isolate_create_callback, const fml::closure &isolate_shutdown_callback, std::shared_ptr< const fml::Mapping > p_persistent_isolate_data, const UIDartState::Context &context)
	Creates a new instance of a runtime controller. This is usually only done by the engine instance associated with the shell.

std::unique_ptr< RuntimeController >	Spawn (RuntimeDelegate &p_client, const std::string &advisory_script_uri, const std::string &advisory_script_entrypoint, const std::function< void(int64_t)> &idle_notification_callback, const fml::closure &isolate_create_callback, const fml::closure &isolate_shutdown_callback, const std::shared_ptr< const fml::Mapping > &persistent_isolate_data, fml::WeakPtr< IOManager > io_manager, fml::WeakPtr< ImageDecoder > image_decoder, fml::WeakPtr< ImageGeneratorRegistry > image_generator_registry, fml::TaskRunnerAffineWeakPtr< SnapshotDelegate > snapshot_delegate) const
	Create a RuntimeController that shares as many resources as possible with the calling RuntimeController such that together they occupy less memory.

	~RuntimeController () override

bool	LaunchRootIsolate (const Settings &settings, const fml::closure &root_isolate_create_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)
	Launches the isolate using the window data associated with this runtime controller. Before this call, the Dart isolate has not been initialized. On successful return, the caller can assume that the isolate is in the `DartIsolate::Phase::Running` phase.

std::unique_ptr< RuntimeController >	Clone () const
	Clone the runtime controller. Launching an isolate with a cloned runtime controller will use the same snapshots and copies all window data to the new instance. This is usually only used in the debug runtime mode to support the cold-restart scenario.

void	AddView (int64_t view_id, const ViewportMetrics &view_metrics, AddViewCallback callback)
	Notify the isolate that a new view is available.

bool	RemoveView (int64_t view_id)
	Notify the isolate that a view is no longer available.

bool	SetViewportMetrics (int64_t view_id, const ViewportMetrics &metrics)
	Forward the specified viewport metrics to the running isolate. If the isolate is not running, these metrics will be saved and flushed to the isolate when it starts.

bool	SetDisplays (const std::vector< DisplayData > &displays)
	Forward the specified display metrics to the running isolate. If the isolate is not running, these metrics will be saved and flushed to the isolate when it starts.

bool	SetLocales (const std::vector< std::string > &locale_data)
	Forward the specified locale data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

bool	SetUserSettingsData (const std::string &data)
	Forward the user settings data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

bool	SetInitialLifecycleState (const std::string &data)
	Forward the initial lifecycle state data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running. After the isolate starts running, the current lifecycle state is pushed to it via the "flutter/lifecycle" channel.

bool	SetSemanticsEnabled (bool enabled)
	Notifies the running isolate about whether the semantics tree should be generated or not. If the isolate is not running, this preference will be saved and flushed to the isolate when it starts running.

bool	SetAccessibilityFeatures (int32_t flags)
	Forward the preference of accessibility features that must be enabled in the semantics tree to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

bool	BeginFrame (fml::TimePoint frame_time, uint64_t frame_number)
	Notifies the running isolate that it should start generating a new frame.

bool	ReportTimings (std::vector< int64_t > timings)
	Dart code cannot fully measure the time it takes for a specific frame to be rendered. This is because Dart code only runs on the UI task runner. That is only a small part of the overall frame workload. The raster task runner frame workload is executed on a thread where Dart code cannot run (and hence instrument). Besides, due to the pipelined nature of rendering in Flutter, there may be multiple frame workloads being processed at any given time. However, for non-Timeline based profiling, it is useful for trace collection and processing to happen in Dart. To do this, the raster task runner frame workloads need to be instrumented separately. After a set number of these profiles have been gathered, they need to be reported back to Dart code. The engine reports this extra instrumentation information back to Dart code running on the engine by invoking this method at predefined intervals.

virtual bool	NotifyIdle (fml::TimeDelta deadline)
	Notify the Dart VM that no frame workloads are expected on the UI task runner till the specified deadline. The VM uses this opportunity to perform garbage collection operations is a manner that interferes as little as possible with frame rendering.

virtual bool	NotifyDestroyed ()
	Notify the Dart VM that the attached flutter view has been destroyed. This gives the Dart VM to perform some cleanup activities e.g: perform garbage collection to free up any unused memory.

virtual bool	IsRootIsolateRunning ()
	Returns if the root isolate is running. The isolate must be transitioned to the running phase manually. The isolate can stop running if it terminates execution on its own.

virtual bool	DispatchPlatformMessage (std::unique_ptr< PlatformMessage > message)
	Dispatch the specified platform message to running root isolate.

bool	DispatchPointerDataPacket (const PointerDataPacket &packet)
	Dispatch the specified pointer data message to the running root isolate.

bool	DispatchSemanticsAction (int32_t node_id, SemanticsAction action, fml::MallocMapping args)
	Dispatch the semantics action to the specified accessibility node.

Dart_Port	GetMainPort ()
	Gets the main port identifier of the root isolate.

std::string	GetIsolateName ()
	Gets the debug name of the root isolate. But default, the debug name of the isolate is derived from its advisory script URI, advisory main entrypoint and its main port name. For example, "main.dart$main-1234" where the script URI is "main.dart", the entrypoint is "main" and the port name "1234". Once launched, the isolate may re-christen itself using a name it selects via `setIsolateDebugName` in `window.dart`. This name is purely advisory and only used by instrumentation and reporting purposes.

bool	HasLivePorts ()
	Returns if the root isolate has any live receive ports.

tonic::DartErrorHandleType	GetLastError ()
	Get the last error encountered by the microtask queue.

std::optional< std::string >	GetRootIsolateServiceID () const
	Get the service ID of the root isolate if the root isolate is running.

std::optional< uint32_t >	GetRootIsolateReturnCode ()
	Get the return code specified by the root isolate (if one is present).

uint64_t	GetRootIsolateGroup () const
	Get an identifier that represents the Dart isolate group the root isolate is in.

void	LoadDartDeferredLibrary (intptr_t loading_unit_id, std::unique_ptr< const fml::Mapping > snapshot_data, std::unique_ptr< const fml::Mapping > snapshot_instructions)
	Loads the Dart shared library into the Dart VM. When the Dart library is loaded successfully, the Dart future returned by the originating loadLibrary() call completes.

virtual void	LoadDartDeferredLibraryError (intptr_t loading_unit_id, const std::string error_message, bool transient)
	Indicates to the dart VM that the request to load a deferred library with the specified loading unit id has failed.

void	RequestDartDeferredLibrary (intptr_t loading_unit_id) override
	Invoked when the Dart VM requests that a deferred library be loaded. Notifies the engine that the deferred library identified by the specified loading unit id should be downloaded and loaded into the Dart VM via `LoadDartDeferredLibrary`

std::shared_ptr< const fml::Mapping >	GetPersistentIsolateData () override
	The embedder can specify data that the isolate can request synchronously on launch. This accessor fetches that data.

const fml::WeakPtr< IOManager > &	GetIOManager () const

virtual DartVM *	GetDartVM () const

const fml::RefPtr< const DartSnapshot > &	GetIsolateSnapshot () const

const PlatformData &	GetPlatformData () const

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

const fml::TaskRunnerAffineWeakPtr< SnapshotDelegate > &	GetSnapshotDelegate () const

std::weak_ptr< const DartIsolate >	GetRootIsolate () const

std::shared_ptr< PlatformIsolateManager >	GetPlatformIsolateManager () override

void	ShutdownPlatformIsolates ()
	Shuts down all registered platform isolates. Must be called from the platform thread.

Protected Member Functions
	RuntimeController (RuntimeDelegate &p_client, const TaskRunners &task_runners)
	Constructor for Mocks.

Protected Member Functions inherited from flutter::PlatformConfigurationClient
virtual	~PlatformConfigurationClient ()

Private Member Functions
std::string	DefaultRouteName () override
	The route or path that the embedder requested when the application was launched.

void	ScheduleFrame () override
	Requests that, at the next appropriate opportunity, a new frame be scheduled for rendering.

void	EndWarmUpFrame () override
	Called when a warm up frame has ended.

void	Render (int64_t view_id, Scene *scene, double width, double height) override
	Updates the client's rendering on the GPU with the newly provided Scene.

void	UpdateSemantics (SemanticsUpdate *update) override
	Receives an updated semantics tree from the Framework.

void	HandlePlatformMessage (std::unique_ptr< PlatformMessage > message) override
	When the Flutter application has a message to send to the underlying platform, the message needs to be forwarded to the platform on the appropriate thread (via the platform task runner). The PlatformConfiguration delegates this task to the engine via this method.

FontCollection &	GetFontCollection () override
	Returns the current collection of fonts available on the platform.

std::shared_ptr< AssetManager >	GetAssetManager () override
	Returns the current collection of assets available on the platform.

void	UpdateIsolateDescription (const std::string isolate_name, int64_t isolate_port) override
	Notifies this client of the name of the root isolate and its port when that isolate is launched, restarted (in the cold-restart scenario) or the application itself updates the name of the root isolate (via `Window.setIsolateDebugName` in `window.dart`). The name of the isolate is meaningless to the engine but is used in instrumentation and tooling. Currently, this information is to update the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation.

void	SetNeedsReportTimings (bool value) override
	Notifies this client that the application has an opinion about whether its frame timings need to be reported backed to it. Due to the asynchronous nature of rendering in Flutter, it is not possible for the application to determine the total time it took to render a specific frame. While the layer-tree is constructed on the UI thread, it needs to be rendering on the raster thread. Dart code cannot execute on this thread. So any instrumentation about the frame times gathered on this thread needs to be aggregated and sent back to the UI thread for processing in Dart.

std::unique_ptr< std::vector< std::string > >	ComputePlatformResolvedLocale (const std::vector< std::string > &supported_locale_data) override
	Directly invokes platform-specific APIs to compute the locale the platform would have natively resolved to.

void	SendChannelUpdate (std::string name, bool listening) override
	Invoked when a listener is registered on a platform channel.

double	GetScaledFontSize (double unscaled_font_size, int configuration_id) const override
	Synchronously invokes platform-specific APIs to apply the system text scaling on the given unscaled font size.

Detailed Description

Represents an instance of a running root isolate with window bindings. In normal operation, a single instance of this object is owned by the engine per shell. This object may only be created, used, and collected on the UI task runner. Window state queried by the root isolate is stored by this object. In cold-restart scenarios, the engine may collect this before installing a new runtime controller in its place. The Clone method may be used by the engine to copy the currently accumulated window state so it can be referenced by the new runtime controller.

When RuntimeController is created, it takes some time before the root isolate becomes ready. Operation during this gap is stored by RuntimeController and flushed to the Dart VM when the isolate becomes ready before the entrypoint function. See PlatformData.

Definition at line 51 of file runtime_controller.h.

Member Typedef Documentation

◆ AddViewCallback

using flutter::RuntimeController::AddViewCallback = std::function<void(bool added)>

A callback that's invoked after this RuntimeController attempts to add a view to the Dart isolate.

If the Dart isolate is not launched yet, this callback will be stored and invoked after the isolate is launched.

The added parameter is false if the add operation fails or was cancelled while pending using RemoveView.

Definition at line 61 of file runtime_controller.h.

Constructor & Destructor Documentation

◆ RuntimeController() [1/2]

flutter::RuntimeController::RuntimeController	(	RuntimeDelegate &	p_client,
		DartVM *	vm,
		fml::RefPtr< const DartSnapshot >	p_isolate_snapshot,
		const std::function< void(int64_t)> &	idle_notification_callback,
		const PlatformData &	platform_data,
		const fml::closure &	isolate_create_callback,
		const fml::closure &	isolate_shutdown_callback,
		std::shared_ptr< const fml::Mapping >	p_persistent_isolate_data,
		const UIDartState::Context &	context
	)

Creates a new instance of a runtime controller. This is usually only done by the engine instance associated with the shell.

Parameters

	client	The runtime delegate. This is usually the `Engine` instance.
	vm	A reference to a running Dart VM. The runtime controller must be collected before the VM is destroyed (this order is guaranteed by the shell).
[in]	idle_notification_callback	The idle notification callback. This allows callers to run native code in isolate scope when the VM is about to be notified that the engine is going to be idle.
[in]	platform_data	The window data (if exists).
[in]	isolate_create_callback	The isolate create callback. This allows callers to run native code in isolate scope on the UI task runner as soon as the root isolate has been created.
[in]	isolate_shutdown_callback	The isolate shutdown callback. This allows callers to run native code in isolate scoped on the UI task runner just as the root isolate is about to be torn down.
[in]	persistent_isolate_data	Unstructured persistent read-only data that the root isolate can access in a synchronous manner.
[in]	context	Engine-owned state which is accessed by the root dart isolate.

Definition at line 28 of file runtime_controller.cc.

    : client_(p_client),
      vm_(p_vm),
      isolate_snapshot_(std::move(p_isolate_snapshot)),
      idle_notification_callback_(p_idle_notification_callback),
      platform_data_(p_platform_data),
      isolate_create_callback_(p_isolate_create_callback),
      isolate_shutdown_callback_(p_isolate_shutdown_callback),
      persistent_isolate_data_(std::move(p_persistent_isolate_data)),
      context_(p_context) {}

◆ ~RuntimeController()

flutter::RuntimeController::~RuntimeController ( )

override

Definition at line 86 of file runtime_controller.cc.

                                      {
  FML_DCHECK(Dart_CurrentIsolate() == nullptr);
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  if (root_isolate) {
    root_isolate->SetReturnCodeCallback(nullptr);
    auto result = root_isolate->Shutdown();
    if (!result) {
      FML_DLOG(ERROR) << "Could not shutdown the root isolate.";
    }
    root_isolate_ = {};
  }
}

◆ RuntimeController() [2/2]

flutter::RuntimeController::RuntimeController	(	RuntimeDelegate &	p_client,
		const TaskRunners &	task_runners
	)

protected

Constructor for Mocks.

Definition at line 24 of file runtime_controller.cc.

26 : client_(p_client), vm_(nullptr), context_(task_runners) {}

Member Function Documentation

◆ AddView()

void flutter::RuntimeController::AddView	(	int64_t	view_id,
		const ViewportMetrics &	view_metrics,
		AddViewCallback	callback
	)

Notify the isolate that a new view is available.

        A view must be added before other methods can refer to it,
        including the implicit view. Adding a view that already exists
        is an error.

        The `callback` is invoked when the add operation is attempted,
        failed, or is cancelled.

        If the isolate is not running, the view add will be queued and
        flushed to the isolate when it starts. Calling `RemoveView`
        before the isolate is launched cancels the add operation.

        If the isolate is running, a frame will be scheduled.

Parameters

[in]	view_id	The ID of the new view.
[in]	viewport_metrics	The initial viewport metrics for the view.
[in]	callback	Callback that will be invoked after the add operation is attempted or cancelled.

Definition at line 157 of file runtime_controller.cc.

                                                          {
  // If the Dart isolate is not running, |FlushRuntimeStateToIsolate| will
  // add the view and invoke the callback when the isolate is started.
  auto* platform_configuration = GetPlatformConfigurationIfAvailable();
  if (!platform_configuration) {
    FML_DCHECK(has_flushed_runtime_state_ == false);
 
    if (pending_add_view_callbacks_.find(view_id) !=
        pending_add_view_callbacks_.end()) {
      FML_LOG(ERROR) << "View #" << view_id << " is already pending creation.";
      callback(false);
      return;
    }
 
    platform_data_.viewport_metrics_for_views[view_id] = view_metrics;
    pending_add_view_callbacks_[view_id] = std::move(callback);
    return;
  }
 
  FML_DCHECK(has_flushed_runtime_state_ || pending_add_view_callbacks_.empty());
 
  platform_data_.viewport_metrics_for_views[view_id] = view_metrics;
  bool added = platform_configuration->AddView(view_id, view_metrics);
  if (added) {
    ScheduleFrame();
  }
 
  callback(added);
}

◆ BeginFrame()

bool flutter::RuntimeController::BeginFrame	(	fml::TimePoint	frame_time,
		uint64_t	frame_number
	)

Notifies the running isolate that it should start generating a new frame.

See also: Engine::BeginFrame for more context.

Parameters

[in] frame_time The point at which the current frame interval began. May be used by animation interpolators, physics simulations, etc.

Returns: If notification to begin frame rendering was delivered to the running isolate.

Definition at line 281 of file runtime_controller.cc.

                                                          {
  MarkAsFrameBorder();
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->BeginFrame(frame_time, frame_number);
    return true;
  }
 
  return false;
}

◆ Clone()

std::unique_ptr< RuntimeController > flutter::RuntimeController::Clone ( ) const

Clone the runtime controller. Launching an isolate with a cloned runtime controller will use the same snapshots and copies all window data to the new instance. This is usually only used in the debug runtime mode to support the cold-restart scenario.

Returns: A clone of the existing runtime controller.

Definition at line 107 of file runtime_controller.cc.

                                                                {
  return std::make_unique<RuntimeController>(client_,                      //
                                             vm_,                          //
                                             isolate_snapshot_,            //
                                             idle_notification_callback_,  //
                                             platform_data_,               //
                                             isolate_create_callback_,     //
                                             isolate_shutdown_callback_,   //
                                             persistent_isolate_data_,     //
                                             context_                      //
  );
}

◆ ComputePlatformResolvedLocale()

std::unique_ptr< std::vector< std::string > > flutter::RuntimeController::ComputePlatformResolvedLocale ( const std::vector< std::string > & supported_locale_data )

overrideprivatevirtual

Directly invokes platform-specific APIs to compute the locale the platform would have natively resolved to.

Parameters

[in] supported_locale_data The vector of strings that represents the locales supported by the app. Each locale consists of three strings: languageCode, countryCode, and scriptCode in that order.

Returns: A vector of 3 strings languageCode, countryCode, and scriptCode that represents the locale selected by the platform. Empty strings mean the value was unassigned. Empty vector represents a null locale.

Implements flutter::PlatformConfigurationClient.

Definition at line 473 of file runtime_controller.cc.

                                                       {
  return client_.ComputePlatformResolvedLocale(supported_locale_data);
}

◆ DefaultRouteName()

std::string flutter::RuntimeController::DefaultRouteName ( )

overrideprivatevirtual

The route or path that the embedder requested when the application was launched.

This will be the string "`/`" if no particular route was requested.

Implements flutter::PlatformConfigurationClient.

Definition at line 389 of file runtime_controller.cc.

                                              {
  return client_.DefaultRouteName();
}

◆ DispatchPlatformMessage()

bool flutter::RuntimeController::DispatchPlatformMessage ( std::unique_ptr< PlatformMessage > message )

virtual

Dispatch the specified platform message to running root isolate.

Parameters

[in] message The message to dispatch to the isolate.

Returns: If the message was dispatched to the running root isolate. This may fail is an isolate is not running.

Definition at line 346 of file runtime_controller.cc.

                                            {
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    TRACE_EVENT0("flutter", "RuntimeController::DispatchPlatformMessage");
    platform_configuration->DispatchPlatformMessage(std::move(message));
    return true;
  }
 
  return false;
}

◆ DispatchPointerDataPacket()

bool flutter::RuntimeController::DispatchPointerDataPacket ( const PointerDataPacket & packet )

Dispatch the specified pointer data message to the running root isolate.

Parameters

[in] packet The pointer data message to dispatch to the isolate.

Returns: If the pointer data message was dispatched. This may fail is an isolate is not running.

Definition at line 357 of file runtime_controller.cc.

                                     {
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    TRACE_EVENT0("flutter", "RuntimeController::DispatchPointerDataPacket");
    platform_configuration->DispatchPointerDataPacket(packet);
    return true;
  }
 
  return false;
}

◆ DispatchSemanticsAction()

bool flutter::RuntimeController::DispatchSemanticsAction	(	int32_t	node_id,
		SemanticsAction	action,
		fml::MallocMapping	args
	)

Dispatch the semantics action to the specified accessibility node.

Parameters

[in]	node_id	The identified of the accessibility node.
[in]	action	The semantics action to perform on the specified accessibility node.
[in]	args	Optional data that applies to the specified action.

Returns: If the semantics action was dispatched. This may fail if an isolate is not running.

Definition at line 368 of file runtime_controller.cc.

                                                                       {
  TRACE_EVENT1("flutter", "RuntimeController::DispatchSemanticsAction", "mode",
               "basic");
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->DispatchSemanticsAction(node_id, action,
                                                    std::move(args));
    return true;
  }
 
  return false;
}

◆ EndWarmUpFrame()

void flutter::RuntimeController::EndWarmUpFrame ( )

overrideprivatevirtual

Called when a warm up frame has ended.

      For more introduction, see `Animator::EndWarmUpFrame`.

Implements flutter::PlatformConfigurationClient.

Definition at line 398 of file runtime_controller.cc.

                                       {
  client_.OnAllViewsRendered();
}

◆ GetAssetManager()

std::shared_ptr< AssetManager > flutter::RuntimeController::GetAssetManager ( )

overrideprivatevirtual

Returns the current collection of assets available on the platform.

Implements flutter::PlatformConfigurationClient.

Definition at line 450 of file runtime_controller.cc.

                                                               {
  return client_.GetAssetManager();
}

◆ GetDartVM()

virtual DartVM * flutter::RuntimeController::GetDartVM ( ) const

inlinevirtual

Definition at line 628 of file runtime_controller.h.

628{ return vm_; }

◆ GetFontCollection()

FontCollection & flutter::RuntimeController::GetFontCollection ( )

overrideprivatevirtual

Returns the current collection of fonts available on the platform.

This function reads an XML file and makes font families and collections of them. MinikinFontForTest is used for FontFamily creation.

Implements flutter::PlatformConfigurationClient.

Definition at line 445 of file runtime_controller.cc.

                                                     {
  return client_.GetFontCollection();
}

◆ GetIOManager()

const fml::WeakPtr< IOManager > & flutter::RuntimeController::GetIOManager ( ) const

inline

Definition at line 624 of file runtime_controller.h.

                                                    {
    return context_.io_manager;
  }

◆ GetIsolateName()

std::string flutter::RuntimeController::GetIsolateName ( )

Gets the debug name of the root isolate. But default, the debug name of the isolate is derived from its advisory script URI, advisory main entrypoint and its main port name. For example, "main.dart$main-1234" where the script URI is "main.dart", the entrypoint is "main" and the port name "1234". Once launched, the isolate may re-christen itself using a name it selects via setIsolateDebugName in window.dart. This name is purely advisory and only used by instrumentation and reporting purposes.

Returns: The debug name of the root isolate.

Definition at line 488 of file runtime_controller.cc.

                                            {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  return root_isolate ? root_isolate->debug_name() : "";
}

◆ GetIsolateSnapshot()

const fml::RefPtr< const DartSnapshot > & flutter::RuntimeController::GetIsolateSnapshot ( ) const

inline

Definition at line 630 of file runtime_controller.h.

                                                                  {
    return isolate_snapshot_;
  }

◆ GetLastError()

tonic::DartErrorHandleType flutter::RuntimeController::GetLastError ( )

Get the last error encountered by the microtask queue.

Returns: The last error encountered by the microtask queue.

Definition at line 502 of file runtime_controller.cc.

                                                         {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  return root_isolate ? root_isolate->GetLastError() : tonic::kNoError;
}

◆ GetMainPort()

Dart_Port flutter::RuntimeController::GetMainPort ( )

Gets the main port identifier of the root isolate.

Returns: The main port identifier. If no root isolate is running, returns ILLEGAL_PORT.

Definition at line 483 of file runtime_controller.cc.

                                         {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  return root_isolate ? root_isolate->main_port() : ILLEGAL_PORT;
}

◆ GetPersistentIsolateData()

std::shared_ptr< const fml::Mapping > flutter::RuntimeController::GetPersistentIsolateData ( )

overridevirtual

The embedder can specify data that the isolate can request synchronously on launch. This accessor fetches that data.

This data is persistent for the duration of the Flutter application and is available even after isolate restarts. Because of this lifecycle, the size of this data must be kept to a minimum.

For asynchronous communication between the embedder and isolate, a platform channel may be used.

Returns: A map of the isolate data that the framework can request upon launch.

Implements flutter::PlatformConfigurationClient.

Definition at line 467 of file runtime_controller.cc.

                                            {
  return persistent_isolate_data_;
}

◆ GetPlatformData()

const PlatformData & flutter::RuntimeController::GetPlatformData ( ) const

inline

Definition at line 634 of file runtime_controller.h.

634{ return platform_data_; }

◆ GetPlatformIsolateManager()

std::shared_ptr< PlatformIsolateManager > flutter::RuntimeController::GetPlatformIsolateManager ( )

inlineoverridevirtual

Implements flutter::PlatformConfigurationClient.

Definition at line 649 of file runtime_controller.h.

                                                                             {
    return platform_isolate_manager_;
  }

◆ GetRootIsolate()

std::weak_ptr< const DartIsolate > flutter::RuntimeController::GetRootIsolate ( ) const

inline

Definition at line 645 of file runtime_controller.h.

                                                        {
    return root_isolate_;
  }

◆ GetRootIsolateGroup()

uint64_t flutter::RuntimeController::GetRootIsolateGroup ( ) const

Get an identifier that represents the Dart isolate group the root isolate is in.

Returns: The root isolate group identifier, zero if one can't be established.

Definition at line 583 of file runtime_controller.cc.

                                                      {
  auto isolate = root_isolate_.lock();
  if (isolate) {
    auto isolate_scope = tonic::DartIsolateScope(isolate->isolate());
    Dart_IsolateGroup isolate_group = Dart_CurrentIsolateGroup();
    return reinterpret_cast<uint64_t>(isolate_group);
  } else {
    return 0;
  }
}

◆ GetRootIsolateReturnCode()

std::optional< uint32_t > flutter::RuntimeController::GetRootIsolateReturnCode ( )

Get the return code specified by the root isolate (if one is present).

Returns: The root isolate return code if the isolate has specified one.

Definition at line 579 of file runtime_controller.cc.

                                                                  {
  return root_isolate_return_code_;
}

◆ GetRootIsolateServiceID()

std::optional< std::string > flutter::RuntimeController::GetRootIsolateServiceID ( ) const

Get the service ID of the root isolate if the root isolate is running.

Returns: The root isolate service id.

Definition at line 572 of file runtime_controller.cc.

                                                                        {
  if (auto isolate = root_isolate_.lock()) {
    return isolate->GetServiceId();
  }
  return std::nullopt;
}

◆ GetScaledFontSize()

double flutter::RuntimeController::GetScaledFontSize	(	double	unscaled_font_size,
		int	configuration_id
	)		const

overrideprivatevirtual

Synchronously invokes platform-specific APIs to apply the system text scaling on the given unscaled font size.

Platforms that support this feature (currently it's only implemented for Android SDK level 34+) will send a valid configuration_id to potential callers, before this method can be called.

Parameters

[in]	unscaled_font_size	The unscaled font size specified by the app developer. The value is in logical pixels, and is guaranteed to be finite and non-negative.
[in]	configuration_id	The unique id of the configuration to use for computing the scaled font size.

Returns: The scaled font size in logical pixels, or -1 if the given configuration_id did not match a valid configuration.

Implements flutter::PlatformConfigurationClient.

Definition at line 627 of file runtime_controller.cc.

                                                                        {
  return client_.GetScaledFontSize(unscaled_font_size, configuration_id);
}

◆ GetSkiaUnrefQueue()

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

inline

Definition at line 636 of file runtime_controller.h.

                                                             {
    return context_.unref_queue;
  }

◆ GetSnapshotDelegate()

const fml::TaskRunnerAffineWeakPtr< SnapshotDelegate > & flutter::RuntimeController::GetSnapshotDelegate ( ) const

inline

Definition at line 640 of file runtime_controller.h.

            {
    return context_.snapshot_delegate;
  }

◆ HandlePlatformMessage()

void flutter::RuntimeController::HandlePlatformMessage ( std::unique_ptr< PlatformMessage > message )

overrideprivatevirtual

When the Flutter application has a message to send to the underlying platform, the message needs to be forwarded to the platform on the appropriate thread (via the platform task runner). The PlatformConfiguration delegates this task to the engine via this method.

See also: PlatformView::HandlePlatformMessage

Parameters

[in] message The message from the Flutter application to send to the underlying platform.

Implements flutter::PlatformConfigurationClient.

Definition at line 439 of file runtime_controller.cc.

                                            {
  client_.HandlePlatformMessage(std::move(message));
}

◆ HasLivePorts()

bool flutter::RuntimeController::HasLivePorts ( )

Returns if the root isolate has any live receive ports.

Returns: True if there are live receive ports, False otherwise. Return False if the root isolate is not running as well.

Definition at line 493 of file runtime_controller.cc.

                                     {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  if (!root_isolate) {
    return false;
  }
  tonic::DartState::Scope scope(root_isolate);
  return Dart_HasLivePorts();
}

◆ IsRootIsolateRunning()

bool flutter::RuntimeController::IsRootIsolateRunning ( )

virtual

Returns if the root isolate is running. The isolate must be transitioned to the running phase manually. The isolate can stop running if it terminates execution on its own.

Returns: True if root isolate running, False otherwise.

Definition at line 99 of file runtime_controller.cc.

                                             {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  if (root_isolate) {
    return root_isolate->GetPhase() == DartIsolate::Phase::Running;
  }
  return false;
}

◆ LaunchRootIsolate()

bool flutter::RuntimeController::LaunchRootIsolate	(	const Settings &	settings,
		const fml::closure &	root_isolate_create_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
	)

Launches the isolate using the window data associated with this runtime controller. Before this call, the Dart isolate has not been initialized. On successful return, the caller can assume that the isolate is in the DartIsolate::Phase::Running phase.

This call will fail if a root isolate is already running. To re-create an isolate with the window data associated with this runtime controller, Clone this runtime controller and Launch an isolate in that runtime controller instead.

Parameters

[in]	settings	The per engine instance settings.
[in]	root_isolate_create_callback	A callback invoked before the root isolate has launched the Dart program, but after it has been created. This is called without isolate scope, and after any root isolate callback in the settings.
[in]	dart_entrypoint	The dart entrypoint. If `std::nullopt` or empty, `main` will be attempted.
[in]	dart_entrypoint_library	The dart entrypoint library. If `std::nullopt` or empty, the core library will be attempted.
[in]	dart_entrypoint_args	Arguments passed as a List<String> to Dart's entrypoint function.
[in]	isolate_configuration	The isolate configuration

Returns: If the isolate could be launched and guided to the DartIsolate::Phase::Running phase.

Definition at line 507 of file runtime_controller.cc.

                                                               {
  if (root_isolate_.lock()) {
    FML_LOG(ERROR) << "Root isolate was already running.";
    return false;
  }
 
  auto strong_root_isolate =
      DartIsolate::CreateRunningRootIsolate(
          settings,                                       //
          isolate_snapshot_,                              //
          std::make_unique<PlatformConfiguration>(this),  //
          DartIsolate::Flags{},                           //
          root_isolate_create_callback,                   //
          isolate_create_callback_,                       //
          isolate_shutdown_callback_,                     //
          std::move(dart_entrypoint),                     //
          std::move(dart_entrypoint_library),             //
          dart_entrypoint_args,                           //
          std::move(isolate_configuration),               //
          context_,                                       //
          spawning_isolate_.lock().get())                 //
          .lock();
 
  if (!strong_root_isolate) {
    FML_LOG(ERROR) << "Could not create root isolate.";
    return false;
  }
 
  // Enable platform channels for background isolates.
  strong_root_isolate->GetIsolateGroupData().SetPlatformMessageHandler(
      strong_root_isolate->GetRootIsolateToken(),
      client_.GetPlatformMessageHandler());
 
  // The root isolate ivar is weak.
  root_isolate_ = strong_root_isolate;
 
  // Capture by `this` here is safe because the callback is made by the dart
  // state itself. The isolate (and its Dart state) is owned by this object and
  // it will be collected before this object.
  strong_root_isolate->SetReturnCodeCallback(
      [this](uint32_t code) { root_isolate_return_code_ = code; });
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    tonic::DartState::Scope scope(strong_root_isolate);
    platform_configuration->DidCreateIsolate();
    if (!FlushRuntimeStateToIsolate()) {
      FML_DLOG(ERROR) << "Could not set up initial isolate state.";
    }
  } else {
    FML_DCHECK(false) << "RuntimeController created without window binding.";
  }
 
  FML_DCHECK(Dart_CurrentIsolate() == nullptr);
 
  client_.OnRootIsolateCreated();
 
  return true;
}

◆ LoadDartDeferredLibrary()

void flutter::RuntimeController::LoadDartDeferredLibrary	(	intptr_t	loading_unit_id,
		std::unique_ptr< const fml::Mapping >	snapshot_data,
		std::unique_ptr< const fml::Mapping >	snapshot_instructions
	)

Loads the Dart shared library into the Dart VM. When the Dart library is loaded successfully, the Dart future returned by the originating loadLibrary() call completes.

The Dart compiler may generate separate shared libraries files called 'loading units' when libraries are imported as deferred. Each of these shared libraries are identified by a unique loading unit id. Callers should open and resolve a SymbolMapping from the shared library. The Mappings should be moved into this method, as ownership will be assumed by the dart root isolate after successful loading and released after shutdown of the root isolate. The loading unit may not be used after isolate shutdown. If loading fails, the mappings will be released.

This method is paired with a RequestDartDeferredLibrary invocation that provides the embedder with the loading unit id of the deferred library to load.

Parameters

[in]	loading_unit_id	The unique id of the deferred library's loading unit, as passed in by RequestDartDeferredLibrary.
[in]	snapshot_data	Dart snapshot data of the loading unit's shared library.
[in]	snapshot_data	Dart snapshot instructions of the loading unit's shared library.

Definition at line 594 of file runtime_controller.cc.

                                                           {
  root_isolate_.lock()->LoadLoadingUnit(loading_unit_id,
                                        std::move(snapshot_data),
                                        std::move(snapshot_instructions));
}

◆ LoadDartDeferredLibraryError()

void flutter::RuntimeController::LoadDartDeferredLibraryError	(	intptr_t	loading_unit_id,
		const std::string	error_message,
		bool	transient
	)

virtual

Indicates to the dart VM that the request to load a deferred library with the specified loading unit id has failed.

The dart future returned by the initiating loadLibrary() call will complete with an error.

Parameters

[in]	loading_unit_id	The unique id of the deferred library's loading unit, as passed in by RequestDartDeferredLibrary.
[in]	error_message	The error message that will appear in the dart Future.
[in]	transient	A transient error is a failure due to temporary conditions such as no network. Transient errors allow the dart VM to re-request the same deferred library and loading_unit_id again. Non-transient errors are permanent and attempts to re-request the library will instantly complete with an error.

Definition at line 603 of file runtime_controller.cc.

                    {
  root_isolate_.lock()->LoadLoadingUnitError(loading_unit_id, error_message,
                                             transient);
}

◆ NotifyDestroyed()

bool flutter::RuntimeController::NotifyDestroyed ( )

virtual

Notify the Dart VM that the attached flutter view has been destroyed. This gives the Dart VM to perform some cleanup activities e.g: perform garbage collection to free up any unused memory.

NotifyDestroyed is advisory. The VM may or may not perform any clean up activities.

Definition at line 333 of file runtime_controller.cc.

                                        {
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  if (!root_isolate) {
    return false;
  }
 
  tonic::DartState::Scope scope(root_isolate);
 
  Dart_NotifyDestroyed();
 
  return true;
}

◆ NotifyIdle()

bool flutter::RuntimeController::NotifyIdle ( fml::TimeDelta deadline )

virtual

Notify the Dart VM that no frame workloads are expected on the UI task runner till the specified deadline. The VM uses this opportunity to perform garbage collection operations is a manner that interferes as little as possible with frame rendering.

NotifyIdle is advisory. The VM may or may not run a garbage collection when this is called, and will eventually perform garbage collections even if it is not called or it is called with insufficient deadlines.

The garbage collection mechanism and its thresholds are internal implementation details and absolutely no guarantees are made about the threshold discussed below. This discussion is also an oversimplification but hopefully serves to calibrate expectations about GC behavior:

When the Dart VM and its root isolate are initialized, the memory consumed upto that point are treated as a baseline.
A fixed percentage of the memory consumed (~20%) over the baseline is treated as the hard threshold.
The memory in play is divided into old space and new space. The new space is typically very small and fills up rapidly.
The baseline plus the threshold is considered the old space while the small new space is a separate region (typically a few pages).
The total old space size minus the max new space size is treated as the soft threshold.
In a world where there is no call to NotifyIdle, when the total allocation exceeds the soft threshold, a concurrent mark is initiated in the VM. There is a “small” pause that occurs when the concurrent mark is initiated and another pause when the mark concludes and a sweep is initiated.
If the total allocations exceeds the hard threshold, a “big” stop-the-world pause is initiated.
If after either the sweep after the concurrent mark, or, the stop-the-world pause, the consumption returns to be below the soft threshold, the dance begins anew.
If after both the “small” and “big” pauses, memory usage is still over the hard threshold, i.e, the objects are still reachable, that amount of memory is treated as the new baseline and a fixed percentage of the new baseline over the new baseline is now the new hard threshold.
Updating the baseline will continue till memory for the updated old space can be allocated from the operating system. These allocations will typically fail due to address space exhaustion on 32-bit systems and page table exhaustion on 64-bit systems.
NotifyIdle initiates the concurrent mark preemptively. The deadline is used by the VM to determine if the corresponding sweep can be performed within the deadline. This way, jank due to “small” pauses can be ameliorated.
There is no ability to stop a “big” pause on reaching the hard threshold in the old space. The best you can do is release (by making them unreachable) objects eagerly so that the are marked as unreachable in the concurrent mark initiated by either reaching the soft threshold or an explicit NotifyIdle.
If you are running out of memory, its because too many large objects were allocation and remained reachable such that the old space kept growing till it could grow no more.
At the edges of allocation thresholds, failures can occur gracefully if the instigating allocation was made in the Dart VM or rather gracelessly if the allocation is made by some native component.

See also: Dart_TimelineGetMicros

Bug:: The deadline argument must be converted to std::chrono instead of a raw integer.

Parameters

[in] deadline The deadline is used by the VM to determine if the corresponding sweep can be performed within the deadline.

Returns: If the idle notification was forwarded to the running isolate.

Definition at line 301 of file runtime_controller.cc.

                                                        {
  if (deadline - fml::TimeDelta::FromMicroseconds(Dart_TimelineGetMicros()) <
      fml::TimeDelta::FromMilliseconds(1)) {
    // There's less than 1ms left before the deadline. Upstream callers do not
    // check to see if the deadline is in the past, and work after this point
    // will be in vain.
    return false;
  }
 
  std::shared_ptr<DartIsolate> root_isolate = root_isolate_.lock();
  if (!root_isolate) {
    return false;
  }
 
  tonic::DartState::Scope scope(root_isolate);
 
  Dart_PerformanceMode performance_mode =
      PlatformConfigurationNativeApi::GetDartPerformanceMode();
  if (performance_mode == Dart_PerformanceMode::Dart_PerformanceMode_Latency) {
    return false;
  }
 
  Dart_NotifyIdle(deadline.ToMicroseconds());
 
  // Idle notifications being in isolate scope are part of the contract.
  if (idle_notification_callback_) {
    TRACE_EVENT0("flutter", "EmbedderIdleNotification");
    idle_notification_callback_(deadline.ToMicroseconds());
  }
  return true;
}

◆ RemoveView()

bool flutter::RuntimeController::RemoveView ( int64_t view_id )

Notify the isolate that a view is no longer available.

        Views that are added before the isolate is started are
        queued until the isolate is launched. If one of these
        "pending" views are removed, the view add is cancelled:
        the `AddViewCallback` will be invoked with an `added` of
        false and `RemoveView` will return false.

        The implicit view (kFlutterImplicitViewId) should never be
        removed. Doing so triggers an assertion.

Parameters

[in] view_id The ID of the view.

Returns: If the remove view operation was forwarded to the running isolate. False if the view does not exist. If the Dart isolate is not running, then the pending view creation (if any) is cancelled and the return value is always false.

Definition at line 189 of file runtime_controller.cc.

                                                  {
  platform_data_.viewport_metrics_for_views.erase(view_id);
 
  // If the Dart isolate has not been launched yet, the pending
  // add view operation's callback is stored by the runtime controller.
  // Notify this callback of the cancellation.
  auto* platform_configuration = GetPlatformConfigurationIfAvailable();
  if (!platform_configuration) {
    FML_DCHECK(has_flushed_runtime_state_ == false);
    if (pending_add_view_callbacks_.find(view_id) !=
        pending_add_view_callbacks_.end()) {
      pending_add_view_callbacks_[view_id](false);
      pending_add_view_callbacks_.erase(view_id);
    }
 
    return false;
  }
 
  return platform_configuration->RemoveView(view_id);
}

◆ Render()

void flutter::RuntimeController::Render	(	int64_t	view_id,
		Scene *	scene,
		double	width,
		double	height
	)

overrideprivatevirtual

Updates the client's rendering on the GPU with the newly provided Scene.

Implements flutter::PlatformConfigurationClient.

Definition at line 403 of file runtime_controller.cc.

                                              {
  const ViewportMetrics* view_metrics =
      UIDartState::Current()->platform_configuration()->GetMetrics(view_id);
  if (view_metrics == nullptr) {
    return;
  }
  client_.Render(view_id, scene->takeLayerTree(width, height),
                 view_metrics->device_pixel_ratio);
  rendered_views_during_frame_.insert(view_id);
  CheckIfAllViewsRendered();
}

◆ ReportTimings()

bool flutter::RuntimeController::ReportTimings ( std::vector< int64_t > timings )

Dart code cannot fully measure the time it takes for a specific frame to be rendered. This is because Dart code only runs on the UI task runner. That is only a small part of the overall frame workload. The raster task runner frame workload is executed on a thread where Dart code cannot run (and hence instrument). Besides, due to the pipelined nature of rendering in Flutter, there may be multiple frame workloads being processed at any given time. However, for non-Timeline based profiling, it is useful for trace collection and processing to happen in Dart. To do this, the raster task runner frame workloads need to be instrumented separately. After a set number of these profiles have been gathered, they need to be reported back to Dart code. The engine reports this extra instrumentation information back to Dart code running on the engine by invoking this method at predefined intervals.

See also: Engine::ReportTimings, FrameTiming

Parameters

[in] timings Collection of FrameTiming::kCount * n timestamps for n frames whose timings have not been reported yet. A collection of integers is reported here for easier conversions to Dart objects. The timestamps are measured against the system monotonic clock measured in microseconds.

Definition at line 292 of file runtime_controller.cc.

                                                                {
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->ReportTimings(std::move(timings));
    return true;
  }
 
  return false;
}

◆ RequestDartDeferredLibrary()

void flutter::RuntimeController::RequestDartDeferredLibrary ( intptr_t loading_unit_id )

overridevirtual

Invoked when the Dart VM requests that a deferred library be loaded. Notifies the engine that the deferred library identified by the specified loading unit id should be downloaded and loaded into the Dart VM via LoadDartDeferredLibrary

Upon encountering errors or otherwise failing to load a loading unit with the specified id, the failure should be directly reported to dart by calling LoadDartDeferredLibraryFailure to ensure the waiting dart future completes with an error.

Parameters

[in] loading_unit_id The unique id of the deferred library's loading unit. This id is to be passed back into LoadDartDeferredLibrary in order to identify which deferred library to load.

Implements flutter::PlatformConfigurationClient.

Definition at line 612 of file runtime_controller.cc.

                                                                           {
  return client_.RequestDartDeferredLibrary(loading_unit_id);
}

◆ ScheduleFrame()

void flutter::RuntimeController::ScheduleFrame ( )

overrideprivatevirtual

Requests that, at the next appropriate opportunity, a new frame be scheduled for rendering.

Implements flutter::PlatformConfigurationClient.

Definition at line 394 of file runtime_controller.cc.

                                      {
  client_.ScheduleFrame();
}

◆ SendChannelUpdate()

void flutter::RuntimeController::SendChannelUpdate	(	std::string	name,
		bool	listening
	)

overrideprivatevirtual

Invoked when a listener is registered on a platform channel.

Parameters

[in]	name	The name of the platform channel to which a listener has been registered or cleared.
[in]	listening	Whether the listener has been set (true) or cleared (false).

Implements flutter::PlatformConfigurationClient.

Definition at line 479 of file runtime_controller.cc.

                                                                        {
  client_.SendChannelUpdate(std::move(name), listening);
}

◆ SetAccessibilityFeatures()

bool flutter::RuntimeController::SetAccessibilityFeatures ( int32_t flags )

Forward the preference of accessibility features that must be enabled in the semantics tree to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

Parameters

[in] flags The accessibility features that must be generated in the semantics tree.

Returns: If the preference of accessibility features was forwarded to the running isolate.

Definition at line 270 of file runtime_controller.cc.

                                                              {
  platform_data_.accessibility_feature_flags_ = flags;
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateAccessibilityFeatures(
        platform_data_.accessibility_feature_flags_);
    return true;
  }
 
  return false;
}

◆ SetDisplays()

bool flutter::RuntimeController::SetDisplays ( const std::vector< DisplayData > & displays )

Forward the specified display metrics to the running isolate. If the isolate is not running, these metrics will be saved and flushed to the isolate when it starts.

Parameters

[in] displays The available displays.

Definition at line 616 of file runtime_controller.cc.

                                                                          {
  TRACE_EVENT0("flutter", "SetDisplays");
  platform_data_.displays = displays;
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateDisplays(displays);
    return true;
  }
  return false;
}

◆ SetInitialLifecycleState()

bool flutter::RuntimeController::SetInitialLifecycleState ( const std::string & data )

Forward the initial lifecycle state data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running. After the isolate starts running, the current lifecycle state is pushed to it via the "flutter/lifecycle" channel.

Deprecated:: The persistent isolate data must be used for this purpose instead.

Parameters

[in] data The lifecycle state data.

Returns: If the lifecycle state data was forwarded to the running isolate.

Definition at line 246 of file runtime_controller.cc.

                                                                      {
  platform_data_.lifecycle_state = data;
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateInitialLifecycleState(
        platform_data_.lifecycle_state);
    return true;
  }
 
  return false;
}

◆ SetLocales()

bool flutter::RuntimeController::SetLocales ( const std::vector< std::string > & locale_data )

Forward the specified locale data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

Deprecated:: The persistent isolate data must be used for this purpose instead.

Parameters

[in] locale_data The locale data. This should consist of groups of 4 strings, each group representing a single locale.

Returns: If the locale data was forwarded to the running isolate.

Definition at line 222 of file runtime_controller.cc.

                                             {
  platform_data_.locale_data = locale_data;
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateLocales(locale_data);
    return true;
  }
 
  return false;
}

◆ SetNeedsReportTimings()

void flutter::RuntimeController::SetNeedsReportTimings ( bool value )

overrideprivatevirtual

Notifies this client that the application has an opinion about whether its frame timings need to be reported backed to it. Due to the asynchronous nature of rendering in Flutter, it is not possible for the application to determine the total time it took to render a specific frame. While the layer-tree is constructed on the UI thread, it needs to be rendering on the raster thread. Dart code cannot execute on this thread. So any instrumentation about the frame times gathered on this thread needs to be aggregated and sent back to the UI thread for processing in Dart.

When the application indicates that frame times need to be reported, it collects this information till a specified number of data points are gathered. Then this information is sent back to Dart code via Engine::ReportTimings.

This option is engine counterpart of the Window._setNeedsReportTimings in window.dart.

Parameters

[in] needs_reporting If reporting information should be collected and send back to Dart.

Implements flutter::PlatformConfigurationClient.

Definition at line 461 of file runtime_controller.cc.

                                                        {
  client_.SetNeedsReportTimings(value);
}

◆ SetSemanticsEnabled()

bool flutter::RuntimeController::SetSemanticsEnabled ( bool enabled )

Notifies the running isolate about whether the semantics tree should be generated or not. If the isolate is not running, this preference will be saved and flushed to the isolate when it starts running.

Parameters

[in] enabled Indicates whether to generate the semantics tree.

Returns: If the semantics tree generation preference was forwarded to the running isolate.

Definition at line 258 of file runtime_controller.cc.

                                                        {
  platform_data_.semantics_enabled = enabled;
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateSemanticsEnabled(
        platform_data_.semantics_enabled);
    return true;
  }
 
  return false;
}

◆ SetUserSettingsData()

bool flutter::RuntimeController::SetUserSettingsData ( const std::string & data )

Forward the user settings data to the running isolate. If the isolate is not running, this data will be saved and flushed to the isolate when it starts running.

Deprecated:: The persistent isolate data must be used for this purpose instead.

Parameters

[in] data The user settings data.

Returns: If the user settings data was forwarded to the running isolate.

Definition at line 234 of file runtime_controller.cc.

                                                                 {
  platform_data_.user_settings_data = data;
 
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    platform_configuration->UpdateUserSettingsData(
        platform_data_.user_settings_data);
    return true;
  }
 
  return false;
}

◆ SetViewportMetrics()

bool flutter::RuntimeController::SetViewportMetrics	(	int64_t	view_id,
		const ViewportMetrics &	metrics
	)

Forward the specified viewport metrics to the running isolate. If the isolate is not running, these metrics will be saved and flushed to the isolate when it starts.

Parameters

[in]	view_id	The ID for the view that `metrics` describes.
[in]	metrics	The window's viewport metrics.

Returns: If the window metrics were forwarded to the running isolate.

Definition at line 210 of file runtime_controller.cc.

                                                                           {
  TRACE_EVENT0("flutter", "SetViewportMetrics");
 
  platform_data_.viewport_metrics_for_views[view_id] = metrics;
  if (auto* platform_configuration = GetPlatformConfigurationIfAvailable()) {
    return platform_configuration->UpdateViewMetrics(view_id, metrics);
  }
 
  return false;
}

◆ ShutdownPlatformIsolates()

void flutter::RuntimeController::ShutdownPlatformIsolates ( )

Shuts down all registered platform isolates. Must be called from the platform thread.

Definition at line 632 of file runtime_controller.cc.

                                                 {
  platform_isolate_manager_->ShutdownPlatformIsolates();
}

◆ Spawn()

std::unique_ptr< RuntimeController > flutter::RuntimeController::Spawn	(	RuntimeDelegate &	p_client,
		const std::string &	advisory_script_uri,
		const std::string &	advisory_script_entrypoint,
		const std::function< void(int64_t)> &	idle_notification_callback,
		const fml::closure &	isolate_create_callback,
		const fml::closure &	isolate_shutdown_callback,
		const std::shared_ptr< const fml::Mapping > &	persistent_isolate_data,
		fml::WeakPtr< IOManager >	io_manager,
		fml::WeakPtr< ImageDecoder >	image_decoder,
		fml::WeakPtr< ImageGeneratorRegistry >	image_generator_registry,
		fml::TaskRunnerAffineWeakPtr< SnapshotDelegate >	snapshot_delegate
	)		const

Create a RuntimeController that shares as many resources as possible with the calling RuntimeController such that together they occupy less memory.

Returns: A RuntimeController with a running isolate.

See also: RuntimeController::RuntimeController

Definition at line 48 of file runtime_controller.cc.

                                                                          {
  UIDartState::Context spawned_context{context_.task_runners,
                                       std::move(snapshot_delegate),
                                       std::move(io_manager),
                                       context_.unref_queue,
                                       std::move(image_decoder),
                                       std::move(image_generator_registry),
                                       advisory_script_uri,
                                       advisory_script_entrypoint,
                                       context_.volatile_path_tracker,
                                       context_.concurrent_task_runner,
                                       context_.enable_impeller,
                                       context_.runtime_stage_backend};
  auto result =
      std::make_unique<RuntimeController>(p_client,                      //
                                          vm_,                           //
                                          isolate_snapshot_,             //
                                          p_idle_notification_callback,  //
                                          platform_data_,                //
                                          p_isolate_create_callback,     //
                                          p_isolate_shutdown_callback,   //
                                          p_persistent_isolate_data,     //
                                          spawned_context);              //
  result->spawning_isolate_ = root_isolate_;
  return result;
}

◆ UpdateIsolateDescription()

void flutter::RuntimeController::UpdateIsolateDescription	(	const std::string	isolate_name,
		int64_t	isolate_port
	)

overrideprivatevirtual

Notifies this client of the name of the root isolate and its port when that isolate is launched, restarted (in the cold-restart scenario) or the application itself updates the name of the root isolate (via Window.setIsolateDebugName in window.dart). The name of the isolate is meaningless to the engine but is used in instrumentation and tooling. Currently, this information is to update the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation.

Parameters

[in]	isolate_name	The isolate name
[in]	isolate_port	The isolate port

Implements flutter::PlatformConfigurationClient.

Definition at line 455 of file runtime_controller.cc.

                                                                       {
  client_.UpdateIsolateDescription(isolate_name, isolate_port);
}

◆ UpdateSemantics()

void flutter::RuntimeController::UpdateSemantics ( SemanticsUpdate * update )

overrideprivatevirtual

Receives an updated semantics tree from the Framework.

Parameters

[in] update The updated semantic tree to apply.

Implements flutter::PlatformConfigurationClient.

Definition at line 432 of file runtime_controller.cc.

                                                               {
  if (platform_data_.semantics_enabled) {
    client_.UpdateSemantics(update->takeNodes(), update->takeActions());
  }
}

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

runtime/runtime_controller.h
runtime/runtime_controller.cc

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ AddViewCallback

Constructor & Destructor Documentation

◆ RuntimeController() [1/2]

◆ ~RuntimeController()

◆ RuntimeController() [2/2]

Member Function Documentation

◆ AddView()

◆ BeginFrame()

◆ Clone()

◆ ComputePlatformResolvedLocale()

◆ DefaultRouteName()

◆ DispatchPlatformMessage()

◆ DispatchPointerDataPacket()

◆ DispatchSemanticsAction()

◆ EndWarmUpFrame()

◆ GetAssetManager()

◆ GetDartVM()

◆ GetFontCollection()

◆ GetIOManager()

◆ GetIsolateName()

◆ GetIsolateSnapshot()

◆ GetLastError()

◆ GetMainPort()

◆ GetPersistentIsolateData()

◆ GetPlatformData()

◆ GetPlatformIsolateManager()

◆ GetRootIsolate()

◆ GetRootIsolateGroup()

◆ GetRootIsolateReturnCode()

◆ GetRootIsolateServiceID()

◆ GetScaledFontSize()

◆ GetSkiaUnrefQueue()

◆ GetSnapshotDelegate()

◆ HandlePlatformMessage()

◆ HasLivePorts()

◆ IsRootIsolateRunning()

◆ LaunchRootIsolate()

◆ LoadDartDeferredLibrary()

◆ LoadDartDeferredLibraryError()

◆ NotifyDestroyed()

◆ NotifyIdle()

◆ RemoveView()

◆ Render()

◆ ReportTimings()

◆ RequestDartDeferredLibrary()

◆ ScheduleFrame()

◆ SendChannelUpdate()

◆ SetAccessibilityFeatures()

◆ SetDisplays()

◆ SetInitialLifecycleState()

◆ SetLocales()

◆ SetNeedsReportTimings()

◆ SetSemanticsEnabled()

◆ SetUserSettingsData()

◆ SetViewportMetrics()

◆ ShutdownPlatformIsolates()

◆ Spawn()

◆ UpdateIsolateDescription()

◆ UpdateSemantics()