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 Settings &	GetSettings () const
	The settings used to launch the running VM instance.

std::shared_ptr< const DartVMData >	GetVMData () const
	The VM and isolate snapshots used by this running Dart VM instance.

std::shared_ptr< ServiceProtocol >	GetServiceProtocol () const
	The service protocol instance associated with this running Dart VM instance. This object manages native handlers for engine vended service protocol methods.

std::shared_ptr< IsolateNameServer >	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.

std::shared_ptr< fml::ConcurrentTaskRunner >	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).

std::shared_ptr< fml::ConcurrentMessageLoop >	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.

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.

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.

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 515 of file dart_vm.cc.

                {
  // Setting the executor is not thread safe but Dart VM shutdown is. So
  // this call is thread-safe.
  SkExecutor::SetDefault(nullptr);
 
  if (Dart_CurrentIsolate() != nullptr) {
    Dart_ExitIsolate();
  }
 
  DartVMInitializer::Cleanup();
 
  dart::bin::CleanupDartIo();
}

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 550 of file dart_vm.cc.

                                                                         {
  return concurrent_message_loop_;
}

◆ 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 546 of file dart_vm.cc.

                                            {
  return concurrent_message_loop_->GetTaskRunner();
}

◆ 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 541 of file dart_vm.cc.

                                                                    {
  return isolate_name_server_;
}

◆ 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 537 of file dart_vm.cc.

                                                                {
  return service_protocol_;
}

◆ 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 533 of file dart_vm.cc.

                                          {
  return settings_;
}

◆ 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 529 of file dart_vm.cc.

                                                        {
  return vm_data_;
}

◆ 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 281 of file dart_vm.cc.

                                {
  return gVMLaunchCount;
}

◆ IsRunningPrecompiledCode()

bool flutter::DartVM::IsRunningPrecompiledCode ( )

static

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.

Returns: If VM instances in the process run precompiled code.

Definition at line 205 of file dart_vm.cc.

                                      {
  return Dart_IsPrecompiledRuntime();
}

Friends And Related Symbol Documentation

◆ DartIsolate

friend class DartIsolate

friend

Definition at line 172 of file dart_vm.h.

◆ DartVMRef

friend class DartVMRef