crashpad::Annotation Class Reference

Base class for an annotation, which records a name-value pair of arbitrary data when set. More...

`#include "client/annotation.h"`

Inheritance diagram for crashpad::Annotation:

## Public Types

enum | Type : uint16_t
| The type of data stored in the annotation. More...
using | ValueSizeType = uint32_t
| The type used for SetSize().

## Public Member Functions

constexpr | Annotation (Type type, const char name[], void *const value_ptr)
| Constructs a new annotation. More...
void | SetSize (ValueSizeType size)
| Specifies the number of bytes in value_ptr_ to include when generating a crash report. More...
void | Clear ()
| Marks the annotation as cleared, indicating the value_ptr_ should not be included in a crash report. More...
bool | is_set () const
| Tests whether the annotation has been set.
Type | type () const
ValueSizeType | size () const
const char * | name () const
const void * | value () const

## Static Public Member Functions

static constexpr Type | UserDefinedType (uint16_t value)
| Creates a user-defined Annotation::Type. More...

## Static Public Attributes

static constexpr size_t | kNameMaxLength = 64
| The maximum length of an annotation’s name, in bytes.
static constexpr size_t | kValueMaxSize = 5 * 4096
| The maximum size of an annotation’s value, in bytes.

## Protected Member Functions

std::atomic< Annotation * > & | link_node ()

## Friends

class | AnnotationList

## Detailed Description

Base class for an annotation, which records a name-value pair of arbitrary data when set.

After an annotation is declared, its `value_ptr_` will not be captured in a crash report until a call to SetSize() specifies how much data from the value should be recorded.

Annotations should be declared with static storage duration.

An example declaration and usage:

// foo.cc:
namespace {
char g_buffer[1024];
crashpad::Annotation g_buffer_annotation(
crashpad::Annotation::Type::kString, "buffer_head", g_buffer);
} // namespace
void OnBufferProduced(size_t n) {
// Capture the head of the buffer, in case we crash when parsing it.
g_buffer_annotation.SetSize(std::min(64, n));
// Start parsing the header.
Frobinate(g_buffer, n);
}

Annotation objects are not inherently thread-safe. To manipulate them from multiple threads, external synchronization must be used.

Annotation objects should never be destroyed. Once they are Set(), they are permanently referenced by a global object.

## Member Enumeration Documentation

## Type

enum crashpad::Annotation::Type : uint16_t

strong

The type of data stored in the annotation.

Enumerator
kInvalid | An invalid annotation. Reserved for internal use.
kString | A `NUL`-terminated C-string.
kUserDefinedStart | Clients may declare their own custom types by using values greater than this.

## Constructor & Destructor Documentation

## Annotation()

constexpr crashpad::Annotation::Annotation | ( | Type | type,
|  | const char | name[],
|  | void *const | value_ptr
| ) |  |

inline

Constructs a new annotation.

Upon construction, the annotation will not be included in any crash reports until

See also
  SetSize() is called with a value greater than `0`.

Parameters

  [in] | type | The data type of the value of the annotation.
  [in] | name | A `NUL`-terminated C-string name for the annotation. Names do not have to be unique, though not all crash processors may handle Annotations with the same name. Names should be constexpr data with static storage duration.
  [in] | value_ptr | A pointer to the value for the annotation. The pointer may not be changed once associated with an annotation, but the data may be mutated.

## Member Function Documentation

## Clear()

void crashpad::Annotation::Clear | ( |  | ) |

Marks the annotation as cleared, indicating the value_ptr_ should not be included in a crash report.

This method does not mutate the data referenced by the annotation, it merely updates the annotation system's bookkeeping.

## SetSize()

void crashpad::Annotation::SetSize | ( | ValueSizeType | size | ) |

Specifies the number of bytes in value_ptr_ to include when generating a crash report.

A size of `0` indicates that no value should be recorded and is the equivalent of calling

See also
  Clear().

This method does not mutate the data referenced by the annotation, it merely updates the annotation system's bookkeeping.

Subclasses of this base class that provide additional Set methods to mutate the value of the annotation must call always call this method.

Parameters

  [in] | size | The number of bytes.

## UserDefinedType()

static constexpr Type crashpad::Annotation::UserDefinedType | ( | uint16_t | value | ) |

inlinestatic

Creates a user-defined Annotation::Type.

This exists to remove the casting overhead of `enum class`.

Parameters

  [in] | value | A value used to create a user-defined type.

Returns
  The value added to Type::kUserDefinedStart and casted.

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

- client/annotation.h
- client/annotation.cc