flutter::Shell Class Reference

#include <shell.h>

Inheritance diagram for flutter::Shell:

Public Types
template<class T >
using	CreateCallback = std::function< std::unique_ptr< T >(Shell &)>
typedef std::function< std::unique_ptr< Engine >(Engine::Delegate &delegate, const PointerDataDispatcherMaker &dispatcher_maker, DartVM &vm, fml::RefPtr< const DartSnapshot > isolate_snapshot, TaskRunners task_runners, const PlatformData &platform_data, Settings settings, std::unique_ptr< Animator > animator, fml::WeakPtr< IOManager > io_manager, fml::RefPtr< SkiaUnrefQueue > unref_queue, fml::TaskRunnerAffineWeakPtr< SnapshotDelegate > snapshot_delegate, std::shared_ptr< VolatilePathTracker > volatile_path_tracker, const std::shared_ptr< fml::SyncSwitch > &gpu_disabled_switch, impeller::RuntimeStageBackend runtime_stage_type)>	EngineCreateCallback
Public Types inherited from flutter::PlatformView::Delegate
using	AddViewCallback = PlatformView::AddViewCallback
using	RemoveViewCallback = PlatformView::RemoveViewCallback
using	KeyDataResponse = std::function< void(bool)>
Public Types inherited from flutter::ServiceProtocol::Handler
using	ServiceProtocolMap = std::map< std::string_view, std::string_view >

Public Member Functions
	~Shell ()
	Destroys the shell. This is a synchronous operation and synchronous barrier blocks are introduced on the various threads to ensure shutdown of all shell sub-components before this method returns. More...
std::unique_ptr< Shell >	Spawn (RunConfiguration run_configuration, const std::string &initial_route, const CreateCallback< PlatformView > &on_create_platform_view, const CreateCallback< Rasterizer > &on_create_rasterizer) const
	Creates one Shell from another Shell where the created Shell takes the opportunity to share any internal components it can. This results is a Shell that has a smaller startup time cost and a smaller memory footprint than an Shell created with the Create function. More...
void	RunEngine (RunConfiguration run_configuration)
	Starts an isolate for the given RunConfiguration. More...
void	RunEngine (RunConfiguration run_configuration, const std::function< void(Engine::RunStatus)> &result_callback)
	Starts an isolate for the given RunConfiguration. The result_callback will be called with the status of the operation. More...
const Settings &	GetSettings () const override
const TaskRunners &	GetTaskRunners () const override
	If callers wish to interact directly with any shell subcomponents, they must (on the platform thread) obtain a task runner that the component is designed to run on and a weak pointer to that component. They may then post a task to that task runner, do the validity check on that task runner before performing any operation on that component. This accessor allows callers to access the task runners for this shell. More...
const fml::RefPtr< fml::RasterThreadMerger >	GetParentRasterThreadMerger () const override
	Getting the raster thread merger from parent shell, it can be a null RefPtr when it's a root Shell or the embedder_->SupportsDynamicThreadMerging() returns false. More...
fml::TaskRunnerAffineWeakPtr< Rasterizer >	GetRasterizer () const
	Rasterizers may only be accessed on the raster task runner. More...
fml::WeakPtr< Engine >	GetEngine ()
	Engines may only be accessed on the UI thread. This method is deprecated, and implementers should instead use other API available on the Shell or the PlatformView. More...
fml::WeakPtr< PlatformView >	GetPlatformView ()
	Platform views may only be accessed on the platform task runner. More...
fml::WeakPtr< ShellIOManager >	GetIOManager ()
	The IO Manager may only be accessed on the IO task runner. More...
void	NotifyLowMemoryWarning () const
	Used by embedders to notify that there is a low memory warning. The shell will attempt to purge caches. Current, only the rasterizer cache is purged. More...
bool	IsSetup () const
	Used by embedders to check if all shell subcomponents are initialized. It is the embedder's responsibility to make this call before accessing any other shell method. A shell that is not set up must be discarded and another one created with updated settings. More...
Rasterizer::Screenshot	Screenshot (Rasterizer::ScreenshotType type, bool base64_encode)
	Captures a screenshot and optionally Base64 encodes the data of the last layer tree rendered by the rasterizer in this shell. More...
fml::Status	WaitForFirstFrame (fml::TimeDelta timeout)
	Pauses the calling thread until the first frame is presented. More...
bool	ReloadSystemFonts ()
	Used by embedders to reload the system fonts in FontCollection. It also clears the cached font families and send system channel message to framework to rebuild affected widgets. More...
std::optional< DartErrorCode >	GetUIIsolateLastError () const
	Used by embedders to get the last error from the Dart UI Isolate, if one exists. More...
bool	EngineHasLivePorts () const
	Used by embedders to check if the Engine is running and has any live ports remaining. For example, the Flutter tester uses this method to check whether it should continue to wait for a running test or not. More...
std::shared_ptr< const fml::SyncSwitch >	GetIsGpuDisabledSyncSwitch () const override
	Accessor for the disable GPU SyncSwitch. More...
void	SetGpuAvailability (GpuAvailability availability)
	Marks the GPU as available or unavailable. More...
DartVM *	GetDartVM ()
	Get a pointer to the Dart VM used by this running shell instance. More...
void	OnDisplayUpdates (std::vector< std::unique_ptr< Display > > displays)
	Notifies the display manager of the updates. More...
double	GetMainDisplayRefreshRate ()
	Queries the DisplayManager for the main display refresh rate. More...
void	RegisterImageDecoder (ImageGeneratorFactory factory, int32_t priority)
	Install a new factory that can match against and decode image data. More...
