Crashpad

Public Member Functions | Protected Types | Protected Member Functions | Static Protected Attributes | List of all members
crashpad::internal::MinidumpWritable Class Referenceabstract

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 const size_t | kInvalidSize
| A size value used to signal failure by methods that return `size_t`. More...

## 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 in minidump files in accordance with expected access patterns: unlike most other data, memory snapshots are large and the entire snapshots do not need to be consulted 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 | ( |  | ) |
| protected virtual

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 | ( |  | ) |
| protected virtual

Returns the object’s children.

Note
  Valid in kStateFrozen or any subsequent state.

Reimplemented in crashpad::MinidumpModuleListWriter, crashpad::MinidumpModuleWriter, crashpad::MinidumpThreadListWriter, crashpad::MinidumpSystemInfoWriter, crashpad::MinidumpMemoryListWriter, crashpad::MinidumpModuleCrashpadInfoListWriter, crashpad::MinidumpUnloadedModuleListWriter, crashpad::MinidumpSimpleStringDictionaryWriter, crashpad::MinidumpThreadWriter, crashpad::MinidumpExceptionWriter, crashpad::MinidumpFileWriter, crashpad::MinidumpCrashpadInfoWriter, crashpad::MinidumpUnloadedModuleWriter, crashpad::MinidumpModuleCrashpadInfoWriter, crashpad::MinidumpSimpleStringDictionaryEntryWriter, crashpad::internal::MinidumpRVAListWriter, crashpad::MinidumpHandleDataWriter, crashpad::MinidumpMemoryInfoListWriter, and crashpad::MinidumpUserStreamWriter.

## ◆ Freeze()

bool crashpad::internal::MinidumpWritable::Freeze | ( |  | ) |
| protected virtual

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.

Reimplemented in crashpad::MinidumpModuleListWriter, crashpad::MinidumpModuleWriter, crashpad::MinidumpThreadListWriter, crashpad::MinidumpSystemInfoWriter, crashpad::MinidumpModuleMiscDebugRecordWriter, crashpad::MinidumpMemoryListWriter, crashpad::MinidumpModuleCrashpadInfoListWriter, crashpad::MinidumpUnloadedModuleListWriter, crashpad::MinidumpSimpleStringDictionaryWriter, crashpad::MinidumpThreadWriter, crashpad::MinidumpMiscInfoWriter, crashpad::MinidumpExceptionWriter, crashpad::MinidumpFileWriter, crashpad::MinidumpCrashpadInfoWriter, crashpad::MinidumpUnloadedModuleWriter, crashpad::MinidumpModuleCrashpadInfoWriter, crashpad::MinidumpSimpleStringDictionaryEntryWriter, crashpad::internal::MinidumpStringWriter< Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF16Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF8Traits >, crashpad::internal::MinidumpRVAListWriter, crashpad::MinidumpHandleDataWriter, crashpad::MinidumpMemoryInfoListWriter, crashpad::internal::MinidumpStreamWriter, and crashpad::MinidumpUserStreamWriter.

## ◆ 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 | ( |  | ) |
| protected pure 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.

Implemented in crashpad::MinidumpModuleListWriter, crashpad::MinidumpModuleWriter, crashpad::test::TestUInt32MinidumpWritable, crashpad::MinidumpThreadListWriter, crashpad::MinidumpSystemInfoWriter, crashpad::MinidumpModuleMiscDebugRecordWriter, crashpad::MinidumpMemoryListWriter, crashpad::MinidumpModuleCrashpadInfoListWriter, crashpad::MinidumpUnloadedModuleListWriter, crashpad::MinidumpSimpleStringDictionaryWriter, crashpad::MinidumpThreadWriter, crashpad::MinidumpMiscInfoWriter, crashpad::MinidumpExceptionWriter, crashpad::MinidumpFileWriter, crashpad::MinidumpCrashpadInfoWriter, crashpad::MinidumpUnloadedModuleWriter, crashpad::MinidumpModuleCrashpadInfoWriter, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordType >, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordPDB20 >, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordPDB70 >, crashpad::MinidumpSimpleStringDictionaryEntryWriter, crashpad::internal::MinidumpStringWriter< Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF16Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF8Traits >, crashpad::internal::MinidumpRVAListWriter, crashpad::MinidumpContextWriter, crashpad::MinidumpHandleDataWriter, crashpad::MinidumpMemoryInfoListWriter, and crashpad::MinidumpUserStreamWriter.

## ◆ 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 | ) |
| protected virtual

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 | ) |
| protected pure 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.

Implemented in crashpad::MinidumpModuleListWriter, crashpad::MinidumpModuleWriter, crashpad::test::TestUInt32MinidumpWritable, crashpad::MinidumpThreadListWriter, crashpad::MinidumpSystemInfoWriter, crashpad::MinidumpModuleMiscDebugRecordWriter, crashpad::MinidumpMemoryListWriter, crashpad::MinidumpModuleCrashpadInfoListWriter, crashpad::MinidumpUnloadedModuleListWriter, crashpad::MinidumpContextAMD64Writer, crashpad::MinidumpSimpleStringDictionaryWriter, crashpad::MinidumpThreadWriter, crashpad::MinidumpMiscInfoWriter, crashpad::MinidumpExceptionWriter, crashpad::MinidumpFileWriter, crashpad::MinidumpCrashpadInfoWriter, crashpad::MinidumpContextX86Writer, crashpad::MinidumpUnloadedModuleWriter, crashpad::MinidumpModuleCrashpadInfoWriter, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordType >, crashpad::MinidumpSimpleStringDictionaryEntryWriter, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordPDB20 >, crashpad::internal::MinidumpModuleCodeViewRecordPDBLinkWriter< CodeViewRecordPDB70 >, crashpad::internal::MinidumpStringWriter< Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF16Traits >, crashpad::internal::MinidumpStringWriter< MinidumpStringWriterUTF8Traits >, crashpad::internal::MinidumpRVAListWriter, crashpad::MinidumpHandleDataWriter, crashpad::MinidumpMemoryInfoListWriter, and crashpad::MinidumpUserStreamWriter.

## ◆ 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 | ( |  | ) |
| protected virtual

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.

## Member Data Documentation

## ◆ kInvalidSize

const size_t crashpad::internal::MinidumpWritable::kInvalidSize
| static protected

Initial value:
=
std::numeric_limits<size_t>::max()

A size value used to signal failure by methods that return `size_t`.

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

- minidump/minidump_writable.h
- minidump/minidump_writable.cc