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
15namespace 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///
42class 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