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 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  bool IsNullSafetyEnabled(
143  const fml::Mapping* application_kernel_mapping) const;
144 
145  private:
146  std::shared_ptr<const fml::Mapping> data_;
147  std::shared_ptr<const fml::Mapping> instructions_;
148 
149  DartSnapshot(std::shared_ptr<const fml::Mapping> data,
150  std::shared_ptr<const fml::Mapping> instructions);
151 
152  ~DartSnapshot();
153 
154  FML_FRIEND_REF_COUNTED_THREAD_SAFE(DartSnapshot);
155  FML_FRIEND_MAKE_REF_COUNTED(DartSnapshot);
156  FML_DISALLOW_COPY_AND_ASSIGN(DartSnapshot);
157 };
158 
159 } // namespace flutter
160 
161 #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< 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
static fml::RefPtr< DartSnapshot > VMSnapshotFromSettings(const Settings &settings)
From the fields present in the given settings object, infer the core snapshot.
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