diff --git a/runtime/dart_vm.h b/runtime/dart_vm.h index 7e8c2a67fd1b4..40b8dc4a242e0 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 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. 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 + /// 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 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. + /// + /// @return The task runner for the concurrent worker thread pool. + /// std::shared_ptr GetConcurrentWorkerTaskRunner() const;