class Annotation

Defined at line 75 of file ../../third_party/crashpad/src/client/annotation.h

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

specifies how much data from the

value should be recorded.

Annotations should be declared with static storage duration.

An example declaration and usage:

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.

Code

                                    
                                           // 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);
                                           }

Public Members

static const size_t kNameMaxLength

static const size_t kValueMaxSize

Public Methods

Type UserDefinedType (uint16_t value)

Creates a user-defined Annotation::Type.

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

Parameters

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

Defined at line 121 of file ../../third_party/crashpad/src/client/annotation.h

void Annotation (Type type, const char[] name, void * value_ptr)

Constructs a new annotation.

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

reports until

Parameters

type [in] The data type of the value of the annotation.

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

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

Defined at line 152 of file ../../third_party/crashpad/src/client/annotation.h

void Annotation (const Annotation & )

Defined at line 158 of file ../../third_party/crashpad/src/client/annotation.h

void SetSize (ValueSizeType size)

Specifies the number of bytes in

to include when

generating a crash report.

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

equivalent of calling

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

size [in] The number of bytes.

void Clear ()

Marks the annotation as cleared, indicating the

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.

Annotation & operator= (const Annotation & )

Defined at line 159 of file ../../third_party/crashpad/src/client/annotation.h

bool is_set ()

Tests whether the annotation has been set.

Defined at line 184 of file ../../third_party/crashpad/src/client/annotation.h

Type type ()

Defined at line 186 of file ../../third_party/crashpad/src/client/annotation.h

ValueSizeType size ()

Defined at line 187 of file ../../third_party/crashpad/src/client/annotation.h

const char * name ()

Defined at line 188 of file ../../third_party/crashpad/src/client/annotation.h

const void * value ()

Defined at line 189 of file ../../third_party/crashpad/src/client/annotation.h

ConcurrentAccessGuardMode concurrent_access_guard_mode ()

Defined at line 191 of file ../../third_party/crashpad/src/client/annotation.h

std::optional<ScopedSpinGuard> TryCreateScopedSpinGuard (uint64_t timeout_ns)

If this Annotation guards concurrent access using ScopedSpinGuard,

tries to obtain the spin guard and returns the result.

Parameters

timeout_ns [in] The timeout in nanoseconds after which to give up trying to obtain the spin guard.

Returns

std::nullopt if the spin guard could not be obtained within

timeout_ns, or the obtained spin guard otherwise.

Defined at line 202 of file ../../third_party/crashpad/src/client/annotation.h

Protected Methods

void Annotation (Type type, const char[] name, void * value_ptr, ConcurrentAccessGuardMode concurrent_access_guard_mode)

Constructs a new annotation.

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

reports until

Parameters

type [in] The data type of the value of the annotation.

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

concurrent_access_guard_mode [in] Mode used to guard concurrent reads from writes.

Defined at line 231 of file ../../third_party/crashpad/src/client/annotation.h

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

Defined at line 248 of file ../../third_party/crashpad/src/client/annotation.h

Annotation * GetLinkNode (std::memory_order order)

Defined at line 250 of file ../../third_party/crashpad/src/client/annotation.h

const Annotation * GetLinkNode (std::memory_order order)

Defined at line 253 of file ../../third_party/crashpad/src/client/annotation.h

Enumerations

enum Type

Name	Value
kInvalid	0
kString	1
kUserDefinedStart	0x8000

The type of data stored in the annotation.

Defined at line 88 of file ../../third_party/crashpad/src/client/annotation.h

enum ConcurrentAccessGuardMode

Name	Value
kUnguarded	false
kScopedSpinGuard	true

Mode used to guard concurrent reads from writes.

Defined at line 101 of file ../../third_party/crashpad/src/client/annotation.h

Friends

class AnnotationList