const std::shared_ptr< PlatformMessageHandler > &	GetPlatformMessageHandler () const override
	Returns the delegate object that handles PlatformMessage's from Flutter to the host platform (and its responses). More...
const std::weak_ptr< VsyncWaiter >	GetVsyncWaiter () const
const std::shared_ptr< fml::ConcurrentTaskRunner >	GetConcurrentWorkerTaskRunner () const
Public Member Functions inherited from flutter::PlatformView::Delegate
virtual void	OnPlatformViewCreated (std::unique_ptr< Surface > surface)=0
	Notifies the delegate that the platform view was created with the given render surface. This surface is platform (iOS, Android) and client-rendering API (OpenGL, Software, Metal, Vulkan) specific. This is usually a sign to the rasterizer to set up and begin rendering to that surface. More...
virtual void	OnPlatformViewDestroyed ()=0
	Notifies the delegate that the platform view was destroyed. This is usually a sign to the rasterizer to suspend rendering a previously configured surface and collect any intermediate resources. More...
virtual void	OnPlatformViewScheduleFrame ()=0
	Notifies the delegate that the platform needs to schedule a frame to regenerate the layer tree and redraw the surface. More...
virtual void	OnPlatformViewAddView (int64_t view_id, const ViewportMetrics &viewport_metrics, AddViewCallback callback)=0
	Allocate resources for a new non-implicit view and inform Dart about the view, and on success, schedules a new frame. More...
virtual void	OnPlatformViewRemoveView (int64_t view_id, RemoveViewCallback callback)=0
	Deallocate resources for a removed view and inform Dart about the removal. More...
virtual void	OnPlatformViewSetNextFrameCallback (const fml::closure &closure)=0
	Notifies the delegate that the specified callback needs to be invoked after the rasterizer is done rendering the next frame. This callback will be called on the render thread and it is caller responsibility to perform any re-threading as necessary. Due to the asynchronous nature of rendering in Flutter, embedders usually add a placeholder over the contents in which Flutter is going to render when Flutter is first initialized. This callback may be used as a signal to remove that placeholder. More...
virtual void	OnPlatformViewSetViewportMetrics (int64_t view_id, const ViewportMetrics &metrics)=0
	Notifies the delegate the viewport metrics of a view have been updated. The rasterizer will need to be reconfigured to render the frame in the updated viewport metrics. More...
virtual void	OnPlatformViewDispatchPlatformMessage (std::unique_ptr< PlatformMessage > message)=0
	Notifies the delegate that the platform has dispatched a platform message from the embedder to the Flutter application. This message must be forwarded to the running isolate hosted by the engine on the UI thread. More...
virtual void	OnPlatformViewDispatchPointerDataPacket (std::unique_ptr< PointerDataPacket > packet)=0
	Notifies the delegate that the platform view has encountered a pointer event. This pointer event needs to be forwarded to the running root isolate hosted by the engine on the UI thread. More...
virtual void	OnPlatformViewDispatchSemanticsAction (int32_t node_id, SemanticsAction action, fml::MallocMapping args)=0
	Notifies the delegate that the platform view has encountered an accessibility related action on the specified node. This event must be forwarded to the running root isolate hosted by the engine on the UI thread. More...
virtual void	OnPlatformViewSetSemanticsEnabled (bool enabled)=0
	Notifies the delegate that the embedder has expressed an opinion about whether the accessibility tree needs to be enabled or disabled. This information needs to be forwarded to the root isolate running on the UI thread. More...
virtual void	OnPlatformViewSetAccessibilityFeatures (int32_t flags)=0
	Notifies the delegate that the embedder has expressed an opinion about the features to enable in the accessibility tree. More...
virtual void	OnPlatformViewRegisterTexture (std::shared_ptr< Texture > texture)=0
	Notifies the delegate that the embedder has specified a texture that it want the rasterizer to composite within the Flutter layer tree. All textures must have a unique identifier. When the rasterizer encounters an external texture within its hierarchy, it gives the embedder a chance to update that texture on the raster thread before it composites the same on-screen. More...
virtual void	OnPlatformViewUnregisterTexture (int64_t texture_id)=0
	Notifies the delegate that the embedder will no longer attempt to composite the specified texture within the layer tree. This allows the rasterizer to collect associated resources. More...
virtual void	OnPlatformViewMarkTextureFrameAvailable (int64_t texture_id)=0
	Notifies the delegate that the embedder has updated the contents of the texture with the specified identifier. Typically, Flutter will only render a frame if there is an updated layer tree. However, in cases where the layer tree is static but one of the externally composited textures has been updated by the embedder, the embedder needs to notify the rasterizer to render a new frame. In such cases, the existing layer tree may be reused with the frame composited with all updated external textures. More...
virtual void	LoadDartDeferredLibrary (intptr_t loading_unit_id, std::unique_ptr< const fml::Mapping > snapshot_data, std::unique_ptr< const fml::Mapping > snapshot_instructions)=0
	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. More...
virtual void	LoadDartDeferredLibraryError (intptr_t loading_unit_id, const std::string error_message, bool transient)=0
	Indicates to the dart VM that the request to load a deferred library with the specified loading unit id has failed. More...
virtual void	UpdateAssetResolverByType (std::unique_ptr< AssetResolver > updated_asset_resolver, AssetResolver::AssetResolverType type)=0
	Replaces the asset resolver handled by the engine's AssetManager of the specified type with updated_asset_resolver. The matching AssetResolver is removed and replaced with updated_asset_resolvers. More...
