From cd881067216bffcdc4978ddd5225fda51395236b Mon Sep 17 00:00:00 2001 From: Chinmay Garde Date: Tue, 15 Oct 2019 12:03:27 -0700 Subject: [PATCH 1/2] Document //flutter/runtime/dart_vm --- runtime/dart_vm.h | 102 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/runtime/dart_vm.h b/runtime/dart_vm.h index 7e8c2a67fd1b4..b7c204f2fe1d0 100644 --- a/runtime/dart_vm.h +++ b/runtime/dart_vm.h @@ -26,22 +26,124 @@ namespace flutter { +//------------------------------------------------------------------------------ +/// @brief 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 he 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 is the VM is configured to do so. All root isolates must +/// be launched and referenced explicitly. class DartVM { public: ~DartVM(); + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return If VM instances in the process run precompiled code. + /// static bool IsRunningPrecompiledCode(); + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return The number of times the VM has been launched. + /// static size_t GetVMLaunchCount(); + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return A valid setting object. + /// const Settings& GetSettings() const; + //---------------------------------------------------------------------------- + /// @brief The VM and isolate snapshots used by this running Dart VM + /// instance. + /// + /// @return A valid VM data instance. + /// std::shared_ptr GetVMData() const; + //---------------------------------------------------------------------------- + /// @brief The service protocol instance associated with this running VM + /// Dart VM instance. This object manages native handlers for + /// engine vended service protocol methods. + /// + /// @return The service protocol for this Dart VM instance. + /// std::shared_ptr GetServiceProtocol() const; + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return The isolate name server. + /// std::shared_ptr GetIsolateNameServer() const; + //---------------------------------------------------------------------------- + /// @brief The task runner whose tasks may 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 depending 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 to 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. + /// + /// @return The task runner for the concurrent worker thread pool. + /// std::shared_ptr GetConcurrentWorkerTaskRunner() const; From 65f77b1f61bda296a9da135f36fc9e2f6679c625 Mon Sep 17 00:00:00 2001 From: Chinmay Garde Date: Tue, 15 Oct 2019 13:49:21 -0700 Subject: [PATCH 2/2] Address PR comments. --- runtime/dart_vm.h | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/runtime/dart_vm.h b/runtime/dart_vm.h index b7c204f2fe1d0..40b8dc4a242e0 100644 --- a/runtime/dart_vm.h +++ b/runtime/dart_vm.h @@ -32,7 +32,7 @@ namespace flutter { /// 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 he platform task runner of that first +/// 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 @@ -56,7 +56,7 @@ namespace flutter { /// 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 is the VM is configured to do so. All root isolates must +/// default if the VM is configured to do so. All root isolates must /// be launched and referenced explicitly. class DartVM { public: @@ -105,7 +105,7 @@ class DartVM { std::shared_ptr GetVMData() const; //---------------------------------------------------------------------------- - /// @brief The service protocol instance associated with this running VM + /// @brief The service protocol instance associated with this running /// Dart VM instance. This object manages native handlers for /// engine vended service protocol methods. /// @@ -124,20 +124,20 @@ class DartVM { std::shared_ptr GetIsolateNameServer() const; //---------------------------------------------------------------------------- - /// @brief The task runner whose tasks may 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 depending on the hardware - /// concurrency of the target device (usually equal to the number - /// of logical CPU cores). + /// @brief 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 to 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 + /// 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.