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, const std::shared_ptr< fml::SyncSwitch > &gpu_disabled_switch, const std::shared_future< impeller::RuntimeStageBackend > &runtime_stage_backend)>	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.
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.
void	RunEngine (RunConfiguration run_configuration)
	Starts an isolate for the given RunConfiguration.
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.
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.
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.
fml::TaskRunnerAffineWeakPtr< Rasterizer >	GetRasterizer () const
	Rasterizers may only be accessed on the raster task runner.
fml::TaskRunnerAffineWeakPtr< 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.
fml::WeakPtr< PlatformView >	GetPlatformView ()
	Platform views may only be accessed on the platform task runner.
fml::WeakPtr< ShellIOManager >	GetIOManager ()
	The IO Manager may only be accessed on the IO task runner.
std::shared_ptr< fml::BasicTaskRunner >	GetShutdownSafeIOTaskRunner ()
	The IO thread can be used for background tasks, including tasks that perform graphics operations using the resource context. But the IO thread will lose the resource context during shutdown of the Shell. Tasks that require the IO manager or the resource context must not run after that phase of shutdown.
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.
void	FlushMicrotaskQueue () const
	Used by embedders to flush the microtask queue. Required when running with merged platform and UI threads, in which case the embedder is responsible for flushing the microtask queue.
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.
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.
fml::Status	WaitForFirstFrame (fml::TimeDelta timeout)
	Pauses the calling thread until the first frame is presented.
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.
std::optional< DartErrorCode >	GetUIIsolateLastError () const
	Used by embedders to get the last error from the Dart UI Isolate, if one exists.
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.
bool	EngineHasPendingMicrotasks () const
	Used by embedders to check if the Engine is running and has any microtasks that have been queued but have not yet run. The Flutter tester uses this as a signal that a test is still running.
std::shared_ptr< const fml::SyncSwitch >	GetIsGpuDisabledSyncSwitch () const override
	Accessor for the disable GPU SyncSwitch.
void	SetGpuAvailability (GpuAvailability availability)
	Marks the GPU as available or unavailable.
DartVM *	GetDartVM ()
	Get a pointer to the Dart VM used by this running shell instance.
void	OnDisplayUpdates (std::vector< std::unique_ptr< Display > > displays)
	Notifies the display manager of the updates.
double	GetMainDisplayRefreshRate ()
	Queries the DisplayManager for the main display refresh rate.
void	RegisterImageDecoder (ImageGeneratorFactory factory, int32_t priority)
	Install a new factory that can match against and decode image data.
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).
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	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.

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.
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 113 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 121 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, const std::shared_ptr<fml::SyncSwitch>& gpu_disabled_switch, const std::shared_future<impeller::RuntimeStageBackend>& runtime_stage_backend)> flutter::Shell::EngineCreateCallback

Definition at line 137 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 606 of file shell.cc.

      {task_runners_.GetIOTaskRunner(),
       std::bind(&Shell::OnServiceProtocolGetPipelineUsage, this,
                 std::placeholders::_1, std::placeholders::_2)};
}
 
Shell::~Shell() {
#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 {
        std::weak_ptr<ShellIOManager> weak_io_manager(io_manager);
        io_manager.reset();
 
        // If the IO manager is not being used by any other spawned shells,
        // then detach the resource context from the IO thread.
        if (platform_view && weak_io_manager.expired()) {
          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();
 
  if (settings_.merged_platform_ui_thread ==
      Settings::MergedPlatformUIThread::kMergeAfterLaunch) {
    // Move the UI task runner back to its original thread to enable shutdown of
    // that thread.

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 223 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);
}

References InferVmInitDataFromSettings(), flutter::Settings::resource_cache_max_bytes_threshold, and TRACE_EVENT0.

Referenced by flutter::AndroidShellHolder::AndroidShellHolder(), flutter::EmbedderEngine::LaunchShell(), flutter::RunTester(), flutter::StartupAndShutdownShell(), flutter::testing::TEST_F(), and flutter::testing::TEST_F().

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 827 of file shell.cc.

                               :
      return DartErrorCode::UnknownError;
    case tonic::kNoError:
      return DartErrorCode::NoError;
  }
  return DartErrorCode::UnknownError;
}
 
bool Shell::EngineHasLivePorts() const {

Referenced by flutter::ScriptCompletionTaskObserver::DidProcessTask().

EngineHasPendingMicrotasks()

bool flutter::Shell::EngineHasPendingMicrotasks

(

)

const

Used by embedders to check if the Engine is running and has any microtasks that have been queued but have not yet run. The Flutter tester uses this as a signal that a test is still running.

Returns

Returns if the shell has an engine and the engine has pending microtasks.

Definition at line 838 of file shell.cc.

                     {
    return false;
  }
 
  return weak_engine_->UIIsolateHasLivePorts();
}
 
bool Shell::EngineHasPendingMicrotasks() const {

Referenced by flutter::ScriptCompletionTaskObserver::DidProcessTask().

FlushMicrotaskQueue()

void flutter::Shell::FlushMicrotaskQueue

(

)

const

Used by embedders to flush the microtask queue. Required when running with merged platform and UI threads, in which case the embedder is responsible for flushing the microtask queue.

Definition at line 763 of file shell.cc.

GetConcurrentWorkerTaskRunner()

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

(

)

const

Definition at line 2488 of file shell.cc.

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

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 960 of file shell.cc.

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

References FML_DCHECK.

Referenced by flutter::testing::TEST_F().

GetEngine()

fml::TaskRunnerAffineWeakPtr< 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 941 of file shell.cc.

          {
  return parent_raster_thread_merger_;
}
 

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 951 of file shell.cc.

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 2421 of file shell.cc.

Referenced by flutter::testing::ShellTestPlatformViewBuilder::operator()(), flutter::testing::TEST_F(), and flutter::testing::TEST_F().

GetMainDisplayRefreshRate()

double flutter::Shell::GetMainDisplayRefreshRate

(

)

Queries the DisplayManager for the main display refresh rate.

Definition at line 2068 of file shell.cc.

                                 {
  FML_DCHECK(task_runners_.GetUITaskRunner()->RunsTasksOnCurrentThread());
  response->SetObject();

References FML_DCHECK, flutter::TaskRunners::GetUITaskRunner(), and fml::TaskRunner::RunsTasksOnCurrentThread().

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

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 931 of file shell.cc.

                                         {
  return settings_;
}

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 2476 of file shell.cc.

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 946 of file shell.cc.

Referenced by flutter::ConfigureShell(), flutter::testing::ShellTest::DispatchPointerData(), FlutterEngineSetNextFrameCallback(), flutter::RunTester(), flutter::testing::TEST_F(), and flutter::testing::ShellTest::VSyncFlush().

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 936 of file shell.cc.

                                               {
  return task_runners_;
}
 

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

GetSettings()

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

overridevirtual

Returns

The settings used to launch this shell.

Implements flutter::Rasterizer::Delegate.

Definition at line 923 of file shell.cc.

                                        {
    PersistentCache::GetCacheForProcess()->Purge();

References flutter::PersistentCache::GetCacheForProcess(), and flutter::PersistentCache::Purge().

Referenced by InferMetalPlatformViewCreationCallback(), flutter::Spawn(), flutter::testing::TEST_F(), and flutter::testing::TEST_F().

GetShutdownSafeIOTaskRunner()

std::shared_ptr< fml::BasicTaskRunner > flutter::Shell::GetShutdownSafeIOTaskRunner

(

)

The IO thread can be used for background tasks, including tasks that perform graphics operations using the resource context. But the IO thread will lose the resource context during shutdown of the Shell. Tasks that require the IO manager or the resource context must not run after that phase of shutdown.

Returns

A BasicTaskRunner that posts tasks to the IO thread but stops running tasks after the Shell shuts down the IO manager.

Definition at line 956 of file shell.cc.

Referenced by InferOpenGLPlatformViewCreationCallback().

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 927 of file shell.cc.

Referenced by flutter::testing::ShellTest::DispatchPointerData(), flutter::testing::GetRasterizerResourceCacheBytesSync(), InferMetalPlatformViewCreationCallback(), InferOpenGLPlatformViewCreationCallback(), InferSoftwarePlatformViewCreationCallback(), InferVulkanPlatformViewCreationCallback(), flutter::testing::ShellTest::NotifyIdle(), flutter::testing::ShellTestPlatformViewBuilder::operator()(), flutter::testing::ShellTest::PlatformViewNotifyCreated(), flutter::testing::ShellTest::PlatformViewNotifyDestroyed(), flutter::testing::ShellTest::PumpOneFrame(), flutter::testing::RasterizerIsTornDown(), flutter::testing::ShellTest::RestartEngine(), flutter::testing::ShellTest::RunEngine(), flutter::RunTester(), flutter::testing::ShellTest::SendEnginePlatformMessage(), flutter::testing::ShellTest::SetViewportMetrics(), flutter::Spawn(), flutter::StartupAndShutdownShell(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::TEST_F(), flutter::testing::ValidateShell(), and flutter::testing::ShellTest::VSyncFlush().

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 807 of file shell.cc.

                                                             {
              FML_LOG(ERROR) << "Could not launch engine with configuration.";
            }
 
            result(run_result);
          }));
}
 
