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 class	Type : uint16_t
	The type of data stored in the annotation. More...

enum class	ConcurrentAccessGuardMode : bool
	Mode used to guard concurrent reads from writes. More...

using	ValueSizeType = uint32_t
	The type used for SetSize().

Public Member Functions
constexpr	Annotation (Type type, const char name[], void *value_ptr)
	Constructs a new annotation.

	Annotation (const Annotation &)=delete

Annotation &	operator= (const Annotation &)=delete

void	SetSize (ValueSizeType size)
	Specifies the number of bytes in value_ptr_ to include when generating a crash report.

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

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

ConcurrentAccessGuardMode	concurrent_access_guard_mode () const

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.

Static Public Member Functions
static constexpr Type	UserDefinedType (uint16_t value)
	Creates a user-defined Annotation::Type.

Static Public Attributes
static constexpr size_t	kNameMaxLength = 256
	The maximum length of an annotation’s name, in bytes. Matches the behavior of Breakpad's SimpleStringDictionary.

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

Protected Member Functions
constexpr	Annotation (Type type, const char name[], void *value_ptr, ConcurrentAccessGuardMode concurrent_access_guard_mode)
	Constructs a new annotation.

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

Annotation *	GetLinkNode (std::memory_order order=std::memory_order_seq_cst)

const Annotation *	GetLinkNode (std::memory_order order=std::memory_order_seq_cst) const

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

◆ ConcurrentAccessGuardMode

enum class crashpad::Annotation::ConcurrentAccessGuardMode : bool

strong

Mode used to guard concurrent reads from writes.

Enumerator
kUnguarded	!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	!brief Annotation guards reads from concurrent writes using ScopedSpinGuard. Clients must use TryCreateScopedSpinGuard() before reading or writing the data in this Annotation.

◆ Type

enum class 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() [1/2]

crashpad::Annotation::Annotation	(	Type	type,
		const char	name[],
		void *	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.

◆ Annotation() [2/2]

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

inlineconstexprprotected

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.
[in]	concurrent_access_guard_mode	Mode used to guard concurrent reads from writes.

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.

◆ TryCreateScopedSpinGuard()

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

inline

If this Annotation guards concurrent access using ScopedSpinGuard, tries to obtain the spin guard and returns the result.

Parameters

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

◆ UserDefinedType()

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

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ ConcurrentAccessGuardMode

◆ Type

Constructor & Destructor Documentation

◆ Annotation() [1/2]

◆ Annotation() [2/2]

Member Function Documentation

◆ Clear()

◆ SetSize()

◆ TryCreateScopedSpinGuard()

◆ UserDefinedType()