Flutter Engine
dart_snapshot.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_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  ///
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  ///
103  const Settings& settings);
104 
105  //----------------------------------------------------------------------------
106  /// @brief Create an isolate snapshot from existing fml::Mappings.
107  ///
108  /// @param[in] snapshot_data The mapping for the heap snapshot.
109  /// @param[in] snapshot_instructions The mapping for the instructions
110  /// snapshot.
111  ///
112  /// @return A valid isolate snapshot or nullptr.
114  std::shared_ptr<const fml::Mapping> snapshot_data,
115  std::shared_ptr<const fml::Mapping> snapshot_instructions);
116 
117  //----------------------------------------------------------------------------
118  /// @brief Determines if this snapshot contains a heap component. Since
119  /// the instructions component is optional, the method does not
120  /// check for its presence. Use `IsValidForAOT` to determine if
121  /// both the heap and instructions components of the snapshot are
122  /// present.
123  ///
124  /// @return Returns if the snapshot contains a heap component.
125  ///
126  bool IsValid() const;
127 
128  //----------------------------------------------------------------------------
129  /// @brief Determines if this snapshot contains both the heap and
130  /// instructions components. This is only useful when determining
131  /// if the snapshot may be used to run AOT code. The instructions
132  /// component will be absent in JIT modes.
133  ///
134  /// @return Returns if the snapshot contains both a heap and instructions
135  /// component.
136  ///
137  bool IsValidForAOT() const;
138 
139  //----------------------------------------------------------------------------
140  /// @brief Get a pointer to the read-only mapping to the heap snapshot.
141  ///
142  /// @return The data mapping.
143  ///
144  const uint8_t* GetDataMapping() const;
145 
146  //----------------------------------------------------------------------------
147  /// @brief Get a pointer to the read-execute mapping to the instructions
148  /// snapshot.
149  ///
150  /// @return The instructions mapping.
151  ///
152  const uint8_t* GetInstructionsMapping() const;
153 
154  bool IsNullSafetyEnabled(
155  const fml::Mapping* application_kernel_mapping) const;
156 
157  private:
158  std::shared_ptr<const fml::Mapping> data_;
159  std::shared_ptr<const fml::Mapping> instructions_;
160 
161  DartSnapshot(std::shared_ptr<const fml::Mapping> data,
162  std::shared_ptr<const fml::Mapping> instructions);
163 
164  ~DartSnapshot();
165 
166  FML_FRIEND_REF_COUNTED_THREAD_SAFE(DartSnapshot);
167  FML_FRIEND_MAKE_REF_COUNTED(DartSnapshot);
168  FML_DISALLOW_COPY_AND_ASSIGN(DartSnapshot);
169 };
170 
171 } // namespace flutter
172 
173 #endif // FLUTTER_RUNTIME_DART_SNAPSHOT_H_
const uint8_t * GetInstructionsMapping() const
Get a pointer to the read-execute mapping to the instructions snapshot.
static fml::RefPtr< const DartSnapshot > IsolateSnapshotFromSettings(const Settings &settings)
From the fields present in the given settings object, infer the isolate snapshot. ...
static const char * kIsolateDataSymbol
Definition: dart_snapshot.h:58
bool IsNullSafetyEnabled(const fml::Mapping *application_kernel_mapping) const
static const char * kIsolateInstructionsSymbol
Definition: dart_snapshot.h:63
A read-only Dart heap snapshot, or, read-executable mapping of AOT compiled Dart code.
Definition: dart_snapshot.h:42
bool IsValidForAOT() const
Determines if this snapshot contains both the heap and instructions components. This is only useful w...
const uint8_t * GetDataMapping() const
Get a pointer to the read-only mapping to the heap snapshot.
static const char * kVMDataSymbol
Definition: dart_snapshot.h:48
bool IsValid() const
Determines if this snapshot contains a heap component. Since the instructions component is optional...
static const char * kVMInstructionsSymbol
Definition: dart_snapshot.h:53
static fml::RefPtr< DartSnapshot > IsolateSnapshotFromMappings(std::shared_ptr< const fml::Mapping > snapshot_data, std::shared_ptr< const fml::Mapping > snapshot_instructions)
Create an isolate snapshot from existing fml::Mappings.
static fml::RefPtr< const DartSnapshot > VMSnapshotFromSettings(const Settings &settings)
From the fields present in the given settings object, infer the core snapshot.