Represents an X-Trace metadata. More...

#include <XtrMetadata.h>

Public Member Functions
	Metadata (size_t tlen=4, size_t olen=4)
	Default constructor, creates a new Metadata with invalid taskId and 0 opId, and with no options.
	Metadata (const TaskId &id, size_t opIdLen=4)
	Creates a new Metadata with the taskId set to the parameter, opId to a random value, and no options.
	Metadata (const TaskId &id, const OpId &opId)
	Creates a new Metadata with the given taskId and opId, and no options.
void	clear ()
	Resets the Metadata to an invalid metadata, with an invalid taskId of length 4, opId set to 0, and no options.
bool	isValid () const
	Whether this metadata is valid.
bool	isEqual (const Metadata &other) const
	Compares this and another Metadata for equality.
const TaskId &	getTaskId () const
	Returns the taskId of this Metadata.
const OpId &	getOpId () const
	Returns the opId of this Metadata.
Options &	getOptions ()
xtr_result	setTaskId (const TaskId &id)
	Sets the taskId of this Metadata.
xtr_result	setRandomTaskId (size_t len=4)
	Sets the taskId to a random value of the given length.
xtr_result	setOpId (const OpId &id)
	Sets the opId of this Metadata.
xtr_result	setRandomOpId (size_t opIdLen=4)
	Sets the opId to a random value of the given length.
xtr_result	addOption (const Option &opt)
u_int16_t	getChainId () const
	Returns the chainId contained in the first chainId option present in the metadata.
xtr_result	setChainId (u_int16_t id)
	Sets the first chainId option present in the Metadata to id.
xtr_result	newChainId ()
	Sets the first chainId option present in the Metadata to a RANDOM id.
u_int8_t	getSeverityThreshold () const
	Returns the severity in the first Severity option present in the metadata.
xtr_result	setSeverityThreshold (u_int8_t s)
	Sets the first severity option present in the Metadata to s.
xtr_result	unsetSeverityThreshold ()
	Removes all severity options from the metadata.
size_t	sizeAsBytes () const
	Returns the size of the metadata in bytes when packed.
xtr_result	pack (u_int8_t to, size_t len) const
	Converts the metadata in memory to a packed byte representation.
size_t	sizeAsString () const
	Returns the size of the metadata when represented as a string, not including the terminating '\0' character.
char *	toString (char *to, size_t len) const
	Converts the metadata to a string in the preallocated buffer.
Static Public Member Functions
static Metadata	createFromString (const char *s, size_t len)
	Creates a new Metadata from the given C-style string.
static Metadata	createFromBytes (const u_int8_t *b, size_t len)
	Creates a new Metadata from the given packed binary representation.
static Metadata	createRandom (size_t taskIdLen=4, size_t opIdLen=4)
	Creates a new Metadata with the given length for the taskId and for the opId.
static size_t	sizeInArray (const u_int8_t *to, size_t len)
	Returns how many bytes a Metadata occupies in binary form in the array pointed to by to.

Detailed Description

Represents an X-Trace metadata.

Constructor & Destructor Documentation

xtr::Metadata::Metadata	(	size_t	tlen = `4`,
		size_t	olen = `4`
	)		`[inline]`

Default constructor, creates a new Metadata with invalid taskId and 0 opId, and with no options.

If called with no parameters, the taskId is set to 4. Version is set to XTR_CURRENT_VERSION

Parameters:

tlen	the length in bytes of the taskId. Valid values are 4, 8, 12, or 20. If an invalid value is passed, an invalid taskId of length 4 is set instead.
olen	the length in bytes of the opId. Valid values are 4 and 8. If an invalid value is passed, 4 is used.

Referenced by createFromBytes(), createFromString(), and createRandom().

xtr::Metadata::Metadata	(	const TaskId &	id,
		size_t	opIdLen = `4`
	)		`[inline]`

Creates a new Metadata with the taskId set to the parameter, opId to a random value, and no options.

Parameters:

id	taskId to use for the metadata
opIdLen	the length of the opId

References setRandomOpId(), and setTaskId().

xtr::Metadata::Metadata	(	const TaskId &	id,
		const OpId &	opId
	)		`[inline]`

Creates a new Metadata with the given taskId and opId, and no options.

Parameters:

id	taskId to use for the metadata
opId	opId to use for the metadata

References setOpId(), and setTaskId().

Member Function Documentation

xtr_result xtr::Metadata::addOption ( const Option & opt ) [inline]

References xtr::Options::addOption().

void xtr::Metadata::clear ( )

Resets the Metadata to an invalid metadata, with an invalid taskId of length 4, opId set to 0, and no options.

This is the same as is returned by the default constructor.

static Metadata xtr::Metadata::createFromBytes	(	const u_int8_t *	b,
		size_t	len
	)		`[inline, static]`

Creates a new Metadata from the given packed binary representation.

References Metadata().

static Metadata xtr::Metadata::createFromString	(	const char *	s,
		size_t	len
	)		`[inline, static]`

Creates a new Metadata from the given C-style string.

Parameters:

s	c-style string buffer
len	number of characters to read from, not including the 0 terminator

Returns:: an Metadata * to a newly allocated object. The metadata will be invalid if there is an error.

References Metadata().

static Metadata xtr::Metadata::createRandom	(	size_t	taskIdLen = `4`,
		size_t	opIdLen = `4`
	)		`[inline, static]`

Creates a new Metadata with the given length for the taskId and for the opId.

