Flutter Engine
flutter::DartVM Class Reference

Describes a running instance of the Dart VM. There may only be one running instance of the Dart VM in the process at any given time. The Dart VM may be created and destroyed on any thread. Typically, the first Flutter shell instance running in the process bootstraps the Dart VM in the process as it starts up. This cost is borne on the platform task runner of that first Flutter shell. When the last Flutter shell instance is destroyed, the VM is destroyed as well if all shell instances were launched with the Settings::leak_vm flag set to false. If there is any shell launch in the process with leak_vm set to true, the VM is never shut down in the process. When the VM is shutdown, the cost of the shutdown is borne on the platform task runner of the last shell instance to be shut down. More...

#include <dart_vm.h>

Public Member Functions

 ~DartVM ()
 
const SettingsGetSettings () const
 The settings used to launch the running VM instance. More...
 
std::shared_ptr< const DartVMDataGetVMData () const
 The VM and isolate snapshots used by this running Dart VM instance. More...
 
std::shared_ptr< ServiceProtocolGetServiceProtocol () const
 The service protocol instance associated with this running Dart VM instance. This object manages native handlers for engine vended service protocol methods. More...
 
std::shared_ptr< IsolateNameServerGetIsolateNameServer () const
 The isolate name server for this running VM instance. The isolate name server maps names (strings) to Dart ports. Running isolates can discover and communicate with each other by advertising and resolving ports at well known names. More...
 
std::shared_ptr< fml::ConcurrentTaskRunnerGetConcurrentWorkerTaskRunner () const
 The task runner whose tasks may be executed concurrently on a pool of worker threads. All subsystems within a running shell instance use this worker pool for their concurrent tasks. This also means that the concurrent worker pool may service tasks from multiple shell instances. The number of workers in a concurrent worker pool depends on the hardware concurrency of the target device (usually equal to the number of logical CPU cores). More...
 
std::shared_ptr< fml::ConcurrentMessageLoopGetConcurrentMessageLoop ()
 The concurrent message loop hosts threads that are used by the engine to perform tasks long running background tasks. Typically, to post tasks to this message loop, the GetConcurrentWorkerTaskRunner method may be used. More...
 

Static Public Member Functions

static bool IsRunningPrecompiledCode ()
 Checks if VM instances in the process can run precompiled code. This call can be made at any time and does not depend on a running VM instance. There are no threading restrictions. More...
 
static size_t GetVMLaunchCount ()
 The number of times the VM has been launched in the process. This call is inherently racy because the VM could be in the process of starting up on another thread between the time the caller makes this call and uses to result. For this purpose, this call is only meant to be used as a debugging aid and primarily only used in tests where the threading model is consistent. More...
 

Friends

class DartVMRef
 
class DartIsolate
 

Detailed Description

Describes a running instance of the Dart VM. There may only be one running instance of the Dart VM in the process at any given time. The Dart VM may be created and destroyed on any thread. Typically, the first Flutter shell instance running in the process bootstraps the Dart VM in the process as it starts up. This cost is borne on the platform task runner of that first Flutter shell. When the last Flutter shell instance is destroyed, the VM is destroyed as well if all shell instances were launched with the Settings::leak_vm flag set to false. If there is any shell launch in the process with leak_vm set to true, the VM is never shut down in the process. When the VM is shutdown, the cost of the shutdown is borne on the platform task runner of the last shell instance to be shut down.

Due to threading considerations, callers may never create an instance of the DartVM directly. All constructors to the DartVM are private. Instead, all callers that need a running VM reference need to access it via the DartVMRef::Create call. This call returns a strong reference to the running VM if one exists in the process already. If a running VM instance is not available in the process, a new instance is created and a strong reference returned to the callers. The DartVMRef::Create call ensures that there are no data races during the creation or shutdown of a Dart VM (since a VM may be created and destroyed on any thread). Due to this behavior, all callers needing a running VM instance must provide snapshots and VM settings necessary to create a VM (even if they end up not being used).

In a running VM instance, the service isolate is launched by default if the VM is configured to do so. All root isolates must be launched and referenced explicitly.

Definition at line 61 of file dart_vm.h.

Constructor & Destructor Documentation

◆ ~DartVM()

flutter::DartVM::~DartVM ( )

Definition at line 466 of file dart_vm.cc.

References FML_CHECK.

466  {
467  // Setting the executor is not thread safe but Dart VM shutdown is. So
468  // this call is thread-safe.
469  SkExecutor::SetDefault(nullptr);
470 
471  if (Dart_CurrentIsolate() != nullptr) {
472  Dart_ExitIsolate();
473  }
474 
475  char* result = Dart_Cleanup();
476 
477  dart::bin::CleanupDartIo();
478 
479  FML_CHECK(result == nullptr)
480  << "Could not cleanly shut down the Dart VM. Error: \"" << result
481  << "\".";
482  free(result);
483 }
#define FML_CHECK(condition)
Definition: logging.h:68

Member Function Documentation

