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
constexpr static 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  )

inlineconstexpr

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

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

inlinestaticconstexpr

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