class Annotation

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. Namesdo not have to be unique, though not all crash processors may handleAnnotations with the same name. Names should be constexpr data withstatic storage duration.
value_ptr [in] A pointer to the value for the annotation. Thepointer may not be changed once associated with an annotation, butthe 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 uptrying 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.
name [in] A `NUL`-terminated C-string name for the annotation. Namesdo not have to be unique, though not all crash processors may handleAnnotations with the same name. Names should be constexpr data withstatic storage duration.
value_ptr [in] A pointer to the value for the annotation. Thepointer may not be changed once associated with an annotation, butthe data may be mutated.
concurrent_access_guard_mode [in] Mode used to guard concurrentreads 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 class Type : uint16_t
Name Value Comments
kInvalid 0

An invalid annotation. Reserved for internal use.
kString 1

A `NUL`-terminated C-string.
kUserDefinedStart 0x8000

Clients may declare their own custom types by using values

greater than this.

The type of data stored in the annotation.

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

enum class ConcurrentAccessGuardMode : _Bool
Name Value Comments
kUnguarded false

\
!brief Annotation does not guard reads from concurrent
writes. Annotation values can be corrupted if the process crashes
mid-write and the handler tries to read from the Annotation while
being written to.
kScopedSpinGuard true

\
!brief Annotation guards reads from concurrent writes using
ScopedSpinGuard. Clients must use TryCreateScopedSpinGuard()
before reading or writing the data in this Annotation.

Mode used to guard concurrent reads from writes.

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

Friends

class AnnotationList