◆ GetConcurrentMessageLoop()

std::shared_ptr< fml::ConcurrentMessageLoop > flutter::DartVM::GetConcurrentMessageLoop ( )

The concurrent message loop hosts threads that are used by the engine to perform tasks long running background tasks. Typically, to post tasks to this message loop, the GetConcurrentWorkerTaskRunner method may be used.

See also
GetConcurrentWorkerTaskRunner
Returns
The concurrent message loop used by this running Dart VM instance.

Definition at line 506 of file dart_vm.cc.

506  {
507  return concurrent_message_loop_;
508 }

◆ GetConcurrentWorkerTaskRunner()

std::shared_ptr< fml::ConcurrentTaskRunner > flutter::DartVM::GetConcurrentWorkerTaskRunner ( ) const

The task runner whose tasks may be executed concurrently on a pool of worker threads. All subsystems within a running shell instance use this worker pool for their concurrent tasks. This also means that the concurrent worker pool may service tasks from multiple shell instances. The number of workers in a concurrent worker pool depends on the hardware concurrency of the target device (usually equal to the number of logical CPU cores).

Attention
Even though concurrent task queue is associated with a running Dart VM instance, the worker pool used by the Flutter engine is NOT shared with the Dart VM internal worker pool. The presence of this worker pool as member of the Dart VM is merely to utilize the strong thread safety guarantees around Dart VM lifecycle for the lifecycle of the concurrent worker pool as well.
Returns
The task runner for the concurrent worker thread pool.

Definition at line 502 of file dart_vm.cc.

502  {
503  return concurrent_message_loop_->GetTaskRunner();
504 }

◆ GetIsolateNameServer()

std::shared_ptr< IsolateNameServer > flutter::DartVM::GetIsolateNameServer ( ) const

The isolate name server for this running VM instance. The isolate name server maps names (strings) to Dart ports. Running isolates can discover and communicate with each other by advertising and resolving ports at well known names.

Returns
The isolate name server.

Definition at line 497 of file dart_vm.cc.

497  {
498  return isolate_name_server_;
499 }

◆ GetServiceProtocol()

std::shared_ptr< ServiceProtocol > flutter::DartVM::GetServiceProtocol ( ) const

The service protocol instance associated with this running Dart VM instance. This object manages native handlers for engine vended service protocol methods.

Returns
The service protocol for this Dart VM instance.

Definition at line 493 of file dart_vm.cc.

Referenced by flutter::Shell::GetDartVM(), and flutter::Shell::~Shell().

493  {
494  return service_protocol_;
495 }

◆ GetSettings()

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

The settings used to launch the running VM instance.

Attention
Even though all callers that need to acquire a strong reference to a VM need to provide a valid settings object, the VM will only reference the settings used by the first caller that bootstraps the VM in the process.
Returns
A valid setting object.

Definition at line 489 of file dart_vm.cc.

References settings_.

489  {
490  return settings_;
491 }

◆ GetVMData()

std::shared_ptr< const DartVMData > flutter::DartVM::GetVMData ( ) const

The VM and isolate snapshots used by this running Dart VM instance.

Returns
A valid VM data instance.

Definition at line 485 of file dart_vm.cc.

485  {
486  return vm_data_;
487 }

◆ GetVMLaunchCount()

size_t flutter::DartVM::GetVMLaunchCount ( )
static

The number of times the VM has been launched in the process. This call is inherently racy because the VM could be in the process of starting up on another thread between the time the caller makes this call and uses to result. For this purpose, this call is only meant to be used as a debugging aid and primarily only used in tests where the threading model is consistent.

Returns
The number of times the VM has been launched.

Definition at line 261 of file dart_vm.cc.

References args, fml::ConcurrentMessageLoop::Create(), flutter::DartFileModifiedCallback(), flutter::DartOldGenHeapSizeArgs(), flutter::EmbedderInformationCallback(), flutter::EnableTracingIfNecessary(), FML_CHECK, FML_DCHECK, FML_LOG, flutter::GetVMServiceAssetsArchiveCallback(), flutter::gVMLaunchCount, flutter::kDartDisableServiceAuthCodesArgs, flutter::kDartEndlessTraceBufferArgs, flutter::kDartStartPausedArgs, flutter::kDartSystraceTraceBufferArgs, flutter::kDartTraceStartupArgs, flutter::ProfilingFlags(), flutter::PushBackAll(), flutter::ServiceStreamCancelCallback(), flutter::ServiceStreamListenCallback(), settings_, fml::size(), flutter::ThreadExitCallback(), and TRACE_EVENT0.

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

261  {
262  return gVMLaunchCount;
263 }
static std::atomic_size_t gVMLaunchCount
Definition: dart_vm.cc:259

◆ IsRunningPrecompiledCode()

Friends And Related Function Documentation

◆ DartIsolate

friend class DartIsolate
friend

Definition at line 172 of file dart_vm.h.

◆ DartVMRef

friend class DartVMRef
friend

Definition at line 171 of file dart_vm.h.


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