Flutter Engine
flutter::DartSnapshot Class Reference

A read-only Dart heap snapshot, or, read-executable mapping of AOT compiled Dart code. More...

#include <dart_snapshot.h>

Inheritance diagram for flutter::DartSnapshot:
fml::RefCountedThreadSafe< DartSnapshot > fml::internal::RefCountedThreadSafeBase

Public Member Functions

bool IsValid () const
 Determines if this snapshot contains a heap component. Since the instructions component is optional, the method does not check for its presence. Use IsValidForAOT to determine if both the heap and instructions components of the snapshot are present. More...
 
bool IsValidForAOT () const
 Determines if this snapshot contains both the heap and instructions components. This is only useful when determining if the snapshot may be used to run AOT code. The instructions component will be absent in JIT modes. More...
 
const uint8_t * GetDataMapping () const
 Get a pointer to the read-only mapping to the heap snapshot. More...
 
const uint8_t * GetInstructionsMapping () const
 Get a pointer to the read-execute mapping to the instructions snapshot. More...
 
bool IsNullSafetyEnabled (const fml::Mapping *application_kernel_mapping) const
 
- Public Member Functions inherited from fml::RefCountedThreadSafe< DartSnapshot >
void Release () const
 
- Public Member Functions inherited from fml::internal::RefCountedThreadSafeBase
void AddRef () const
 
bool HasOneRef () const
 
void AssertHasOneRef () const
 

Static Public Member Functions

static fml::RefPtr< const DartSnapshotVMSnapshotFromSettings (const Settings &settings)
 From the fields present in the given settings object, infer the core snapshot. More...
 
static fml::RefPtr< const DartSnapshotIsolateSnapshotFromSettings (const Settings &settings)
 From the fields present in the given settings object, infer the isolate snapshot. More...
 
static fml::RefPtr< DartSnapshotIsolateSnapshotFromMappings (std::shared_ptr< const fml::Mapping > snapshot_data, std::shared_ptr< const fml::Mapping > snapshot_instructions)
 Create an isolate snapshot from existing fml::Mappings. More...
 
static fml::RefPtr< DartSnapshotVMServiceIsolateSnapshotFromSettings (const Settings &settings)
 Create an isolate snapshot specialized for launching the service isolate. Returns nullptr if no such snapshot is available. More...
 

Static Public Attributes

static const char * kVMDataSymbol = "kDartVmSnapshotData"
 
static const char * kVMInstructionsSymbol = "kDartVmSnapshotInstructions"
 
static const char * kIsolateDataSymbol = "kDartIsolateSnapshotData"
 
static const char * kIsolateInstructionsSymbol
 

Additional Inherited Members

- Protected Member Functions inherited from fml::RefCountedThreadSafe< DartSnapshot >
 RefCountedThreadSafe ()
 
 ~RefCountedThreadSafe ()
 
- Protected Member Functions inherited from fml::internal::RefCountedThreadSafeBase
 RefCountedThreadSafeBase ()
 
 ~RefCountedThreadSafeBase ()
 
bool Release () const
 
void Adopt ()
 

Detailed Description

A read-only Dart heap snapshot, or, read-executable mapping of AOT compiled Dart code.

To make Dart code startup more performant, the Flutter tools on the host snapshot the state of the Dart heap at specific points and package the same with the Flutter application. When the Dart VM on the target is configured to run AOT compiled Dart code, the tools also compile the developer's Flutter application code to target specific machine code (instructions). This class deals with the mapping of both these buffers at runtime on the target.

A Flutter application typically needs two instances of this class at runtime to run Dart code. One instance is for the VM and is called the "core snapshot". The other is the isolate and called the "isolate snapshot". Different root isolates can be launched with different isolate snapshots.

These snapshots are typically memory-mapped at runtime, or, referenced directly as symbols present in Mach or ELF binaries.

In the case of the core snapshot, the snapshot is collected when the VM shuts down. The isolate snapshot is collected when the isolate group shuts down.

Definition at line 42 of file dart_snapshot.h.

Member Function Documentation

◆ GetDataMapping()

const uint8_t * flutter::DartSnapshot::GetDataMapping ( ) const

Get a pointer to the read-only mapping to the heap snapshot.

Returns
The data mapping.

Definition at line 228 of file dart_snapshot.cc.

Referenced by IsNullSafetyEnabled().

228  {
229  return data_ ? data_->GetMapping() : nullptr;
230 }

◆ GetInstructionsMapping()

const uint8_t * flutter::DartSnapshot::GetInstructionsMapping ( ) const

Get a pointer to the read-execute mapping to the instructions snapshot.

Returns
The instructions mapping.

Definition at line 232 of file dart_snapshot.cc.

Referenced by IsNullSafetyEnabled().

232  {
233  return instructions_ ? instructions_->GetMapping() : nullptr;
234 }

