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:

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.

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.

const uint8_t *	GetDataMapping () const
	Get a pointer to the read-only mapping to the heap snapshot.

const uint8_t *	GetInstructionsMapping () const
	Get a pointer to the read-execute mapping to the instructions snapshot.

bool	IsDontNeedSafe () const
	Returns whether both the data and instructions mappings are safe to use with madvise(DONTNEED).

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 DartSnapshot >	VMSnapshotFromSettings (const Settings &settings)
	From the fields present in the given settings object, infer the core snapshot.

static fml::RefPtr< const DartSnapshot >	IsolateSnapshotFromSettings (const Settings &settings)
	From the fields present in the given settings object, infer the isolate snapshot.

static fml::RefPtr< DartSnapshot >	IsolateSnapshotFromMappings (const std::shared_ptr< const fml::Mapping > &snapshot_data, const std::shared_ptr< const fml::Mapping > &snapshot_instructions)
	Create an isolate snapshot from existing fml::Mappings.

static fml::RefPtr< DartSnapshot >	VMServiceIsolateSnapshotFromSettings (const Settings &settings)
	Create an isolate snapshot specialized for launching the service isolate. Returns nullptr if no such snapshot is available.

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 41 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 250 of file dart_snapshot.cc.

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

Referenced by IsNullSafetyEnabled().

◆ 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 254 of file dart_snapshot.cc.

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

Referenced by IsNullSafetyEnabled().

◆ IsDontNeedSafe()

bool flutter::DartSnapshot::IsDontNeedSafe ( ) const

Returns whether both the data and instructions mappings are safe to use with madvise(DONTNEED).

Definition at line 258 of file dart_snapshot.cc.

                                        {
  if (data_ && !data_->IsDontNeedSafe()) {
    return false;
  }
  if (instructions_ && !instructions_->IsDontNeedSafe()) {
    return false;
  }
  return true;
}

◆ IsNullSafetyEnabled()

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

Definition at line 268 of file dart_snapshot.cc.

                                                                     {
  return ::Dart_DetectNullSafety(
      nullptr,           // script_uri (unsupported by Flutter)
      nullptr,           // package_config (package resolution of parent used)
      nullptr,           // original_working_directory (no package config)
      GetDataMapping(),  // snapshot_data
      GetInstructionsMapping(),                 // snapshot_instructions
      kernel ? kernel->GetMapping() : nullptr,  // kernel_buffer
      kernel ? kernel->GetSize() : 0u           // kernel_buffer_size
  );
}

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

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

◆ IsolateSnapshotFromMappings()

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

static

Create an isolate snapshot from existing fml::Mappings.

Parameters

[in]	snapshot_data	The mapping for the heap snapshot.
[in]	snapshot_instructions	The mapping for the instructions snapshot.

Returns: A valid isolate snapshot or nullptr.

Definition at line 205 of file dart_snapshot.cc.

                                                                  {
  auto snapshot =
      fml::MakeRefCounted<DartSnapshot>(snapshot_data, snapshot_instructions);
  if (snapshot->IsValid()) {
    return snapshot;
  }
  return nullptr;
  // NOLINTNEXTLINE(clang-analyzer-cplusplus.NewDeleteLeaks)
}

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

◆ 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] settings The settings to infer the isolate snapshot from.

Returns: A valid isolate snapshot or nullptr.

Definition at line 192 of file dart_snapshot.cc.

                              {
  TRACE_EVENT0("flutter", "DartSnapshot::IsolateSnapshotFromSettings");
  auto snapshot =
      fml::MakeRefCounted<DartSnapshot>(ResolveIsolateData(settings),         //
                                        ResolveIsolateInstructions(settings)  //
      );
  if (snapshot->IsValid()) {
    return snapshot;
  }
  return nullptr;
}

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

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

◆ 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 242 of file dart_snapshot.cc.

                                 {
  return static_cast<bool>(data_);
}

◆ 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 246 of file dart_snapshot.cc.

                                       {
  return data_ && instructions_;
}

◆ 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 217 of file dart_snapshot.cc.

                              {
#if DART_SNAPSHOT_STATIC_LINK
  return nullptr;
#else   // DART_SNAPSHOT_STATIC_LINK
  if (settings.vmservice_snapshot_library_path.empty()) {
    return nullptr;
  }
 
  std::shared_ptr<const fml::Mapping> snapshot_data =
      SearchMapping(nullptr, "", settings.vmservice_snapshot_library_path,
                    DartSnapshot::kIsolateDataSymbol, false);
  std::shared_ptr<const fml::Mapping> snapshot_instructions =
      SearchMapping(nullptr, "", settings.vmservice_snapshot_library_path,
                    DartSnapshot::kIsolateInstructionsSymbol, true);
  return IsolateSnapshotFromMappings(snapshot_data, snapshot_instructions);
#endif  // DART_SNAPSHOT_STATIC_LINK
}

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

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

◆ 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] settings The settings to infer the core snapshot from.

Returns: A valid core snapshot or nullptr.

Definition at line 179 of file dart_snapshot.cc.

                              {
  TRACE_EVENT0("flutter", "DartSnapshot::VMSnapshotFromSettings");
  auto snapshot =
      fml::MakeRefCounted<DartSnapshot>(ResolveVMData(settings),         //
                                        ResolveVMInstructions(settings)  //
      );
  if (snapshot->IsValid()) {
    return snapshot;
  }
  return nullptr;
}

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

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

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 57 of file dart_snapshot.h.

Referenced by flutter::LoadDartDeferredLibrary(), flutter::ResolveIsolateData(), and VMServiceIsolateSnapshotFromSettings().

◆ 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 62 of file dart_snapshot.h.

Referenced by flutter::LoadDartDeferredLibrary(), flutter::ResolveIsolateInstructions(), and VMServiceIsolateSnapshotFromSettings().

◆ 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 47 of file dart_snapshot.h.

Referenced by flutter::ResolveVMData().

◆ 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 52 of file dart_snapshot.h.

Referenced by flutter::ResolveVMInstructions().

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

runtime/dart_snapshot.h
runtime/dart_snapshot.cc

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ GetDataMapping()

◆ GetInstructionsMapping()

◆ IsDontNeedSafe()

◆ IsNullSafetyEnabled()

◆ IsolateSnapshotFromMappings()

◆ IsolateSnapshotFromSettings()

◆ IsValid()

◆ IsValidForAOT()

◆ VMServiceIsolateSnapshotFromSettings()

◆ VMSnapshotFromSettings()

Member Data Documentation

◆ kIsolateDataSymbol

◆ kIsolateInstructionsSymbol

◆ kVMDataSymbol

◆ kVMInstructionsSymbol