Flutter Engine
dart_vm.h
Go to the documentation of this file.
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 
184 };
185 
186 } // namespace flutter
187 
188 #endif // FLUTTER_RUNTIME_DART_VM_H_
const Settings & GetSettings() const
The settings used to launch the running VM instance.
Definition: dart_vm.cc:489
std::shared_ptr< ServiceProtocol > GetServiceProtocol() const
The service protocol instance associated with this running Dart VM instance. This object manages nati...
Definition: dart_vm.cc:493
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).
Definition: dart_vm.cc:502
Represents an instance of a live isolate. An isolate is a separate Dart execution context...
Definition: dart_isolate.h:62
static bool IsRunningPrecompiledCode()
Checks if VM instances in the process can run precompiled code. This call can be made at any time and...
Definition: dart_vm.cc:199
std::shared_ptr< fml::ConcurrentMessageLoop > GetConcurrentMessageLoop()
The concurrent message loop hosts threads that are used by the engine to perform tasks long running b...
Definition: dart_vm.cc:506
An interface used by Skia to schedule work on engine managed threads (usually workers in a concurrent...
static size_t GetVMLaunchCount()
The number of times the VM has been launched in the process. This call is inherently racy because the...
Definition: dart_vm.cc:261
Describes a running instance of the Dart VM. There may only be one running instance of the Dart VM in...
Definition: dart_vm.h:61
std::shared_ptr< IsolateNameServer > GetIsolateNameServer() const
The isolate name server for this running VM instance. The isolate name server maps names (strings) to...
Definition: dart_vm.cc:497
std::shared_ptr< const DartVMData > GetVMData() const
The VM and isolate snapshots used by this running Dart VM instance.
Definition: dart_vm.cc:485
#define FML_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:27