◆ IsNullSafetyEnabled()

bool flutter::DartSnapshot::IsNullSafetyEnabled ( const fml::Mapping application_kernel_mapping) const

Definition at line 236 of file dart_snapshot.cc.

References GetDataMapping(), GetInstructionsMapping(), fml::Mapping::GetMapping(), and fml::Mapping::GetSize().

Referenced by flutter::AppSnapshotIsolateConfiguration::IsNullSafetyEnabled(), flutter::KernelIsolateConfiguration::IsNullSafetyEnabled(), and flutter::KernelListIsolateConfiguration::IsNullSafetyEnabled().

236  {
237  return ::Dart_DetectNullSafety(
238  nullptr, // script_uri (unsupported by Flutter)
239  nullptr, // package_config (package resolution of parent used)
240  nullptr, // original_working_directory (no package config)
241  GetDataMapping(), // snapshot_data
242  GetInstructionsMapping(), // snapshot_instructions
243  kernel ? kernel->GetMapping() : nullptr, // kernel_buffer
244  kernel ? kernel->GetSize() : 0u // kernel_buffer_size
245  );
246 }
const uint8_t * GetInstructionsMapping() const
Get a pointer to the read-execute mapping to the instructions snapshot.
const uint8_t * GetDataMapping() const
Get a pointer to the read-only mapping to the heap snapshot.

◆ IsolateSnapshotFromMappings()

fml::RefPtr< DartSnapshot > flutter::DartSnapshot::IsolateSnapshotFromMappings ( std::shared_ptr< const fml::Mapping snapshot_data,
std::shared_ptr< const fml::Mapping snapshot_instructions 
)
static

Create an isolate snapshot from existing fml::Mappings.

Parameters
[in]snapshot_dataThe mapping for the heap snapshot.
[in]snapshot_instructionsThe mapping for the instructions snapshot.
Returns
A valid isolate snapshot or nullptr.

Definition at line 184 of file dart_snapshot.cc.

Referenced by flutter::DartIsolate::LoadLoadingUnit(), and VMServiceIsolateSnapshotFromSettings().

186  {
187  auto snapshot =
188  fml::MakeRefCounted<DartSnapshot>(snapshot_data, snapshot_instructions);
189  if (snapshot->IsValid()) {
190  return snapshot;
191  }
192  return nullptr;
193 }

◆ IsolateSnapshotFromSettings()

fml::RefPtr< const DartSnapshot > flutter::DartSnapshot::IsolateSnapshotFromSettings ( const Settings settings)
static

From the fields present in the given settings object, infer the isolate snapshot.

Attention
Depending on the runtime mode of the Flutter application and the target that Flutter is running on, a complex fallback mechanism is in place to infer the locations of each snapshot buffer. If the caller wants to explicitly specify the buffers of the isolate snapshot, the Settings::isolate_snapshot_data and Settings::isolate_snapshots_instr mapping fields may be used. This specification takes precedence over all fallback search paths.
Parameters
[in]settingsThe settings to infer the isolate snapshot from.
Returns
A valid isolate snapshot or nullptr.

Definition at line 171 of file dart_snapshot.cc.

References flutter::ResolveIsolateData(), flutter::ResolveIsolateInstructions(), and TRACE_EVENT0.

Referenced by flutter::DartVMData::Create(), and flutter::Shell::Create().

172  {
173  TRACE_EVENT0("flutter", "DartSnapshot::IsolateSnapshotFromSettings");
174  auto snapshot =
175  fml::MakeRefCounted<DartSnapshot>(ResolveIsolateData(settings), //
176  ResolveIsolateInstructions(settings) //
177  );
178  if (snapshot->IsValid()) {
179  return snapshot;
180  }
181  return nullptr;
182 }
#define TRACE_EVENT0(category_group, name)
Definition: trace_event.h:90
static std::shared_ptr< const fml::Mapping > ResolveIsolateInstructions(const Settings &settings)
static std::shared_ptr< const fml::Mapping > ResolveIsolateData(const Settings &settings)

◆ IsValid()

bool flutter::DartSnapshot::IsValid ( ) const

Determines if this snapshot contains a heap component. Since the instructions component is optional, the method does not check for its presence. Use IsValidForAOT to determine if both the heap and instructions components of the snapshot are present.

Returns
Returns if the snapshot contains a heap component.

Definition at line 220 of file dart_snapshot.cc.

220  {
221  return static_cast<bool>(data_);
222 }

◆ IsValidForAOT()

bool flutter::DartSnapshot::IsValidForAOT ( ) const

Determines if this snapshot contains both the heap and instructions components. This is only useful when determining if the snapshot may be used to run AOT code. The instructions component will be absent in JIT modes.

Returns
Returns if the snapshot contains both a heap and instructions component.

Definition at line 224 of file dart_snapshot.cc.

