class MinidumpWritable

Defined at line 35 of file ../../third_party/crashpad/src/minidump/minidump_writable.h

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

file.

Protected Members

static const size_t kInvalidSize

Public Methods

void MinidumpWritable (const MinidumpWritable & )

Defined at line 37 of file ../../third_party/crashpad/src/minidump/minidump_writable.h

MinidumpWritable & operator= (const MinidumpWritable & )

Defined at line 38 of file ../../third_party/crashpad/src/minidump/minidump_writable.h

void ~MinidumpWritable ()

bool WriteEverything (FileWriterInterface * file_writer)

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

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

Returns

`true` on success. `false` on failure, with an appropriate message

logged.

void 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.

This is public instead of protected because objects of derived classes need

to be able to register their own pointers with distinct objects.

Parameters

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

void RegisterRVA (RVA64 * rva)

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.

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.

This is public instead of protected because objects of derived classes need

to be able to register their own pointers with distinct objects.

Parameters

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

void RegisterLocationDescriptor (MINIDUMP_LOCATION_DESCRIPTOR64 * location_descriptor64)

Protected Methods

void MinidumpWritable ()

bool Freeze ()

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.

size_t SizeOfObject ()

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.

size_t Alignment ()

Returns the object’s desired byte-boundary alignment.

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

needed.

std::vector<MinidumpWritable *> Children ()

Returns the object’s children.

Phase WritePhase ()

Returns the object’s desired write phase.

The default implementation returns #kPhaseEarly. Subclasses may override

this method to alter their write phase.

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.

This method is responsible for determining the final file offset of the

object, which may be increased from

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

phase [in] The phase during which the object will be written. Ifthis does not match Phase(), processing is suppressed, althoughrecursive processing will still occur on all children. This addressesthe case where parents and children do not write in the same phase.

offset [in] The file offset at which the object will be written. Theoffset may need to be adjusted for alignment.

write_sequence [out] 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 thatthe 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.

bool WillWriteAtOffsetImpl (FileOffset offset)

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

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

Returns

`true` on success. `false` on error, indicating that the minidump

file should not be written.

bool WritePaddingAndObject (FileWriterInterface * file_writer)

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

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

Returns

`true` on success. `false` on error with an appropriate message

logged.

bool WriteObject (FileWriterInterface * file_writer)

Writes the object’s content.

Parameters

file_writer [in] 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.

State state ()

The state of the object.

Defined at line 148 of file ../../third_party/crashpad/src/minidump/minidump_writable.h

Enumerations

enum State

Name	Value	Comments
kStateMutable	0	The object’s properties can be modified.
kStateFrozen	1	The object is “frozen”. Its properties cannot be modified. Pointers to file offsets of other structures may not yet be valid.
kStateWritable	2	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	3	The object has been written to a minidump file.

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.

Defined at line 100 of file ../../third_party/crashpad/src/minidump/minidump_writable.h

enum Phase

Name	Value	Comments
kPhaseEarly	0	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	1	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.

Name

Value

Comments

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.

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

minidump file.

Defined at line 123 of file ../../third_party/crashpad/src/minidump/minidump_writable.h