1// Copyright 2013 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef FLUTTER_RUNTIME_DART_VM_H_
6#define FLUTTER_RUNTIME_DART_VM_H_
7
8#include <memory>
9#include <string>
10
11#include "flutter/common/settings.h"
12#include "flutter/fml/build_config.h"
13#include "flutter/fml/closure.h"
14#include "flutter/fml/macros.h"
15#include "flutter/fml/memory/ref_counted.h"
16#include "flutter/fml/memory/ref_ptr.h"
17#include "flutter/fml/memory/weak_ptr.h"
18#include "flutter/fml/message_loop.h"
19#include "flutter/lib/ui/isolate_name_server/isolate_name_server.h"
20#include "flutter/runtime/dart_isolate.h"
21#include "flutter/runtime/dart_snapshot.h"
22#include "flutter/runtime/dart_vm_data.h"
23#include "flutter/runtime/service_protocol.h"
24#include "flutter/runtime/skia_concurrent_executor.h"
25#include "third_party/dart/runtime/include/dart_api.h"
26
27namespace flutter {
28
29//------------------------------------------------------------------------------
30/// @brief Describes a running instance of the Dart VM. There may only be
31/// one running instance of the Dart VM in the process at any given
32/// time. The Dart VM may be created and destroyed on any thread.
33/// Typically, the first Flutter shell instance running in the
34/// process bootstraps the Dart VM in the process as it starts up.
35/// This cost is borne on the platform task runner of that first
36/// Flutter shell. When the last Flutter shell instance is
37/// destroyed, the VM is destroyed as well if all shell instances
38/// were launched with the `Settings::leak_vm` flag set to false. If
39/// there is any shell launch in the process with `leak_vm` set to
40/// true, the VM is never shut down in the process. When the VM is
41/// shutdown, the cost of the shutdown is borne on the platform task
42/// runner of the last shell instance to be shut down.
43///
44/// Due to threading considerations, callers may never create an
45/// instance of the DartVM directly. All constructors to the DartVM
46/// are private. Instead, all callers that need a running VM
47/// reference need to access it via the `DartVMRef::Create` call.
48/// This call returns a strong reference to the running VM if one
49/// exists in the process already. If a running VM instance is not
50/// available in the process, a new instance is created and a strong
51/// reference returned to the callers. The DartVMRef::Create call
52/// ensures that there are no data races during the creation or
53/// shutdown of a Dart VM (since a VM may be created and destroyed
54/// on any thread). Due to this behavior, all callers needing a
55/// running VM instance must provide snapshots and VM settings
56/// necessary to create a VM (even if they end up not being used).
57///
58/// In a running VM instance, the service isolate is launched by
59/// default if the VM is configured to do so. All root isolates must
60/// be launched and referenced explicitly.
61class DartVM {
62 public:
63 ~DartVM();
64
65 //----------------------------------------------------------------------------
66 /// @brief Checks if VM instances in the process can run precompiled
67 /// code. This call can be made at any time and does not depend on
68 /// a running VM instance. There are no threading restrictions.
69 ///
70 /// @return If VM instances in the process run precompiled code.
71 ///
72 static bool IsRunningPrecompiledCode();
73
74 //----------------------------------------------------------------------------
75 /// @brief The number of times the VM has been launched in the process.
76 /// This call is inherently racy because the VM could be in the
77 /// process of starting up on another thread between the time the
78 /// caller makes this call and uses to result. For this purpose,
79 /// this call is only meant to be used as a debugging aid and
80 /// primarily only used in tests where the threading model is
81 /// consistent.
82 ///
83 /// @return The number of times the VM has been launched.
84 ///
85 static size_t GetVMLaunchCount();
86
87 //----------------------------------------------------------------------------
88 /// @brief The settings used to launch the running VM instance.
89 ///
90 /// @attention Even though all callers that need to acquire a strong
91 /// reference to a VM need to provide a valid settings object, the
92 /// VM will only reference the settings used by the first caller
93 /// that bootstraps the VM in the process.
94 ///
95 /// @return A valid setting object.
96 ///
97 const Settings& GetSettings() const;
98
99 //----------------------------------------------------------------------------
100 /// @brief The VM and isolate snapshots used by this running Dart VM
101 /// instance.
102 ///
103 /// @return A valid VM data instance.
104 ///
105 std::shared_ptr<const DartVMData> GetVMData() const;
106
107 //----------------------------------------------------------------------------
108 /// @brief The service protocol instance associated with this running
109 /// Dart VM instance. This object manages native handlers for
110 /// engine vended service protocol methods.
111 ///
112 /// @return The service protocol for this Dart VM instance.
113 ///
114 std::shared_ptr<ServiceProtocol> GetServiceProtocol() const;
115
116 //----------------------------------------------------------------------------
117 /// @brief The isolate name server for this running VM instance. The
118 /// isolate name server maps names (strings) to Dart ports.
119 /// Running isolates can discover and communicate with each other
120 /// by advertising and resolving ports at well known names.
121 ///
122 /// @return The isolate name server.
123 ///
124 std::shared_ptr<IsolateNameServer> GetIsolateNameServer() const;
125
126 //----------------------------------------------------------------------------
127 /// @brief The task runner whose tasks may be executed concurrently on a
128 /// pool of worker threads. All subsystems within a running shell
129 /// instance use this worker pool for their concurrent tasks. This
130 /// also means that the concurrent worker pool may service tasks
131 /// from multiple shell instances. The number of workers in a
132 /// concurrent worker pool depends on the hardware concurrency
133 /// of the target device (usually equal to the number of logical
134 /// CPU cores).
135 ///
136 ///
137 /// @attention Even though concurrent task queue is associated with a running
138 /// Dart VM instance, the worker pool used by the Flutter engine
139 /// is NOT shared with the Dart VM internal worker pool. The
140 /// presence of this worker pool as member of the Dart VM is
141 /// merely to utilize the strong thread safety guarantees around
142 /// Dart VM lifecycle for the lifecycle of the concurrent worker
143 /// pool as well.
144 ///
145 /// @return The task runner for the concurrent worker thread pool.
146 ///
147 std::shared_ptr<fml::ConcurrentTaskRunner> GetConcurrentWorkerTaskRunner()
148 const;
149
150 //----------------------------------------------------------------------------
151 /// @brief The concurrent message loop hosts threads that are used by the
152 /// engine to perform tasks long running background tasks.
153 /// Typically, to post tasks to this message loop, the
154 /// `GetConcurrentWorkerTaskRunner` method may be used.
155 ///
156 /// @see GetConcurrentWorkerTaskRunner
157 ///
158 /// @return The concurrent message loop used by this running Dart VM
159 /// instance.
160 ///
161 std::shared_ptr<fml::ConcurrentMessageLoop> GetConcurrentMessageLoop();
162
163 private:
164 const Settings settings_;
165 std::shared_ptr<fml::ConcurrentMessageLoop> concurrent_message_loop_;
166 SkiaConcurrentExecutor skia_concurrent_executor_;
167 std::shared_ptr<const DartVMData> vm_data_;
168 const std::shared_ptr<IsolateNameServer> isolate_name_server_;
169 const std::shared_ptr<ServiceProtocol> service_protocol_;
170
171 friend class DartVMRef;
172 friend class DartIsolate;
173
174 static std::shared_ptr<DartVM> Create(
175 const Settings& settings,
176 fml::RefPtr<const DartSnapshot> vm_snapshot,
177 fml::RefPtr<const DartSnapshot> isolate_snapshot,
178 std::shared_ptr<IsolateNameServer> isolate_name_server);
179
180 DartVM(const std::shared_ptr<const DartVMData>& data,
181 std::shared_ptr<IsolateNameServer> isolate_name_server);
182
183 FML_DISALLOW_COPY_AND_ASSIGN(DartVM);
184};
185
186} // namespace flutter
187
188#endif // FLUTTER_RUNTIME_DART_VM_H_
189

source code of flutter_engine/flutter/runtime/dart_vm.h