virtual const Settings &	OnPlatformViewGetSettings () const =0
	Called by the platform view on the platform thread to get the settings object associated with the platform view instance. More...
virtual void	OnAnimatorBeginFrame (fml::TimePoint frame_target_time, uint64_t frame_number)=0
virtual void	OnAnimatorNotifyIdle (fml::TimeDelta deadline)=0
virtual void	OnAnimatorUpdateLatestFrameTargetTime (fml::TimePoint frame_target_time)=0
virtual void	OnAnimatorDraw (std::shared_ptr< FramePipeline > pipeline)=0
virtual void	OnAnimatorDrawLastLayerTrees (std::unique_ptr< FrameTimingsRecorder > frame_timings_recorder)=0
virtual void	OnEngineUpdateSemantics (SemanticsNodeUpdates updates, CustomAccessibilityActionUpdates actions)=0
	When the accessibility tree has been updated by the Flutter application, this new information needs to be conveyed to the underlying platform. The engine delegates this task to the shell via this call. The engine cannot access the underlying platform directly because of threading considerations. Most platform specific APIs to convey accessibility information are only safe to access on the platform task runner while the engine is running on the UI task runner. More...
virtual void	OnEngineHandlePlatformMessage (std::unique_ptr< PlatformMessage > message)=0
	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 engine delegates this task to the shell via this method. More...
virtual void	OnPreEngineRestart ()=0
	Notifies the delegate that the root isolate of the application is about to be discarded and a new isolate with the same runtime started in its place. This should only happen in the Flutter "debug" runtime mode in the cold-restart scenario. The embedder may need to reset native resource in response to the restart. More...
virtual void	OnRootIsolateCreated ()=0
	Notifies the shell that the root isolate is created. Currently, this information is to add to 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. More...
virtual void	UpdateIsolateDescription (const std::string isolate_name, int64_t isolate_port)=0
	Notifies the shell 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 PlatformDispatcher.setIsolateDebugName in platform_dispatcher.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. More...
virtual void	SetNeedsReportTimings (bool needs_reporting)=0
	Notifies the shell 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. More...
virtual std::unique_ptr< std::vector< std::string > >	ComputePlatformResolvedLocale (const std::vector< std::string > &supported_locale_data)=0
	Directly invokes platform-specific APIs to compute the locale the platform would have natively resolved to. More...
virtual void	RequestDartDeferredLibrary (intptr_t loading_unit_id)=0
	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 More...
virtual fml::TimePoint	GetCurrentTimePoint ()=0
	Returns the current fml::TimePoint. This method is primarily provided to allow tests to control Any methods that rely on advancing the clock. More...
virtual const std::shared_ptr< PlatformMessageHandler > &	GetPlatformMessageHandler () const =0
	Returns the delegate object that handles PlatformMessage's from Flutter to the host platform (and its responses). More...
virtual void	OnEngineChannelUpdate (std::string name, bool listening)=0
	Invoked when a listener is registered on a platform channel. More...
virtual double	GetScaledFontSize (double unscaled_font_size, int configuration_id) const =0
	Synchronously invokes platform-specific APIs to apply the system text scaling on the given unscaled font size. More...
virtual void	OnFrameRasterized (const FrameTiming &frame_timing)=0
	Notifies the delegate that a frame has been rendered. The rasterizer collects profiling information for each part of the frame workload. This profiling information is made available to the delegate for forwarding to subsystems interested in collecting such profiles. Currently, the shell (the delegate) forwards this to the engine where Dart code can react to this information. More...
virtual fml::Milliseconds	GetFrameBudget ()=0
virtual fml::TimePoint	GetLatestFrameTargetTime () const =0
virtual const TaskRunners &	GetTaskRunners () const =0
	Task runners used by the shell. More...
virtual const fml::RefPtr< fml::RasterThreadMerger >	GetParentRasterThreadMerger () const =0
	The raster thread merger from parent shell's rasterizer. More...
virtual std::shared_ptr< const fml::SyncSwitch >	GetIsGpuDisabledSyncSwitch () const =0
virtual const Settings &	GetSettings () const =0
virtual bool	ShouldDiscardLayerTree (int64_t view_id, const flutter::LayerTree &tree)=0
virtual fml::RefPtr< fml::TaskRunner >	GetServiceProtocolHandlerTaskRunner (std::string_view method) const =0
virtual Description	GetServiceProtocolDescription () const =0
virtual bool	HandleServiceProtocolMessage (std::string_view method, const ServiceProtocolMap &params, rapidjson::Document *response)=0
virtual size_t	GetResourceCacheLimit ()=0

Static Public Member Functions
static std::unique_ptr< Shell >	Create (const PlatformData &platform_data, const TaskRunners &task_runners, Settings settings, const CreateCallback< PlatformView > &on_create_platform_view, const CreateCallback< Rasterizer > &on_create_rasterizer, bool is_gpu_disabled=false)
	Creates a shell instance using the provided settings. The callbacks to create the various shell subcomponents will be called on the appropriate threads before this method returns. If this is the first instance of a shell in the process, this call also bootstraps the Dart VM. More...
static std::pair< DartVMRef, fml::RefPtr< const DartSnapshot > >	InferVmInitDataFromSettings (Settings &settings)

Friends
class	testing::ShellTest

Additional Inherited Members
Protected Member Functions inherited from flutter::ResourceCacheLimitItem
virtual	~ResourceCacheLimitItem ()=default

Detailed Description

Perhaps the single most important class in the Flutter engine repository. When embedders create a Flutter application, they are referring to the creation of an instance of a shell. Creation and destruction of the shell is synchronous and the embedder only holds a unique pointer to the shell. The shell does not create the threads its primary components run on. Instead, it is the embedder's responsibility to create threads and give the shell task runners for those threads. Due to deterministic destruction of the shell, the embedder can terminate all threads immediately after collecting the shell. The shell must be created and destroyed on the same thread, but, different shells (i.e. a separate instances of a Flutter application) may be run on different threads simultaneously. The task runners themselves do not have to be unique. If all task runner references given to the shell during shell creation point to the same task runner, the Flutter application is effectively single threaded.

The shell is the central nervous system of the Flutter application. None of the shell components are thread safe and must be created, accessed and destroyed on the same thread. To interact with one another, the various components delegate to the shell for communication. Instead of using back pointers to the shell, a delegation pattern is used by all components that want to communicate with one another. Because of this, the shell implements the delegate interface for all these components.

All shell methods accessed by the embedder may only be called on the platform task runner. In case the embedder wants to directly access a shell subcomponent, it is the embedder's responsibility to acquire a weak pointer to that component and post a task to the task runner used by the component to access its methods. The shell must also be destroyed on the platform task runner.

There is no explicit API to bootstrap and shutdown the Dart VM. The first instance of the shell in the process bootstraps the Dart VM and the destruction of the last shell instance destroys the same. Since different shells may be created and destroyed on different threads. VM bootstrap may happen on one thread but its collection on another. This behavior is thread safe.

Definition at line 112 of file shell.h.

Member Typedef Documentation

CreateCallback

template<class T >

using flutter::Shell::CreateCallback = std::function<std::unique_ptr<T>(Shell&)>

Definition at line 120 of file shell.h.

EngineCreateCallback

typedef std::function<std::unique_ptr<Engine>( Engine::Delegate& delegate, const PointerDataDispatcherMaker& dispatcher_maker, DartVM& vm, fml::RefPtr<const DartSnapshot> isolate_snapshot, TaskRunners task_runners, const PlatformData& platform_data, Settings settings, std::unique_ptr<Animator> animator, fml::WeakPtr<IOManager> io_manager, fml::RefPtr<SkiaUnrefQueue> unref_queue, fml::TaskRunnerAffineWeakPtr<SnapshotDelegate> snapshot_delegate, std::shared_ptr<VolatilePathTracker> volatile_path_tracker, const std::shared_ptr<fml::SyncSwitch>& gpu_disabled_switch, impeller::RuntimeStageBackend runtime_stage_type)> flutter::Shell::EngineCreateCallback

Definition at line 136 of file shell.h.

Constructor & Destructor Documentation

~Shell()

flutter::Shell::~Shell

(

)

Destroys the shell. This is a synchronous operation and synchronous barrier blocks are introduced on the various threads to ensure shutdown of all shell sub-components before this method returns.

Definition at line 529 of file shell.cc.

              {
#if !SLIMPELLER
  PersistentCache::GetCacheForProcess()->RemoveWorkerTaskRunner(
      task_runners_.GetIOTaskRunner());
#endif  //  !SLIMPELLER
 
  vm_->GetServiceProtocol()->RemoveHandler(this);
 
  fml::AutoResetWaitableEvent platiso_latch, ui_latch, gpu_latch,
      platform_latch, io_latch;
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetPlatformTaskRunner(),
      fml::MakeCopyable([this, &platiso_latch]() mutable {
        engine_->ShutdownPlatformIsolates();
        platiso_latch.Signal();
      }));
  platiso_latch.Wait();
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetUITaskRunner(),
      fml::MakeCopyable([this, &ui_latch]() mutable {
        engine_.reset();
        ui_latch.Signal();
      }));
  ui_latch.Wait();
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetRasterTaskRunner(),
      fml::MakeCopyable(
          [this, rasterizer = std::move(rasterizer_), &gpu_latch]() mutable {
            rasterizer.reset();
            this->weak_factory_gpu_.reset();
            gpu_latch.Signal();
          }));
  gpu_latch.Wait();
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetIOTaskRunner(),
      fml::MakeCopyable([io_manager = std::move(io_manager_),
                         platform_view = platform_view_.get(),
                         &io_latch]() mutable {
        io_manager.reset();
        if (platform_view) {
          platform_view->ReleaseResourceContext();
        }
        io_latch.Signal();
      }));
 
  io_latch.Wait();
 
  // The platform view must go last because it may be holding onto platform side
  // counterparts to resources owned by subsystems running on other threads. For
  // example, the NSOpenGLContext on the Mac.
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetPlatformTaskRunner(),
      fml::MakeCopyable([platform_view = std::move(platform_view_),
                         &platform_latch]() mutable {
        platform_view.reset();
        platform_latch.Signal();
      }));
  platform_latch.Wait();
}

Member Function Documentation

Create()

std::unique_ptr< Shell > flutter::Shell::Create ( const PlatformData &  platform_data, const TaskRunners &  task_runners, Settings  settings, const CreateCallback< PlatformView > &  on_create_platform_view, const CreateCallback< Rasterizer > &  on_create_rasterizer, bool  is_gpu_disabled = false  )

static

Creates a shell instance using the provided settings. The callbacks to create the various shell subcomponents will be called on the appropriate threads before this method returns. If this is the first instance of a shell in the process, this call also bootstraps the Dart VM.

Note

The root isolate which will run this Shell's Dart code takes its instructions from the passed in settings. This allows embedders to host multiple Shells with different Dart code.

Parameters

[in]	task_runners	The task runners
[in]	settings	The settings
[in]	on_create_platform_view	The callback that must return a platform view. This will be called on the platform task runner before this method returns.
[in]	on_create_rasterizer	That callback that must provide a valid rasterizer. This will be called on the render task runner before this method returns.
[in]	is_gpu_disabled	The default value for the switch that turns off the GPU.

Returns

A full initialized shell if the settings and callbacks are valid. The root isolate has been created but not yet launched. It may be launched by obtaining the engine weak pointer and posting a task onto the UI task runner with a valid run configuration to run the isolate. The embedder must always check the validity of the shell (using the IsSetup call) immediately after getting a pointer to it.

Definition at line 169 of file shell.cc.

                          {
  // This must come first as it initializes tracing.
  PerformInitializationTasks(settings);
 
  TRACE_EVENT0("flutter", "Shell::Create");
 
  auto [vm, isolate_snapshot] = InferVmInitDataFromSettings(settings);
  auto resource_cache_limit_calculator =
      std::make_shared<ResourceCacheLimitCalculator>(
          settings.resource_cache_max_bytes_threshold);
 
  return CreateWithSnapshot(platform_data,                     //
                            task_runners,                      //
                            /*parent_thread_merger=*/nullptr,  //
                            /*parent_io_manager=*/nullptr,     //
                            resource_cache_limit_calculator,   //
                            settings,                          //
                            std::move(vm),                     //
                            std::move(isolate_snapshot),       //
                            on_create_platform_view,           //
                            on_create_rasterizer,              //
                            CreateEngine, is_gpu_disabled);
}

EngineHasLivePorts()

bool flutter::Shell::EngineHasLivePorts

(

)

const

Used by embedders to check if the Engine is running and has any live ports remaining. For example, the Flutter tester uses this method to check whether it should continue to wait for a running test or not.

Returns

Returns if the shell has an engine and the engine has any live Dart ports.

Definition at line 717 of file shell.cc.

                                     {
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetUITaskRunner()->RunsTasksOnCurrentThread());
 
  if (!weak_engine_) {
    return false;
  }
 
  return weak_engine_->UIIsolateHasLivePorts();
}

GetConcurrentWorkerTaskRunner()

const std::shared_ptr< fml::ConcurrentTaskRunner > flutter::Shell::GetConcurrentWorkerTaskRunner

(

)

const

Definition at line 2334 of file shell.cc.

                                           {
  FML_DCHECK(vm_);
  if (!vm_) {
    return nullptr;
  }
  return vm_->GetConcurrentWorkerTaskRunner();
}

GetDartVM()

DartVM * flutter::Shell::GetDartVM

(

)

Get a pointer to the Dart VM used by this running shell instance.

Returns

The Dart VM pointer.

Definition at line 834 of file shell.cc.

                         {
  return &vm_;
}

GetEngine()

fml::WeakPtr< Engine > flutter::Shell::GetEngine

(

)

Engines may only be accessed on the UI thread. This method is deprecated, and implementers should instead use other API available on the Shell or the PlatformView.

Returns

A weak pointer to the engine.

Definition at line 819 of file shell.cc.

                                    {
  FML_DCHECK(is_set_up_);
  return weak_engine_;
}

GetIOManager()

fml::WeakPtr< ShellIOManager > flutter::Shell::GetIOManager

(

)

The IO Manager may only be accessed on the IO task runner.

Returns

A weak pointer to the IO manager.

Definition at line 829 of file shell.cc.

                                               {
  FML_DCHECK(is_set_up_);
  return io_manager_->GetWeakPtr();
}

GetIsGpuDisabledSyncSwitch()

std::shared_ptr< const fml::SyncSwitch > flutter::Shell::GetIsGpuDisabledSyncSwitch ( ) const

overridevirtual

Accessor for the disable GPU SyncSwitch.

Implements flutter::Rasterizer::Delegate.

Definition at line 2267 of file shell.cc.

          {
  return is_gpu_disabled_sync_switch_;
}

GetMainDisplayRefreshRate()

double flutter::Shell::GetMainDisplayRefreshRate

(

)

Queries the DisplayManager for the main display refresh rate.

Definition at line 1871 of file shell.cc.

                                        {
  return display_manager_->GetMainDisplayRefreshRate();
}

GetParentRasterThreadMerger()

const fml::RefPtr< fml::RasterThreadMerger > flutter::Shell::GetParentRasterThreadMerger ( ) const

overridevirtual

Getting the raster thread merger from parent shell, it can be a null RefPtr when it's a root Shell or the embedder_->SupportsDynamicThreadMerging() returns false.

Returns

The raster thread merger used by the parent shell.

Implements flutter::Rasterizer::Delegate.

Definition at line 809 of file shell.cc.

          {
  return parent_raster_thread_merger_;
}

GetPlatformMessageHandler()

const std::shared_ptr< PlatformMessageHandler > & flutter::Shell::GetPlatformMessageHandler ( ) const

overridevirtual

Returns the delegate object that handles PlatformMessage's from Flutter to the host platform (and its responses).

Implements flutter::Engine::Delegate.

Definition at line 2322 of file shell.cc.

                                       {
  return platform_message_handler_;
}

GetPlatformView()

fml::WeakPtr< PlatformView > flutter::Shell::GetPlatformView

(

)

Platform views may only be accessed on the platform task runner.

Returns

A weak pointer to the platform view.

Definition at line 824 of file shell.cc.

                                                {
  FML_DCHECK(is_set_up_);
  return weak_platform_view_;
}

GetRasterizer()

fml::TaskRunnerAffineWeakPtr< Rasterizer > flutter::Shell::GetRasterizer

(

)

const

Rasterizers may only be accessed on the raster task runner.

Returns

A weak pointer to the rasterizer.

Definition at line 814 of file shell.cc.

                                                                  {
  FML_DCHECK(is_set_up_);
  return weak_rasterizer_;
}

GetSettings()

const Settings & flutter::Shell::GetSettings ( ) const

overridevirtual

Returns

The settings used to launch this shell.

Implements flutter::Rasterizer::Delegate.

Definition at line 801 of file shell.cc.

                                         {
  return settings_;
}

GetTaskRunners()

const TaskRunners & flutter::Shell::GetTaskRunners ( ) const

overridevirtual

If callers wish to interact directly with any shell subcomponents, they must (on the platform thread) obtain a task runner that the component is designed to run on and a weak pointer to that component. They may then post a task to that task runner, do the validity check on that task runner before performing any operation on that component. This accessor allows callers to access the task runners for this shell.

Returns

The task runners current in use by the shell.

Implements flutter::Rasterizer::Delegate.

Definition at line 805 of file shell.cc.

                                               {
  return task_runners_;
}

GetUIIsolateLastError()

std::optional< DartErrorCode > flutter::Shell::GetUIIsolateLastError

(

)

const

Used by embedders to get the last error from the Dart UI Isolate, if one exists.

Returns

Returns the last error code from the UI Isolate.

Definition at line 697 of file shell.cc.

                                                              {
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetUITaskRunner()->RunsTasksOnCurrentThread());
 
  if (!weak_engine_) {
    return std::nullopt;
  }
  switch (weak_engine_->GetUIIsolateLastError()) {
    case tonic::kCompilationErrorType:
      return DartErrorCode::CompilationError;
    case tonic::kApiErrorType:
      return DartErrorCode::ApiError;
    case tonic::kUnknownErrorType:
      return DartErrorCode::UnknownError;
    case tonic::kNoError:
      return DartErrorCode::NoError;
  }
  return DartErrorCode::UnknownError;
}

GetVsyncWaiter()

const std::weak_ptr< VsyncWaiter > flutter::Shell::GetVsyncWaiter

(

)

const

Definition at line 2326 of file shell.cc.

                                                           {
  if (!engine_) {
    return {};
  }
  return engine_->GetVsyncWaiter();
}

InferVmInitDataFromSettings()

std::pair< DartVMRef, fml::RefPtr< const DartSnapshot > > flutter::Shell::InferVmInitDataFromSettings ( Settings &  settings )

static

Definition at line 153 of file shell.cc.

                                                     {
  // Always use the `vm_snapshot` and `isolate_snapshot` provided by the
  // settings to launch the VM.  If the VM is already running, the snapshot
  // arguments are ignored.
  auto vm_snapshot = DartSnapshot::VMSnapshotFromSettings(settings);
  auto isolate_snapshot = DartSnapshot::IsolateSnapshotFromSettings(settings);
  auto vm = DartVMRef::Create(settings, vm_snapshot, isolate_snapshot);
 
  // If the settings did not specify an `isolate_snapshot`, fall back to the
  // one the VM was launched with.
  if (!isolate_snapshot) {
    isolate_snapshot = vm->GetVMData()->GetIsolateSnapshot();
  }
  return {std::move(vm), isolate_snapshot};
}

IsSetup()

bool flutter::Shell::IsSetup

(

)

const

Used by embedders to check if all shell subcomponents are initialized. It is the embedder's responsibility to make this call before accessing any other shell method. A shell that is not set up must be discarded and another one created with updated settings.

Returns

Returns if the shell has been set up. Once set up, this does not change for the life-cycle of the shell.

Definition at line 728 of file shell.cc.

                          {
  return is_set_up_;
}

NotifyLowMemoryWarning()

void flutter::Shell::NotifyLowMemoryWarning

(

)

const

Used by embedders to notify that there is a low memory warning. The shell will attempt to purge caches. Current, only the rasterizer cache is purged.

Definition at line 637 of file shell.cc.

                                         {
  auto trace_id = fml::tracing::TraceNonce();
  TRACE_EVENT_ASYNC_BEGIN0("flutter", "Shell::NotifyLowMemoryWarning",
                           trace_id);
  // This does not require a current isolate but does require a running VM.
  // Since a valid shell will not be returned to the embedder without a valid
  // DartVMRef, we can be certain that this is a safe spot to assume a VM is
  // running.
  ::Dart_NotifyLowMemory();
 
  task_runners_.GetRasterTaskRunner()->PostTask(
      [rasterizer = rasterizer_->GetWeakPtr(), trace_id = trace_id]() {
        if (rasterizer) {
          rasterizer->NotifyLowMemoryWarning();
        }
        TRACE_EVENT_ASYNC_END0("flutter", "Shell::NotifyLowMemoryWarning",
                               trace_id);
      });
  // The IO Manager uses resource cache limits of 0, so it is not necessary
  // to purge them.
}

OnDisplayUpdates()

void flutter::Shell::OnDisplayUpdates

(

std::vector< std::unique_ptr< Display > >

displays

)

Notifies the display manager of the updates.

Definition at line 2297 of file shell.cc.

                                                                       {
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
 
  std::vector<DisplayData> display_data;
  display_data.reserve(displays.size());
  for (const auto& display : displays) {
    display_data.push_back(display->GetDisplayData());
  }
  task_runners_.GetUITaskRunner()->PostTask(
      [engine = engine_->GetWeakPtr(),
       display_data = std::move(display_data)]() {
        if (engine) {
          engine->SetDisplays(display_data);
        }
      });
 
  display_manager_->HandleDisplayUpdates(std::move(displays));
}

RegisterImageDecoder()

void flutter::Shell::RegisterImageDecoder	(	ImageGeneratorFactory	factory,
		int32_t	priority
	)

Install a new factory that can match against and decode image data.

Parameters

[in]	factory	Callback that produces ImageGenerators for compatible input data.
[in]	priority	The priority used to determine the order in which factories are tried. Higher values mean higher priority. The built-in Skia decoders are installed at priority 0, and so a priority > 0 takes precedent over the builtin decoders. When multiple decoders are added with the same priority, those which are added earlier take precedent.

See also

CreateCompatibleGenerator

Definition at line 1875 of file shell.cc.

                                                   {
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
  FML_DCHECK(is_set_up_);
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetUITaskRunner(),
      [engine = engine_->GetWeakPtr(), factory = std::move(factory),
       priority]() {
        if (engine) {
          engine->GetImageGeneratorRegistry()->AddFactory(factory, priority);
        }
      });
}

ReloadSystemFonts()

bool flutter::Shell::ReloadSystemFonts

(

)

Used by embedders to reload the system fonts in FontCollection. It also clears the cached font families and send system channel message to framework to rebuild affected widgets.

Returns

Returns if shell reloads system fonts successfully.

Definition at line 2252 of file shell.cc.

                              {
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
 
  if (!engine_) {
    return false;
  }
  engine_->SetupDefaultFontManager();
  engine_->GetFontCollection().GetFontCollection()->ClearFontFamilyCache();
  // After system fonts are reloaded, we send a system channel message
  // to notify flutter framework.
  SendFontChangeNotification();
  return true;
}

RunEngine() [1/2]

void flutter::Shell::RunEngine

(

RunConfiguration

run_configuration

)

Starts an isolate for the given RunConfiguration.

Definition at line 659 of file shell.cc.

                                                        {
  RunEngine(std::move(run_configuration), nullptr);
}

RunEngine() [2/2]

void flutter::Shell::RunEngine	(	RunConfiguration	run_configuration,
		const std::function< void(Engine::RunStatus)> &	result_callback
	)

Starts an isolate for the given RunConfiguration. The result_callback will be called with the status of the operation.

Definition at line 663 of file shell.cc.

                                                               {
  auto result = [platform_runner = task_runners_.GetPlatformTaskRunner(),
                 result_callback](Engine::RunStatus run_result) {
    if (!result_callback) {
      return;
    }
    platform_runner->PostTask(
        [result_callback, run_result]() { result_callback(run_result); });
  };
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
 
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetUITaskRunner(),
      fml::MakeCopyable(
          [run_configuration = std::move(run_configuration),
           weak_engine = weak_engine_, result]() mutable {
            if (!weak_engine) {
              FML_LOG(ERROR)
                  << "Could not launch engine with configuration - no engine.";
              result(Engine::RunStatus::Failure);
              return;
            }
            auto run_result = weak_engine->Run(std::move(run_configuration));
            if (run_result == flutter::Engine::RunStatus::Failure) {
              FML_LOG(ERROR) << "Could not launch engine with configuration.";
            }
 
            result(run_result);
          }));
}

Screenshot()

Rasterizer::Screenshot flutter::Shell::Screenshot	(	Rasterizer::ScreenshotType	type,
		bool	base64_encode
	)

Captures a screenshot and optionally Base64 encodes the data of the last layer tree rendered by the rasterizer in this shell.

Parameters

[in]	type	The type of screenshot to capture.
[in]	base64_encode	If the screenshot data should be base64 encoded.

Returns

The screenshot result.

Definition at line 2189 of file shell.cc.

                        {
  if (settings_.enable_impeller) {
    switch (screenshot_type) {
      case Rasterizer::ScreenshotType::SkiaPicture:
        FML_LOG(ERROR)
            << "Impeller backend cannot produce ScreenshotType::SkiaPicture.";
        return {};
      case Rasterizer::ScreenshotType::UncompressedImage:
      case Rasterizer::ScreenshotType::CompressedImage:
      case Rasterizer::ScreenshotType::SurfaceData:
        break;
    }
  }
  TRACE_EVENT0("flutter", "Shell::Screenshot");
  fml::AutoResetWaitableEvent latch;
  Rasterizer::Screenshot screenshot;
  fml::TaskRunner::RunNowOrPostTask(
      task_runners_.GetRasterTaskRunner(), [&latch,                        //
                                            rasterizer = GetRasterizer(),  //
                                            &screenshot,                   //
                                            screenshot_type,               //
                                            base64_encode                  //
  ]() {
        if (rasterizer) {
          screenshot = rasterizer->ScreenshotLastLayerTree(screenshot_type,
                                                           base64_encode);
        }
        latch.Signal();
      });
  latch.Wait();
  return screenshot;
}

SetGpuAvailability()

void flutter::Shell::SetGpuAvailability

(

GpuAvailability

availability

)

Marks the GPU as available or unavailable.

Definition at line 2272 of file shell.cc.

                                                           {
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
  switch (availability) {
    case GpuAvailability::kAvailable:
      is_gpu_disabled_sync_switch_->SetSwitch(false);
      return;
    case GpuAvailability::kFlushAndMakeUnavailable: {
      fml::AutoResetWaitableEvent latch;
      fml::TaskRunner::RunNowOrPostTask(
          task_runners_.GetIOTaskRunner(),
          [io_manager = io_manager_.get(), &latch]() {
            io_manager->GetSkiaUnrefQueue()->Drain();
            latch.Signal();
          });
      latch.Wait();
    }
      // FALLTHROUGH
    case GpuAvailability::kUnavailable:
      is_gpu_disabled_sync_switch_->SetSwitch(true);
      return;
    default:
      FML_DCHECK(false);
  }
}