std::optional<DartErrorCode> Shell::GetUIIsolateLastError() const {
  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;

Referenced by flutter::ScriptCompletionTaskObserver::DidProcessTask().

GetVsyncWaiter()

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

(

)

const

Definition at line 2480 of file shell.cc.

                                        {
  return fml::TimePoint::Now();
}
 
const std::shared_ptr<PlatformMessageHandler>&
Shell::GetPlatformMessageHandler() const {

References fml::TimePoint::Now().

InferVmInitDataFromSettings()

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

static

Definition at line 207 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};
}

References flutter::DartVMRef::Create(), flutter::DartSnapshot::IsolateSnapshotFromSettings(), and flutter::DartSnapshot::VMSnapshotFromSettings().

Referenced by Create().

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 849 of file shell.cc.

                     {

Referenced by flutter::RunTester(), flutter::testing::ValidateDestroyPlatformView(), and flutter::testing::ValidateShell().

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 741 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]() {

OnDisplayUpdates()

void flutter::Shell::OnDisplayUpdates

(

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

displays

)

Notifies the display manager of the updates.

Definition at line 2451 of file shell.cc.

                                    :
      is_gpu_disabled_sync_switch_->SetSwitch(true);
      return;
    default:
      FML_DCHECK(false);
  }
}
 
void Shell::OnDisplayUpdates(std::vector<std::unique_ptr<Display>> displays) {
  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());
  }
  fml::TaskRunner::RunNowOrPostTask(task_runners_.GetUITaskRunner(),

Referenced by flutter::ConfigureShell().

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 2072 of file shell.cc.

                                        {
  return display_manager_->GetMainDisplayRefreshRate();
}
 
void Shell::RegisterImageDecoder(ImageGeneratorFactory factory,
                                 int32_t priority) {
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
  FML_DCHECK(is_set_up_);
 

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 2406 of file shell.cc.

               {
    return fml::Status();
  } else {
    return fml::Status(fml::StatusCode::kDeadlineExceeded, "timeout");
  }
}
 
bool Shell::ReloadSystemFonts() {
  FML_DCHECK(is_set_up_);
  FML_DCHECK(task_runners_.GetPlatformTaskRunner()->RunsTasksOnCurrentThread());
 
  if (!engine_) {

RunEngine() [1/2]

void flutter::Shell::RunEngine

(

RunConfiguration

run_configuration

)

Starts an isolate for the given RunConfiguration.

Definition at line 769 of file shell.cc.

Referenced by flutter::RunTester().

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 773 of file shell.cc.

               {
    engine_->FlushMicrotaskQueue();
  }
}
 
void Shell::RunEngine(RunConfiguration run_configuration) {
  RunEngine(std::move(run_configuration), nullptr);
}
 
void Shell::RunEngine(
    RunConfiguration run_configuration,
    const std::function<void(Engine::RunStatus)>& result_callback) {
  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;

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 2343 of file shell.cc.

                                                      {
        if (engine) {
          engine->SendViewFocusEvent(event);
        }
      });
}
 
Rasterizer::Screenshot Shell::Screenshot(
    Rasterizer::ScreenshotType screenshot_type,
    bool base64_encode) {
  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                  //
  ]() {

SetGpuAvailability()

void flutter::Shell::SetGpuAvailability

(

GpuAvailability

availability

)

Marks the GPU as available or unavailable.

Definition at line 2426 of file shell.cc.

          {
  return is_gpu_disabled_sync_switch_;
}
 
void Shell::SetGpuAvailability(GpuAvailability availability) {
  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();

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 687 of file shell.cc.

                                                           {
      task_queues->Unmerge(platform_queue_id, ui_queue_id);
    }
  }
}
 
std::unique_ptr<Shell> Shell::Spawn(
    RunConfiguration run_configuration,
    const std::string& initial_route,
    const CreateCallback<PlatformView>& on_create_platform_view,
    const CreateCallback<Rasterizer>& on_create_rasterizer) const {
  FML_DCHECK(task_runners_.IsValid());
 
  if (settings_.merged_platform_ui_thread ==
      Settings::MergedPlatformUIThread::kMergeAfterLaunch) {
    // Spawning engines that share the same task runners can result in
    // deadlocks when the UI task runner is moved to the platform thread.
    FML_LOG(ERROR) << "MergedPlatformUIThread::kMergeAfterLaunch does not "
                      "support spawning";
    return nullptr;
  }
 
  // 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<fml::SyncSwitch>& is_gpu_disabled_sync_switch,
          const std::shared_future<impeller::RuntimeStageBackend>&
              runtime_stage_backend) {
        return engine->Spawn(
            /*delegate=*/delegate,
            /*dispatcher_maker=*/dispatcher_maker,
            /*settings=*/settings,
            /*animator=*/std::move(animator),

Referenced by flutter::Spawn().

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 2378 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(

Friends And Related Symbol Documentation

testing::ShellTest

friend class testing::ShellTest

friend

Definition at line 847 of file shell.h.

---

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

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