224  {
225  return data_ && instructions_;
226 }

◆ VMServiceIsolateSnapshotFromSettings()

fml::RefPtr< DartSnapshot > flutter::DartSnapshot::VMServiceIsolateSnapshotFromSettings ( const Settings settings)
static

Create an isolate snapshot specialized for launching the service isolate. Returns nullptr if no such snapshot is available.

Returns
A valid isolate snapshot or nullptr.

Definition at line 195 of file dart_snapshot.cc.

References flutter::data, IsolateSnapshotFromMappings(), flutter::SearchMapping(), and flutter::Settings::vmservice_snapshot_library_path.

Referenced by flutter::DartVMData::Create().

196  {
197 #if DART_SNAPSHOT_STATIC_LINK
198  return nullptr;
199 #else // DART_SNAPSHOT_STATIC_LINK
200  if (settings.vmservice_snapshot_library_path.empty()) {
201  return nullptr;
202  }
203 
204  std::shared_ptr<const fml::Mapping> snapshot_data =
205  SearchMapping(nullptr, "", settings.vmservice_snapshot_library_path,
207  std::shared_ptr<const fml::Mapping> snapshot_instructions =
208  SearchMapping(nullptr, "", settings.vmservice_snapshot_library_path,
210  return IsolateSnapshotFromMappings(snapshot_data, snapshot_instructions);
211 #endif // DART_SNAPSHOT_STATIC_LINK
212 }
static std::shared_ptr< const fml::Mapping > SearchMapping(MappingCallback embedder_mapping_callback, const std::string &file_path, const std::vector< std::string > &native_library_path, const char *native_library_symbol_name, bool is_executable)
static const char * kIsolateDataSymbol
Definition: dart_snapshot.h:58
static const char * kIsolateInstructionsSymbol
Definition: dart_snapshot.h:63
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.

◆ VMSnapshotFromSettings()

fml::RefPtr< const DartSnapshot > flutter::DartSnapshot::VMSnapshotFromSettings ( const Settings settings)
static

From the fields present in the given settings object, infer the core snapshot.

Attention
Depending on the runtime mode of the Flutter application and the target that Flutter is running on, a complex fallback mechanism is in place to infer the locations of each snapshot buffer. If the caller wants to explicitly specify the buffers of the core snapshot, the Settings::vm_snapshot_data and Settings::vm_snapshots_instr mapping fields may be used. This specification takes precedence over all fallback search paths.
Parameters
[in]settingsThe settings to infer the core snapshot from.
Returns
A valid core snapshot or nullptr.

Definition at line 158 of file dart_snapshot.cc.

References flutter::ResolveVMData(), flutter::ResolveVMInstructions(), and TRACE_EVENT0.

Referenced by flutter::DartVMData::Create(), and flutter::Shell::Create().

159  {
160  TRACE_EVENT0("flutter", "DartSnapshot::VMSnapshotFromSettings");
161  auto snapshot =
162  fml::MakeRefCounted<DartSnapshot>(ResolveVMData(settings), //
163  ResolveVMInstructions(settings) //
164  );
165  if (snapshot->IsValid()) {
166  return snapshot;
167  }
168  return nullptr;
169 }
static std::shared_ptr< const fml::Mapping > ResolveVMInstructions(const Settings &settings)
#define TRACE_EVENT0(category_group, name)
Definition: trace_event.h:90
static std::shared_ptr< const fml::Mapping > ResolveVMData(const Settings &settings)

Member Data Documentation

◆ kIsolateDataSymbol

const char * flutter::DartSnapshot::kIsolateDataSymbol = "kDartIsolateSnapshotData"
static

The symbol name of the heap data of the isolate snapshot in a dynamic library or currently loaded process.

Definition at line 58 of file dart_snapshot.h.

Referenced by flutter::LoadDartDeferredLibrary().

◆ kIsolateInstructionsSymbol

const char * flutter::DartSnapshot::kIsolateInstructionsSymbol
static
Initial value:
=
"kDartIsolateSnapshotInstructions"

The symbol name of the instructions data of the isolate snapshot in a dynamic library or currently loaded process.

Definition at line 63 of file dart_snapshot.h.

Referenced by flutter::LoadDartDeferredLibrary().

◆ kVMDataSymbol

const char * flutter::DartSnapshot::kVMDataSymbol = "kDartVmSnapshotData"
static

The symbol name of the heap data of the core snapshot in a dynamic library or currently loaded process.

Definition at line 48 of file dart_snapshot.h.

◆ kVMInstructionsSymbol

const char * flutter::DartSnapshot::kVMInstructionsSymbol = "kDartVmSnapshotInstructions"
static

The symbol name of the instructions data of the core snapshot in a dynamic library or currently loaded process.

Definition at line 53 of file dart_snapshot.h.


The documentation for this class was generated from the following files: