The base class for all content that might be written to a minidump file. More...

#include "minidump/minidump_writable.h"

Inheritance diagram for crashpad::internal::MinidumpWritable:

Public Member Functions
virtual bool	WriteEverything (FileWriterInterface *file_writer)
	Writes an object and all of its children to a minidump file. More...

void	RegisterRVA (RVA *rva)
	Registers a file offset pointer as one that should point to the object on which this method is called. More...

void	RegisterLocationDescriptor (MINIDUMP_LOCATION_DESCRIPTOR *location_descriptor)
	Registers a location descriptor as one that should point to the object on which this method is called. More...

Protected Types
enum	State
	Identifies the state of an object. More...

enum	Phase
	Identifies the phase during which an object will be written to a minidump file. More...

Protected Member Functions
State	state () const
	The state of the object.

virtual bool	Freeze ()
	Transitions the object from kStateMutable to kStateFrozen. More...

virtual size_t	SizeOfObject ()=0
	Returns the amount of space that this object will consume when written to a minidump file, in bytes, not including any leading or trailing padding necessary to maintain proper alignment. More...

virtual size_t	Alignment ()
	Returns the object’s desired byte-boundary alignment. More...

virtual std::vector< MinidumpWritable * >	Children ()
	Returns the object’s children. More...

virtual Phase	WritePhase ()
	Returns the object’s desired write phase. More...

size_t	WillWriteAtOffset (Phase phase, FileOffset offset, std::vector< MinidumpWritable > *write_sequence)
	Prepares the object to be written at a known file offset, transitioning it from kStateFrozen to kStateWritable. More...

virtual bool	WillWriteAtOffsetImpl (FileOffset offset)
	Called once an object’s writable file offset is determined, as it transitions into kStateWritable. More...

bool	WritePaddingAndObject (FileWriterInterface *file_writer)
	Writes the object, transitioning it from kStateWritable to kStateWritten. More...

virtual bool	WriteObject (FileWriterInterface *file_writer)=0
	Writes the object’s content. More...

Static Protected Attributes
static constexpr size_t	kInvalidSize = std::numeric_limits<size_t>::max()
	A size value used to signal failure by methods that return `size_t`.

Detailed Description

The base class for all content that might be written to a minidump file.

Member Enumeration Documentation

◆ Phase

enum crashpad::internal::MinidumpWritable::Phase

protected

Identifies the phase during which an object will be written to a minidump file.

Enumerator

kPhaseEarly

Objects that are written to a minidump file “early”.

The normal sequence is for an object to write itself and then write all
of its children.

kPhaseLate

Objects that are written to a minidump file “late”.

Some objects, such as those capturing memory region snapshots, are
written to minidump files after all other objects. This “late” phase
identifies such objects. This is useful to improve spatial locality in
minidump files in accordance with expected access patterns: unlike most
other data, memory snapshots are large and do not usually need to be
consulted in their entirety in order to process a minidump file.

◆ State

enum crashpad::internal::MinidumpWritable::State

protected

Identifies the state of an object.

Objects will normally transition through each of these states as they are created, populated with data, and then written to a minidump file.

Enumerator
kStateMutable	The object’s properties can be modified.
kStateFrozen	The object is “frozen”. Its properties cannot be modified. Pointers to file offsets of other structures may not yet be valid.
kStateWritable	The object is writable. The file offset at which it will be written is known. Pointers to file offsets of other structures are valid when all objects in a tree are in this state.
kStateWritten	The object has been written to a minidump file.

Member Function Documentation

◆ Alignment()

size_t crashpad::internal::MinidumpWritable::Alignment ( )

protectedvirtual

Returns the object’s desired byte-boundary alignment.

The default implementation returns 4. Subclasses may override this as needed.

Note: Valid in kStateFrozen or any subsequent state.

Reimplemented in crashpad::MinidumpContextAMD64Writer.

◆ Children()

std::vector< MinidumpWritable * > crashpad::internal::MinidumpWritable::Children ( )

protectedvirtual

Returns the object’s children.

Note: Valid in kStateFrozen or any subsequent state.

◆ Freeze()

bool crashpad::internal::MinidumpWritable::Freeze ( )

protectedvirtual

Transitions the object from kStateMutable to kStateFrozen.

The default implementation marks the object as frozen and recursively calls Freeze() on all of its children. Subclasses may override this method to perform processing that should only be done once callers have finished populating an object with data. Typically, a subclass implementation would call RegisterRVA() or RegisterLocationDescriptor() on other objects as appropriate, because at the time Freeze() runs, the in-memory locations of RVAs and location descriptors are known and will not change for the remaining duration of an object’s lifetime.

Returns: true on success. false on failure, with an appropriate message logged.

◆ RegisterLocationDescriptor()

void crashpad::internal::MinidumpWritable::RegisterLocationDescriptor ( MINIDUMP_LOCATION_DESCRIPTOR * location_descriptor )

Registers a location descriptor as one that should point to the object on which this method is called.

Once an object’s size and the file offset at it will be written is known (when it enters kStateFrozen), the relevant data in registered location descriptors will be updated.

Parameters

[in] location_descriptor A pointer to a location descriptor that should contain this object’s writable size and file offset, once they are known.

Note: Valid in kStateFrozen or any preceding state.

◆ RegisterRVA()

void crashpad::internal::MinidumpWritable::RegisterRVA ( RVA * rva )

Registers a file offset pointer as one that should point to the object on which this method is called.

Once the file offset at which an object will be written is known (when it enters kStateWritable), registered RVA pointers will be updated.

Parameters

[in] rva A pointer to storage for the file offset that should contain this object’s writable file offset, once it is known.

Note: Valid in kStateFrozen or any preceding state.

◆ SizeOfObject()

virtual size_t crashpad::internal::MinidumpWritable::SizeOfObject ( )

protectedpure virtual

Returns the amount of space that this object will consume when written to a minidump file, in bytes, not including any leading or trailing padding necessary to maintain proper alignment.

Note: Valid in kStateFrozen or any subsequent state.

◆ WillWriteAtOffset()

size_t crashpad::internal::MinidumpWritable::WillWriteAtOffset	(	Phase	phase,
		FileOffset *	offset,
		std::vector< MinidumpWritable * > *	write_sequence
	)

protected

Prepares the object to be written at a known file offset, transitioning it from kStateFrozen to kStateWritable.

This method is responsible for determining the final file offset of the object, which may be increased from offset to meet alignment requirements. It calls WillWriteAtOffsetImpl() for the benefit of subclasses. It populates all RVAs and location descriptors registered with it via RegisterRVA() and RegisterLocationDescriptor(). It also recurses into all known children.

Parameters

[in]	phase	The phase during which the object will be written. If this does not match Phase(), processing is suppressed, although recursive processing will still occur on all children. This addresses the case where parents and children do not write in the same phase.
[in]	offset	The file offset at which the object will be written. The offset may need to be adjusted for alignment.
[out]	write_sequence	This object will append itself to this list, such that on return from a recursive tree of WillWriteAtOffset() calls, elements of the vector will be organized in the sequence that the objects will be written to the minidump file.

Returns: The file size consumed by this object and all children, including any padding inserted to meet alignment requirements. On failure, kInvalidSize, with an appropriate message logged.

Note: This method cannot be overridden. Subclasses that need to perform processing when an object transitions to kStateWritable should implement WillWriteAtOffsetImpl(), which is called by this method.

◆ WillWriteAtOffsetImpl()

bool crashpad::internal::MinidumpWritable::WillWriteAtOffsetImpl ( FileOffset offset )

protectedvirtual

Called once an object’s writable file offset is determined, as it transitions into kStateWritable.

Subclasses can override this method if they need to provide additional processing once their writable file offset is known. Typically, this will be done by subclasses that handle certain RVAs themselves instead of using the RegisterRVA() interface.

Parameters

[in] offset The file offset at which the object will be written. The value passed to this method will already have been adjusted to meet alignment requirements.

Returns: true on success. false on error, indicating that the minidump file should not be written.

Note: Valid in kStateFrozen. The object will transition to kStateWritable after this method returns.

Reimplemented in crashpad::MinidumpFileWriter.

◆ WriteEverything()

bool crashpad::internal::MinidumpWritable::WriteEverything ( FileWriterInterface * file_writer )

virtual

Writes an object and all of its children to a minidump file.

Use this on the root object of a tree of MinidumpWritable objects, typically on a MinidumpFileWriter object.

Parameters

[in] file_writer The file writer to receive the minidump file’s content.

Returns: true on success. false on failure, with an appropriate message logged.

Note: Valid in kStateMutable, and transitions the object and the entire tree beneath it through all states to kStateWritten.; This method should rarely be overridden.

Reimplemented in crashpad::MinidumpFileWriter.

◆ WriteObject()

virtual bool crashpad::internal::MinidumpWritable::WriteObject ( FileWriterInterface * file_writer )

protectedpure virtual

Writes the object’s content.

Parameters

[in] file_writer The file writer to receive the object’s content.

Returns: true on success. false on error, indicating that the content could not be written to the minidump file.

Note: Valid in kStateWritable. The object will transition to kStateWritten after this method returns.

◆ WritePaddingAndObject()

bool crashpad::internal::MinidumpWritable::WritePaddingAndObject ( FileWriterInterface * file_writer )

protected

Writes the object, transitioning it from kStateWritable to kStateWritten.

Writes any padding necessary to meet alignment requirements, and then calls WriteObject() to write the object’s content.

Parameters

[in] file_writer The file writer to receive the object’s content.

Returns: true on success. false on error with an appropriate message logged.

Note: This method cannot be overridden. Subclasses must override WriteObject().

◆ WritePhase()

MinidumpWritable::Phase crashpad::internal::MinidumpWritable::WritePhase ( )

protectedvirtual

Returns the object’s desired write phase.

The default implementation returns kPhaseEarly. Subclasses may override this method to alter their write phase.

Note: Valid in any state.

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

minidump/minidump_writable.h
minidump/minidump_writable.cc

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Phase

◆ State

Member Function Documentation

◆ Alignment()

◆ Children()

◆ Freeze()

◆ RegisterLocationDescriptor()

◆ RegisterRVA()

◆ SizeOfObject()

◆ WillWriteAtOffset()

◆ WillWriteAtOffsetImpl()

◆ WriteEverything()

◆ WriteObject()

◆ WritePaddingAndObject()

◆ WritePhase()