Both the taskId and the opId will be set to random numbers. If called with no parameters the taskId and opId will be set to the default of 4 bytes.

If there is an error a metadata will be returned as if called from the default constructor, i.e., 0'd taskID of length 4, 0'd opId, no options.

Parameters:

taskIdLen	the length in bytes of the taskId of the created metadata.
opIdLen	the length of the opId

References Metadata().

u_int16_t xtr::Metadata::getChainId ( ) const

Returns the chainId contained in the first chainId option present in the metadata.

If no chainId option is present, returns 0. Experimental.

const OpId& xtr::Metadata::getOpId ( ) const [inline]

Returns the opId of this Metadata.

Options& xtr::Metadata::getOptions ( ) [inline]

u_int8_t xtr::Metadata::getSeverityThreshold ( ) const

Returns the severity in the first Severity option present in the metadata.

If no such option is in, returns OptionSeverity::_UNSET

const TaskId& xtr::Metadata::getTaskId ( ) const [inline]

Returns the taskId of this Metadata.

bool xtr::Metadata::isEqual ( const Metadata & other ) const

Compares this and another Metadata for equality.

The taskId, opId, and options have to be the same. In particular, the options must all be identical and in the same order

bool xtr::Metadata::isValid ( ) const [inline]

Whether this metadata is valid.

An Metadata is valid if the taskId is not all zeroes.

References xtr::TaskId::isValid().

xtr_result xtr::Metadata::newChainId ( )

Sets the first chainId option present in the Metadata to a RANDOM id.

This is used to indicate a fork in the computation.

xtr_result xtr::Metadata::pack	(	u_int8_t *	to,
		size_t *	len
	)		const

Converts the metadata in memory to a packed byte representation.

Parameters:

to	pointer to a prealocated array
len	pointer to an integer. input: the maximum size of the array output: the actual size used (equal to the result of sizeAsBytes()

Returns:: xtr_result XTR_FAIL if *len < sizeAsBytes(), or if to or len are NULL

xtr_result xtr::Metadata::setChainId ( u_int16_t id )

Sets the first chainId option present in the Metadata to id.

If there is no chainId present, creates a new option

xtr_result xtr::Metadata::setOpId ( const OpId & id )

Sets the opId of this Metadata.

If the version of the metadata is 0 and the new opId has length > 4, the version is updated to 1.

Parameters:

id	opId to be set

Referenced by Metadata().

xtr_result xtr::Metadata::setRandomOpId ( size_t opIdLen = 4 )

Sets the opId to a random value of the given length.

If the version of the metadata is 0 and the new opId has length > 4, the version is updated to 1.

Parameters:

opIdLen length of the new opId. Valid lengths are 4 or 8. If an invalid length is passed, the opId is not altered.

Returns:: XTR_SUCCESS if length is valid, XTR_FAIL otherwise

Referenced by Metadata().

xtr_result xtr::Metadata::setRandomTaskId ( size_t len = 4 )

Sets the taskId to a random value of the given length.

Parameters:

len	length of the new taskId. Valid lengths are 4,8,12, or 20. If an invalid length is passed, the taskId is not altered.

Returns:: XTR_SUCCESS if length is valid, XTR_FAIL otherwise

xtr_result xtr::Metadata::setSeverityThreshold ( u_int8_t s )

Sets the first severity option present in the Metadata to s.

If there is no Severity option present, creates a new option

Parameters:

s	severity level. Only valid values are from OptionSeverity::EMERG to OptionSeverity:DEBUG.

Returns:: XTR_FAIL_SEVERITY if s is invalid XTR_FAIL if can't add option XTR_SUCCESS otherwise.

xtr_result xtr::Metadata::setTaskId ( const TaskId & id )

Sets the taskId of this Metadata.

Parameters:

id	taskId to be set

Referenced by Metadata().

size_t xtr::Metadata::sizeAsBytes ( ) const

Returns the size of the metadata in bytes when packed.

Referenced by sizeAsString().

size_t xtr::Metadata::sizeAsString ( ) const [inline]

Returns the size of the metadata when represented as a string, not including the terminating '\0' character.

This is consistent with strlen called on a string representation of the metadata.

References sizeAsBytes().

static size_t xtr::Metadata::sizeInArray	(	const u_int8_t *	to,
		size_t	len
	)		`[static]`

Returns how many bytes a Metadata occupies in binary form in the array pointed to by to.

If to does not have a valid metadata or if len is not sufficient for a valid metadata, then we return 0.

Parameters:

to	an array of size at least len where to look for a metadata
len	minimum size of the array pointed to by to

Returns:: the number of bytes occupied by the metadata if valid, or 0 if the metadata is invalid or len is insuficient

char* xtr::Metadata::toString	(	char *	to,
		size_t	len
	)		const

Converts the metadata to a string in the preallocated buffer.

Parameters:

to	preallocated buffer. If the call is successful, the contents of buf will be the string representation of the metadata. Otherwise (if len is insufficient, < sizeAsString() + 1), buf will have '\0' in its first position.
len	maximum size of the buffer. This must be at least sizeAsString() + 1.

Returns:: pointer to 'to'.

xtr_result xtr::Metadata::unsetSeverityThreshold ( )

Removes all severity options from the metadata.

After this call a call to getSeverity MUST return OptionSeverity::_UNSET.

Returns:: XTR_SUCCESS even if no severity option was present (i.e., the call is idempotent)

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

XtrMetadata.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation