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_SNAPSHOT_H_ |
6 | #define FLUTTER_RUNTIME_DART_SNAPSHOT_H_ |
7 | |
8 | #include <memory> |
9 | #include <string> |
10 | |
11 | #include "flutter/common/settings.h" |
12 | #include "flutter/fml/macros.h" |
13 | #include "flutter/fml/memory/ref_counted.h" |
14 | |
15 | namespace flutter { |
16 | |
17 | //------------------------------------------------------------------------------ |
18 | /// @brief A read-only Dart heap snapshot, or, read-executable mapping of |
19 | /// AOT compiled Dart code. |
20 | /// |
21 | /// To make Dart code startup more performant, the Flutter tools on |
22 | /// the host snapshot the state of the Dart heap at specific points |
23 | /// and package the same with the Flutter application. When the Dart |
24 | /// VM on the target is configured to run AOT compiled Dart code, |
25 | /// the tools also compile the developer's Flutter application code |
26 | /// to target specific machine code (instructions). This class deals |
27 | /// with the mapping of both these buffers at runtime on the target. |
28 | /// |
29 | /// A Flutter application typically needs two instances of this |
30 | /// class at runtime to run Dart code. One instance is for the VM |
31 | /// and is called the "core snapshot". The other is the isolate |
32 | /// and called the "isolate snapshot". Different root isolates can |
33 | /// be launched with different isolate snapshots. |
34 | /// |
35 | /// These snapshots are typically memory-mapped at runtime, or, |
36 | /// referenced directly as symbols present in Mach or ELF binaries. |
37 | /// |
38 | /// In the case of the core snapshot, the snapshot is collected when |
39 | /// the VM shuts down. The isolate snapshot is collected when the |
40 | /// isolate group shuts down. |
41 | /// |
42 | class DartSnapshot : public fml::RefCountedThreadSafe<DartSnapshot> { |
43 | public: |
44 | //---------------------------------------------------------------------------- |
45 | /// The symbol name of the heap data of the core snapshot in a dynamic library |
46 | /// or currently loaded process. |
47 | /// |
48 | static const char* kVMDataSymbol; |
49 | //---------------------------------------------------------------------------- |
50 | /// The symbol name of the instructions data of the core snapshot in a dynamic |
51 | /// library or currently loaded process. |
52 | /// |
53 | static const char* kVMInstructionsSymbol; |
54 | //---------------------------------------------------------------------------- |
55 | /// The symbol name of the heap data of the isolate snapshot in a dynamic |
56 | /// library or currently loaded process. |
57 | /// |
58 | static const char* kIsolateDataSymbol; |
59 | //---------------------------------------------------------------------------- |
60 | /// The symbol name of the instructions data of the isolate snapshot in a |
61 | /// dynamic library or currently loaded process. |
62 | /// |
63 | static const char* kIsolateInstructionsSymbol; |
64 | |
65 | //---------------------------------------------------------------------------- |
66 | /// @brief From the fields present in the given settings object, infer |
67 | /// the core snapshot. |
68 | /// |
69 | /// @attention Depending on the runtime mode of the Flutter application and |
70 | /// the target that Flutter is running on, a complex fallback |
71 | /// mechanism is in place to infer the locations of each snapshot |
72 | /// buffer. If the caller wants to explicitly specify the buffers |
73 | /// of the core snapshot, the `Settings::vm_snapshot_data` and |
74 | /// `Settings::vm_snapshots_instr` mapping fields may be used. |
75 | /// This specification takes precedence over all fallback search |
76 | /// paths. |
77 | /// |
78 | /// @param[in] settings The settings to infer the core snapshot from. |
79 | /// |
80 | /// @return A valid core snapshot or nullptr. |
81 | /// |
82 | static fml::RefPtr<DartSnapshot> VMSnapshotFromSettings( |
83 | const Settings& settings); |
84 | |
85 | //---------------------------------------------------------------------------- |
86 | /// @brief From the fields present in the given settings object, infer |
87 | /// the isolate snapshot. |
88 | /// |
89 | /// @attention Depending on the runtime mode of the Flutter application and |
90 | /// the target that Flutter is running on, a complex fallback |
91 | /// mechanism is in place to infer the locations of each snapshot |
92 | /// buffer. If the caller wants to explicitly specify the buffers |
93 | /// of the isolate snapshot, the `Settings::isolate_snapshot_data` |
94 | /// and `Settings::isolate_snapshots_instr` mapping fields may be |
95 | /// used. This specification takes precedence over all fallback |
96 | /// search paths. |
97 | /// |
98 | /// @param[in] settings The settings to infer the isolate snapshot from. |
99 | /// |
100 | /// @return A valid isolate snapshot or nullptr. |
101 | /// |
102 | static fml::RefPtr<DartSnapshot> IsolateSnapshotFromSettings( |
103 | const Settings& settings); |
104 | |
105 | //---------------------------------------------------------------------------- |
106 | /// @brief Determines if this snapshot contains a heap component. Since |
107 | /// the instructions component is optional, the method does not |
108 | /// check for its presence. Use `IsValidForAOT` to determine if |
109 | /// both the heap and instructions components of the snapshot are |
110 | /// present. |
111 | /// |
112 | /// @return Returns if the snapshot contains a heap component. |
113 | /// |
114 | bool IsValid() const; |
115 | |
116 | //---------------------------------------------------------------------------- |
117 | /// @brief Determines if this snapshot contains both the heap and |
118 | /// instructions components. This is only useful when determining |
119 | /// if the snapshot may be used to run AOT code. The instructions |
120 | /// component will be absent in JIT modes. |
121 | /// |
122 | /// @return Returns if the snapshot contains both a heap and instructions |
123 | /// component. |
124 | /// |
125 | bool IsValidForAOT() const; |
126 | |
127 | //---------------------------------------------------------------------------- |
128 | /// @brief Get a pointer to the read-only mapping to the heap snapshot. |
129 | /// |
130 | /// @return The data mapping. |
131 | /// |
132 | const uint8_t* GetDataMapping() const; |
133 | |
134 | //---------------------------------------------------------------------------- |
135 | /// @brief Get a pointer to the read-execute mapping to the instructions |
136 | /// snapshot. |
137 | /// |
138 | /// @return The instructions mapping. |
139 | /// |
140 | const uint8_t* GetInstructionsMapping() const; |
141 | |
142 | private: |
143 | std::shared_ptr<const fml::Mapping> data_; |
144 | std::shared_ptr<const fml::Mapping> instructions_; |
145 | |
146 | DartSnapshot(std::shared_ptr<const fml::Mapping> data, |
147 | std::shared_ptr<const fml::Mapping> instructions); |
148 | |
149 | ~DartSnapshot(); |
150 | |
151 | FML_FRIEND_REF_COUNTED_THREAD_SAFE(DartSnapshot); |
152 | FML_FRIEND_MAKE_REF_COUNTED(DartSnapshot); |
153 | FML_DISALLOW_COPY_AND_ASSIGN(DartSnapshot); |
154 | }; |
155 | |
156 | } // namespace flutter |
157 | |
158 | #endif // FLUTTER_RUNTIME_DART_SNAPSHOT_H_ |
159 | |