Spawn()

std::unique_ptr< Shell > flutter::Shell::Spawn	(	RunConfiguration	run_configuration,
		const std::string &	initial_route,
		const CreateCallback< PlatformView > &	on_create_platform_view,
		const CreateCallback< Rasterizer > &	on_create_rasterizer
	)		const

Creates one Shell from another Shell where the created Shell takes the opportunity to share any internal components it can. This results is a Shell that has a smaller startup time cost and a smaller memory footprint than an Shell created with the Create function.

The new Shell is returned in a running state so RunEngine shouldn't be called again on the Shell. Once running, the second Shell is mostly independent from the original Shell and the original Shell doesn't need to keep running for the spawned Shell to keep functioning.

Parameters

[in]

run_configuration

A RunConfiguration used to run the Isolate associated with this new Shell. It doesn't have to be the same configuration as the current Shell but it needs to be in the same snapshot or AOT.

See also

http://flutter.dev/go/multiple-engines

Definition at line 593 of file shell.cc.

                                                                  {
  FML_DCHECK(task_runners_.IsValid());
  // It's safe to store this value since it is set on the platform thread.
  bool is_gpu_disabled = false;
  GetIsGpuDisabledSyncSwitch()->Execute(
      fml::SyncSwitch::Handlers()
          .SetIfFalse([&is_gpu_disabled] { is_gpu_disabled = false; })
          .SetIfTrue([&is_gpu_disabled] { is_gpu_disabled = true; }));
  std::unique_ptr<Shell> result = CreateWithSnapshot(
      PlatformData{}, task_runners_, rasterizer_->GetRasterThreadMerger(),
      io_manager_, resource_cache_limit_calculator_, GetSettings(), vm_,
      vm_->GetVMData()->GetIsolateSnapshot(), on_create_platform_view,
      on_create_rasterizer,
      [engine = this->engine_.get(), initial_route](
          Engine::Delegate& delegate,
          const PointerDataDispatcherMaker& dispatcher_maker, DartVM& vm,
          const fml::RefPtr<const DartSnapshot>& isolate_snapshot,
          const TaskRunners& task_runners, const PlatformData& platform_data,
          const Settings& settings, std::unique_ptr<Animator> animator,
          const fml::WeakPtr<IOManager>& io_manager,
          const fml::RefPtr<SkiaUnrefQueue>& unref_queue,
          fml::TaskRunnerAffineWeakPtr<SnapshotDelegate> snapshot_delegate,
          const std::shared_ptr<VolatilePathTracker>& volatile_path_tracker,
          const std::shared_ptr<fml::SyncSwitch>& is_gpu_disabled_sync_switch,
          impeller::RuntimeStageBackend runtime_stage_backend) {
        return engine->Spawn(
            /*delegate=*/delegate,
            /*dispatcher_maker=*/dispatcher_maker,
            /*settings=*/settings,
            /*animator=*/std::move(animator),
            /*initial_route=*/initial_route,
            /*io_manager=*/io_manager,
            /*snapshot_delegate=*/std::move(snapshot_delegate),
            /*gpu_disabled_switch=*/is_gpu_disabled_sync_switch);
      },
      is_gpu_disabled);
  result->RunEngine(std::move(run_configuration));
  return result;
}

WaitForFirstFrame()

fml::Status flutter::Shell::WaitForFirstFrame

(

fml::TimeDelta

timeout

)

Pauses the calling thread until the first frame is presented.

Parameters

[in]

timeout

The duration to wait before timing out. If this duration would cause an overflow when added to std::chrono::steady_clock::now(), this method will wait indefinitely for the first frame.

Returns

'kOk' when the first frame has been presented before the timeout successfully, 'kFailedPrecondition' if called from the GPU or UI thread, 'kDeadlineExceeded' if there is a timeout.

Definition at line 2224 of file shell.cc.

                                                       {
  FML_DCHECK(is_set_up_);
  if (task_runners_.GetUITaskRunner()->RunsTasksOnCurrentThread() ||
      task_runners_.GetRasterTaskRunner()->RunsTasksOnCurrentThread()) {
    return fml::Status(fml::StatusCode::kFailedPrecondition,
                       "WaitForFirstFrame called from thread that can't wait "
                       "because it is responsible for generating the frame.");
  }
 
  // Check for overflow.
  auto now = std::chrono::steady_clock::now();
  auto max_duration = std::chrono::steady_clock::time_point::max() - now;
  auto desired_duration = std::chrono::milliseconds(timeout.ToMilliseconds());
  auto duration =
      now + (desired_duration > max_duration ? max_duration : desired_duration);
 
  std::unique_lock<std::mutex> lock(waiting_for_first_frame_mutex_);
  bool success = waiting_for_first_frame_condition_.wait_until(
      lock, duration, [&waiting_for_first_frame = waiting_for_first_frame_] {
        return !waiting_for_first_frame.load();
      });
  if (success) {
    return fml::Status();
  } else {
    return fml::Status(fml::StatusCode::kDeadlineExceeded, "timeout");
  }
}

Friends And Related Function Documentation

testing::ShellTest

friend class testing::ShellTest

friend

Definition at line 792 of file shell.h.

---

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

• shell/common/shell.h
• shell/common/shell.cc