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 | |
27 | namespace 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. |
61 | class 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 | Settings settings, |
176 | fml::RefPtr<DartSnapshot> vm_snapshot, |
177 | fml::RefPtr<DartSnapshot> isolate_snapshot, |
178 | std::shared_ptr<IsolateNameServer> isolate_name_server); |
179 | |
180 | DartVM(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 | |