Babeltrace 2 C API 2.1.0
Open-source trace manipulation framework
Loading...
Searching...
No Matches

Detailed Description

Class of stream clocks.

A clock class is the class of stream clocks.

A clock class is a trace IR metadata object.

Stream clocks only exist conceptually in Babeltrace 2 because they're stateful objects. Messages cannot refer to stateful objects because they must not change while being transported from one component to the other.

Instead of having a stream clock object, messages have a default clock snapshot: this is a snapshot of the value of the default clock of a stream (a clock class instance):

In the illustration above, notice that:

The default clock class property of a stream class is optional: if a stream class has no default clock class, then its instances (streams) have no default clock, therefore all the messages created from this stream have no default clock snapshot.

A clock class is a shared object: get a new reference with bt_clock_class_get_ref() and put an existing reference with bt_clock_class_put_ref().

Some library functions freeze clock classes on success. The documentation of those functions indicate this postcondition.

The type of a clock class is bt_clock_class.

Create a default clock class from a self component with bt_clock_class_create().

Since Babeltrace 2.1, get the effective Message Interchange Protocol version of the trace processing graph containing the component from which a clock class was created with bt_clock_class_get_graph_mip_version().

Clock value vs. clock origin

The value of a stream clock (a conceptual instance of a clock class) is in cycles. This value is always positive and is relative to the offset of the clock, which is itself relative to its origin.

The origin of a clock is one of, depending on its class:

If bt_clock_class_origin_is_known() returns BT_FALSE

Unknown.

Two stream clocks of which the classes have an unknown origin only have a correlation if they share the same identity.

Check whether or not two clock classes share the same identity with bt_clock_class_has_same_identity().

If bt_clock_class_origin_is_unix_epoch() returns BT_TRUE

The Unix epoch.

All stream clocks with a Unix epoch origin, whatever their identity, have a correlation.

Otherwise (only available when the clock class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1; available since Babeltrace 2.1)

The namespace, name, and unique identifier (UID) tuple returned by bt_clock_class_get_origin_namespace(), bt_clock_class_get_origin_name(), and bt_clock_class_get_origin_uid().

All stream clocks with the same custom origin, whatever their identity, have a correlation.

Check whether or not two clock classes share the same identity with bt_clock_class_has_same_identity().

To compute an effective stream clock value, in cycles from its origin:

  1. Convert the "offset in seconds" property of the clock to cycles using its frequency.
  2. Add the value of step 1, the value of the stream clock, and the "offset in cycles" property of the clock.

Because typical tracer clocks have a high frequency (often 1 GHz and more), an effective stream clock value (cycles since Unix epoch, for example) can be larger than UINT64_MAX. This is why a clock class has two offset properties (one in seconds and one in cycles): to make it possible for a stream clock to have smaller values, relative to this offset.

The bt_clock_class_cycles_to_ns_from_origin(), bt_util_clock_cycles_to_ns_from_origin(), and bt_clock_snapshot_get_ns_from_origin() functions convert a stream clock value (cycles) to an equivalent nanoseconds from origin value using the relevant clock class properties (frequency and offset).

Those functions perform this computation:

  1. Convert the "offset in cycles" property of the clock to seconds using its frequency.
  2. Convert the value of the clock to seconds using its frequency.
  3. Add the values of step 1, step 2, and the "offset in seconds" property of the clock.
  4. Convert the value of step 3 to nanoseconds.

The following illustration shows the possible scenarios:

The "offset in seconds" property of the clock can be negative. For example, considering:

Then the computed value is −7.5 seconds from origin, or −7,500,000,000 nanoseconds from origin.

Properties

A clock class has the following properties:

Frequency

Frequency of the clock class instances (stream clocks) (cycles/second).

Use bt_clock_class_set_frequency() and bt_clock_class_get_frequency().

Offset (in seconds and in cycles)

Offset in seconds relative to the origin of the clock class instances (stream clocks), and offset in cycles relative to the offset in seconds.

The values of the clock class instances are relative to the computed offset.

Use bt_clock_class_set_offset() and bt_clock_class_get_offset().

Precision (optional when the clock class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1; available since Babeltrace 2.1)

Precision of the clock class instance (stream clocks) values (cycles).

For example, considering a precision of 7 cycles, an accuracy of 0 cycles, and the stream clock value 42 cycles, the real stream clock value can be anything between 35 cycles and 49 cycles.

Use bt_clock_class_set_precision() and bt_clock_class_get_opt_precision().

Optional: Accuracy (only available when the clock class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1; available since Babeltrace 2.1)

Accuracy of the clock class instance (stream clocks) values (cycles).

For example, considering an accuracy of 7 cycles, a precision of 0 cycles, and the stream clock value 42 cycles, the real stream clock value can be anything between 35 cycles and 49 cycles.

Use bt_clock_class_set_accuracy() and bt_clock_class_get_accuracy().

Origin

Origin of the clock class instances (stream clocks).

Depending on the effective Message Interchange Protocol (MIP) version of the trace processing graph:

MIP 0 or MIP 1
Unknown origin

Use bt_clock_class_set_origin_unknown() and bt_clock_class_origin_is_known().

Unix epoch origin
Use bt_clock_class_set_origin_unix_epoch() and bt_clock_class_origin_is_unix_epoch(),

MIP 1: custom origin (available since Babeltrace 2.1)
Use bt_clock_class_set_origin(), bt_clock_class_get_origin_namespace(), bt_clock_class_get_origin_name(), and bt_clock_class_get_origin_uid().

Optional: Identity

Identity of the clock class instances (stream clocks).

Depending on the effective Message Interchange Protocol (MIP) version of the trace processing graph:

MIP 0

The name and UUID property pair.

A valid identity only requires the UUID property.

Use bt_clock_class_set_name(), bt_clock_class_get_name(), bt_clock_class_set_uuid(), and bt_clock_class_get_uuid().

MIP 1 (available since Babeltrace 2.1)

The namespace, name, and UID property tuple.

A valid identity only requires the name and UID properties.

Use bt_clock_class_set_namespace(), bt_clock_class_get_namespace(), bt_clock_class_set_name(), bt_clock_class_get_name(), bt_clock_class_set_uid(), and bt_clock_class_get_uid().

Optional: Description

Description of the clock class.

Use bt_clock_class_set_description() and bt_clock_class_get_description().

Optional: User attributes

User attributes of the clock class.

User attributes are custom attributes attached to a clock class.

Use bt_clock_class_set_user_attributes(), bt_clock_class_borrow_user_attributes(), and bt_clock_class_borrow_user_attributes_const().

Properties

enum  bt_clock_class_set_origin_status {
  BT_CLOCK_CLASS_SET_ORIGIN_STATUS_OK ,
  BT_CLOCK_CLASS_SET_ORIGIN_STATUS_MEMORY_ERROR
}
 Status codes for bt_clock_class_set_origin(). More...
 
enum  bt_clock_class_set_namespace_status {
  BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_OK ,
  BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR
}
 Status codes for bt_clock_class_set_namespace(). More...
 
enum  bt_clock_class_set_name_status {
  BT_CLOCK_CLASS_SET_NAME_STATUS_OK ,
  BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
}
 Status codes for bt_clock_class_set_name(). More...
 
enum  bt_clock_class_set_uid_status {
  BT_CLOCK_CLASS_SET_UID_STATUS_OK ,
  BT_CLOCK_CLASS_SET_UID_STATUS_MEMORY_ERROR
}
 Status codes for bt_clock_class_set_uid(). More...
 
enum  bt_clock_class_set_description_status {
  BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK ,
  BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
}
 Status codes for bt_clock_class_set_description(). More...
 
typedef enum bt_clock_class_set_origin_status bt_clock_class_set_origin_status
 Status codes for bt_clock_class_set_origin().
 
typedef enum bt_clock_class_set_namespace_status bt_clock_class_set_namespace_status
 Status codes for bt_clock_class_set_namespace().
 
typedef enum bt_clock_class_set_name_status bt_clock_class_set_name_status
 Status codes for bt_clock_class_set_name().
 
typedef enum bt_clock_class_set_uid_status bt_clock_class_set_uid_status
 Status codes for bt_clock_class_set_uid().
 
typedef enum bt_clock_class_set_description_status bt_clock_class_set_description_status
 Status codes for bt_clock_class_set_description().
 
void bt_clock_class_set_frequency (bt_clock_class *clock_class, uint64_t frequency)
 Sets the frequency (Hz) of the clock class clock_class to frequency.
 
uint64_t bt_clock_class_get_frequency (const bt_clock_class *clock_class)
 Returns the frequency (Hz) of the clock class clock_class.
 
void bt_clock_class_set_offset (bt_clock_class *clock_class, int64_t offset_seconds, uint64_t offset_cycles)
 Sets the offset of the clock class clock_class to offset_seconds plus offset_cycles from its origin.
 
void bt_clock_class_get_offset (const bt_clock_class *clock_class, int64_t *offset_seconds, uint64_t *offset_cycles)
 Returns the offsets in seconds and cycles of the clock class clock_class.
 
void bt_clock_class_set_precision (bt_clock_class *clock_class, uint64_t precision)
 Sets the precision (cycles) of the clock class clock_class to precision.
 
uint64_t bt_clock_class_get_precision (const bt_clock_class *clock_class)
 Returns the precision (cycles) of the clock class clock_class.
 
bt_property_availability bt_clock_class_get_opt_precision (const struct bt_clock_class *clock_class, uint64_t *precision)
 Returns the precision of the clock class clock_class.
 
void bt_clock_class_set_accuracy (bt_clock_class *clock_class, uint64_t accuracy)
 Sets the accuracy (cycles) of the clock class clock_class to accuracy.
 
bt_property_availability bt_clock_class_get_accuracy (const struct bt_clock_class *clock_class, uint64_t *accuracy)
 Returns the accuracy of the clock class clock_class.
 
void bt_clock_class_set_origin_is_unix_epoch (bt_clock_class *clock_class, bt_bool origin_is_unix_epoch)
 Sets whether the origin of the clock class clock_class is unknown or the Unix epoch.
 
void bt_clock_class_set_origin_unknown (bt_clock_class *clock_class)
 Makes the origin of the clock class clock_class unknown.
 
void bt_clock_class_set_origin_unix_epoch (bt_clock_class *clock_class)
 Makes the origin of the clock class clock_class the Unix epoch.
 
bt_clock_class_set_origin_status bt_clock_class_set_origin (bt_clock_class *clock_class, const char *ns, const char *name, const char *uid)
 Sets the custom origin of the clock class clock_class to the ns, name, and uid tuple.
 
bt_bool bt_clock_class_origin_is_known (const bt_clock_class *clock_class)
 Returns whether or not the origin of the clock class clock_class is known.
 
bt_bool bt_clock_class_origin_is_unix_epoch (const bt_clock_class *clock_class)
 Returns whether or not the origin of the clock class clock_class is the Unix epoch.
 
const char * bt_clock_class_get_origin_namespace (const bt_clock_class *clock_class)
 Returns the namespace of the custom origin of the clock class clock_class.
 
const char * bt_clock_class_get_origin_name (const bt_clock_class *clock_class)
 Returns the name of the custom origin of the clock class clock_class.
 
const char * bt_clock_class_get_origin_uid (const bt_clock_class *clock_class)
 Returns the UID of the custom origin of the clock class clock_class.
 
bt_clock_class_set_namespace_status bt_clock_class_set_namespace (bt_clock_class *clock_class, const char *ns)
 Sets the namespace of the clock class clock_class to a copy of ns.
 
const char * bt_clock_class_get_namespace (const bt_clock_class *clock_class)
 Returns the namespace of the clock class clock_class.
 
bt_clock_class_set_name_status bt_clock_class_set_name (bt_clock_class *clock_class, const char *name)
 Sets the name of the clock class clock_class to a copy of name.
 
const char * bt_clock_class_get_name (const bt_clock_class *clock_class)
 Returns the name of the clock class clock_class.
 
bt_clock_class_set_uid_status bt_clock_class_set_uid (bt_clock_class *clock_class, const char *uid)
 Sets the unique identifier (UID) of the clock class clock_class to a copy of uid.
 
const char * bt_clock_class_get_uid (const bt_clock_class *clock_class)
 Returns the UID of the clock class clock_class.
 
bt_bool bt_clock_class_has_same_identity (const bt_clock_class *clock_class_a, const bt_clock_class *clock_class_b)
 Returns whether or not the clock classes clock_class_a and clock_class_b share the same identity.
 
void bt_clock_class_set_uuid (bt_clock_class *clock_class, bt_uuid uuid)
 Sets the UUID of the clock class clock_class to a copy of uuid.
 
bt_uuid bt_clock_class_get_uuid (const bt_clock_class *clock_class)
 Returns the UUID of the clock class clock_class.
 
bt_clock_class_set_description_status bt_clock_class_set_description (bt_clock_class *clock_class, const char *description)
 Sets the description of the clock class clock_class to a copy of description.
 
const char * bt_clock_class_get_description (const bt_clock_class *clock_class)
 Returns the description of the clock class clock_class.
 
void bt_clock_class_set_user_attributes (bt_clock_class *clock_class, const bt_value *user_attributes)
 Sets the user attributes of the clock class clock_class to user_attributes.
 
bt_valuebt_clock_class_borrow_user_attributes (bt_clock_class *clock_class)
 Borrows the user attributes of the clock class clock_class.
 
const bt_valuebt_clock_class_borrow_user_attributes_const (const bt_clock_class *clock_class)
 Borrows the user attributes of the clock class clock_class (const version).
 

Utilities

enum  bt_clock_class_cycles_to_ns_from_origin_status {
  BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK ,
  BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
}
 Status codes for bt_clock_class_cycles_to_ns_from_origin(). More...
 
typedef enum bt_clock_class_cycles_to_ns_from_origin_status bt_clock_class_cycles_to_ns_from_origin_status
 Status codes for bt_clock_class_cycles_to_ns_from_origin().
 
bt_clock_class_cycles_to_ns_from_origin_status bt_clock_class_cycles_to_ns_from_origin (const bt_clock_class *clock_class, uint64_t value, int64_t *ns_from_origin)
 Converts the stream clock value value from cycles to nanoseconds from the origin of the clock class clock_class and sets *ns_from_origin to the result.
 

Type

typedef struct bt_clock_class bt_clock_class
 Clock class.
 

Creation

bt_clock_classbt_clock_class_create (bt_self_component *self_component)
 Creates a default clock class from the self component self_component.
 

Effective Message Interchange Protocol (MIP) version access

uint64_t bt_clock_class_get_graph_mip_version (const bt_clock_class *clock_class)
 Returns the effective Message Interchange Protocol (MIP) version of the trace processing graph containing the component from which clock_class was created.
 

Reference count

void bt_clock_class_get_ref (const bt_clock_class *clock_class)
 Increments the reference count of the clock class clock_class.
 
void bt_clock_class_put_ref (const bt_clock_class *clock_class)
 Decrements the reference count of the clock class clock_class.
 
#define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_clock_class)
 Decrements the reference count of the clock class _clock_class, and then sets _clock_class to NULL.
 
#define BT_CLOCK_CLASS_MOVE_REF(_dst, _src)
 Decrements the reference count of the clock class _dst, sets _dst to _src, and then sets _src to NULL.
 

Typedef Documentation

◆ bt_clock_class_set_origin_status

◆ bt_clock_class_set_namespace_status

◆ bt_clock_class_set_uid_status

Status codes for bt_clock_class_set_uid().

Since
Babeltrace 2.1

Enumeration Type Documentation

◆ bt_clock_class_set_origin_status

Status codes for bt_clock_class_set_origin().

Since
Babeltrace 2.1
Enumerator
BT_CLOCK_CLASS_SET_ORIGIN_STATUS_OK 

Success.

BT_CLOCK_CLASS_SET_ORIGIN_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_clock_class_set_namespace_status

Status codes for bt_clock_class_set_namespace().

Since
Babeltrace 2.1
Enumerator
BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_OK 

Success.

BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_clock_class_set_name_status

Status codes for bt_clock_class_set_name().

Enumerator
BT_CLOCK_CLASS_SET_NAME_STATUS_OK 

Success.

BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_clock_class_set_uid_status

Status codes for bt_clock_class_set_uid().

Since
Babeltrace 2.1
Enumerator
BT_CLOCK_CLASS_SET_UID_STATUS_OK 

Success.

BT_CLOCK_CLASS_SET_UID_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_clock_class_set_description_status

Status codes for bt_clock_class_set_description().

Enumerator
BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK 

Success.

BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR 

Out of memory.

◆ bt_clock_class_cycles_to_ns_from_origin_status

Status codes for bt_clock_class_cycles_to_ns_from_origin().

Enumerator
BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK 

Success.

BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR 

Integer overflow while computing the result.

Macro Definition Documentation

◆ BT_CLOCK_CLASS_PUT_REF_AND_RESET

#define BT_CLOCK_CLASS_PUT_REF_AND_RESET ( _clock_class)

Decrements the reference count of the clock class _clock_class, and then sets _clock_class to NULL.

Parameters
_clock_class

Clock class of which to decrement the reference count.

Can contain NULL.

Precondition
_clock_class is an assignable expression.

◆ BT_CLOCK_CLASS_MOVE_REF

#define BT_CLOCK_CLASS_MOVE_REF ( _dst,
_src )

Decrements the reference count of the clock class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a clock class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters
_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition
_dst is an assignable expression.
_src is an assignable expression.

Function Documentation

◆ bt_clock_class_create()

bt_clock_class * bt_clock_class_create ( bt_self_component * self_component)
extern

Creates a default clock class from the self component self_component.

On success, the returned clock class has the following property values:

Property Value
Frequency 1 GHz
Offset in seconds 0 seconds
Offset in cycles 0 cycles
Precision

Depending on the effective Message Interchange Protocol (MIP) version of the trace processing graph:

MIP 0

0 cycles

MIP 1 (available since Babeltrace 2.1)
Unknown
Message Interchange Protocol version 1: accuracy (available since Babeltrace 2.1) Unknown
Origin Unix epoch
Identity

None, that is, depending on the effective Message Interchange Protocol (MIP) version of the trace processing graph:

MIP 0

No name and no UUID

MIP 1 (available since Babeltrace 2.1)
No namespace, no name, and no UID
Description None
User attributes Empty map value
Parameters
[in]self_componentSelf component from which to create the default clock class.
Returns
New clock class reference, or NULL on memory error.
Precondition
self_component is not NULL.

◆ bt_clock_class_set_frequency()

void bt_clock_class_set_frequency ( bt_clock_class * clock_class,
uint64_t frequency )
extern

Sets the frequency (Hz) of the clock class clock_class to frequency.

See the frequency property.

Parameters
[in]clock_classClock class of which to set the frequency to frequency.
[in]frequencyNew frequency of clock_class.
Precondition
clock_class is not NULL.
clock_class is not frozen.
frequency isn't 0.
frequency isn't UINT64_C(-1).
frequency is greater than the offset in cycles of the clock class (as returned by bt_clock_class_get_offset()).
See also
bt_clock_class_get_frequency() — Returns the frequency of a clock class.

◆ bt_clock_class_get_frequency()

uint64_t bt_clock_class_get_frequency ( const bt_clock_class * clock_class)
extern

Returns the frequency (Hz) of the clock class clock_class.

See the frequency property.

Parameters
[in]clock_classClock class of which to get the frequency.
Returns
Frequency (Hz) of clock_class.
Precondition
clock_class is not NULL.
See also
bt_clock_class_set_frequency() — Sets the frequency of a clock class.

◆ bt_clock_class_set_offset()

void bt_clock_class_set_offset ( bt_clock_class * clock_class,
int64_t offset_seconds,
uint64_t offset_cycles )
extern

Sets the offset of the clock class clock_class to offset_seconds plus offset_cycles from its origin.

See the offset property.

Parameters
[in]clock_classClock class of which to set the offset to offset_seconds and offset_cycles.
[in]offset_secondsNew offset in seconds of clock_class.
[in]offset_cyclesNew offset in cycles of clock_class.
Precondition
clock_class is not NULL.
clock_class is not frozen.
offset_cycles is less than the frequency of the clock class (as returned by bt_clock_class_get_frequency()).
See also
bt_clock_class_get_offset() — Returns the offset of a clock class.

◆ bt_clock_class_get_offset()

void bt_clock_class_get_offset ( const bt_clock_class * clock_class,
int64_t * offset_seconds,
uint64_t * offset_cycles )
extern

Returns the offsets in seconds and cycles of the clock class clock_class.

See the offset property.

Parameters
[in]clock_classClock class of which to get the offset.
[out]offset_secondsWhen this function returns, *offset_seconds is the offset in seconds of clock_class.
[out]offset_cyclesWhen this function returns, *offset_cycles is the offset in cycles of clock_class.
Precondition
clock_class is not NULL.
offset_seconds is not NULL.
offset_cycles is not NULL.
See also
bt_clock_class_set_offset() — Sets the offset of a clock class.

◆ bt_clock_class_set_precision()

void bt_clock_class_set_precision ( bt_clock_class * clock_class,
uint64_t precision )
extern

Sets the precision (cycles) of the clock class clock_class to precision.

See the precision property.

Parameters
[in]clock_classClock class of which to set the precision to precision.
[in]precisionNew precision of clock_class.
Precondition
clock_class is not NULL.
clock_class is not frozen.
See also
bt_clock_class_get_precision() — Returns the precision of a clock class.

◆ bt_clock_class_get_precision()

uint64_t bt_clock_class_get_precision ( const bt_clock_class * clock_class)
extern

Returns the precision (cycles) of the clock class clock_class.

Deprecated
Use bt_clock_class_get_opt_precision().
Note
This function is only available when clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol (MIP) version 0.

See the precision property.

Parameters
[in]clock_classClock class of which to get the precision.
Returns
Precision (cycles) of clock_class.
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  0.
See also
bt_clock_class_set_precision() — Sets the precision of a clock class.

◆ bt_clock_class_get_opt_precision()

bt_property_availability bt_clock_class_get_opt_precision ( const struct bt_clock_class * clock_class,
uint64_t * precision )
extern

Returns the precision of the clock class clock_class.

See the precision property.

Parameters
[in]clock_classClock class of which to get the precision.
[out]precision

If this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, then *precision is the precision (cycles) of clock_class.

Otherwise, the precision of clock_class is unknown.

Return values
BT_PROPERTY_AVAILABILITY_AVAILABLEThe precision of clock_class is known.
BT_PROPERTY_AVAILABILITY_NOT_AVAILABLEThe precision of clock_class is unknown.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
precision is not NULL.
See also
bt_clock_class_set_precision() — Sets the precision of a clock class.

◆ bt_clock_class_set_accuracy()

void bt_clock_class_set_accuracy ( bt_clock_class * clock_class,
uint64_t accuracy )
extern

Sets the accuracy (cycles) of the clock class clock_class to accuracy.

See the accuracy property.

Parameters
[in]clock_classClock class of which to set the accuracy to accuracy.
[in]accuracyNew accuracy of clock_class.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
See also
bt_clock_class_get_accuracy() — Returns the accuracy of a clock class.

◆ bt_clock_class_get_accuracy()

bt_property_availability bt_clock_class_get_accuracy ( const struct bt_clock_class * clock_class,
uint64_t * accuracy )
extern

Returns the accuracy of the clock class clock_class.

See the accuracy property.

Parameters
[in]clock_classClock class of which to get the accuracy.
[out]accuracy

If this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, *accuracy is the accuracy (cycles) of clock_class.

Otherwise, the accuracy of clock_class is unknown.

Return values
BT_PROPERTY_AVAILABILITY_AVAILABLEThe accuracy of clock_class is known.
BT_PROPERTY_AVAILABILITY_NOT_AVAILABLEThe accuracy of clock_class is unknown.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
accuracy is not NULL.
See also
bt_clock_class_set_accuracy() — Sets the accuracy of a clock class.

◆ bt_clock_class_set_origin_is_unix_epoch()

void bt_clock_class_set_origin_is_unix_epoch ( bt_clock_class * clock_class,
bt_bool origin_is_unix_epoch )
extern

Sets whether the origin of the clock class clock_class is unknown or the Unix epoch.

Deprecated
Use bt_clock_class_set_origin_unknown() or bt_clock_class_set_origin_unix_epoch().

See the origin property.

Parameters
[in]clock_classClock class of which to set whether its origin is unknown or the Unix epoch.
[in]origin_is_unix_epoch

One of:

BT_FALSE

Make the origin of clock_class unknown.

BT_TRUE
Make the origin of clock_class the Unix epoch.
Precondition
clock_class is not NULL.
clock_class is not frozen.
See also
bt_clock_class_origin_is_unix_epoch() — Returns whether or not the origin of a clock class is the Unix epoch.

◆ bt_clock_class_set_origin_unknown()

void bt_clock_class_set_origin_unknown ( bt_clock_class * clock_class)
extern

Makes the origin of the clock class clock_class unknown.

See the origin property.

Parameters
[in]clock_classClock class of which to make the origin unknown.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
See also
bt_clock_class_set_origin_unix_epoch() — Makes the origin of a clock class the Unix epoch.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.
bt_clock_class_origin_is_known() — Returns whether or not the origin of a clock class is known.

◆ bt_clock_class_set_origin_unix_epoch()

void bt_clock_class_set_origin_unix_epoch ( bt_clock_class * clock_class)
extern

Makes the origin of the clock class clock_class the Unix epoch.

See the origin property.

Parameters
[in]clock_classClock class of which to make the origin the Unix epoch.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
See also
bt_clock_class_set_origin_unknown() — Makes the origin of a clock class unknown.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.
bt_clock_class_origin_is_unix_epoch() — Returns whether or not the origin of a clock class is the Unix epoch.

◆ bt_clock_class_set_origin()

bt_clock_class_set_origin_status bt_clock_class_set_origin ( bt_clock_class * clock_class,
const char * ns,
const char * name,
const char * uid )
extern

Sets the custom origin of the clock class clock_class to the ns, name, and uid tuple.

See the origin property.

Parameters
[in]clock_classClock class of which to set the origin to the ns, name, and uid tuple.
[in]ns

Namespace of the custom origin of clock_class (copied).

Can be NULL.

[in]nameName of the custom origin of clock_class (copied).
[in]uidUnique identifier (UID) of the custom origin of clock_class (copied).
Return values
BT_CLOCK_CLASS_SET_ORIGIN_STATUS_OKSuccess.
BT_CLOCK_CLASS_SET_ORIGIN_STATUS_MEMORY_ERROROut of memory.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
name is not NULL.
uid is not NULL.
Postcondition
bt_clock_class_origin_is_known() returns BT_TRUE with clock_class.
bt_clock_class_origin_is_unix_epoch() returns BT_FALSE with clock_class.
See also
bt_clock_class_set_origin_unknown() — Makes the origin of a clock class unknown.
bt_clock_class_set_origin_unix_epoch() — Makes the origin of a clock class the Unix epoch.
bt_clock_class_get_origin_namespace() — Returns the namespace of the custom origin of a clock class.
bt_clock_class_get_origin_name() — Returns the name of the custom origin of a clock class.
bt_clock_class_get_origin_uid() — Returns the UID of the custom origin of a clock class.

◆ bt_clock_class_origin_is_known()

bt_bool bt_clock_class_origin_is_known ( const bt_clock_class * clock_class)
extern

Returns whether or not the origin of the clock class clock_class is known.

See the origin property.

The origin of clock_class is known if it's either the Unix epoch or custom.

Parameters
[in]clock_classClock class of which to get whether or not its origin is known.
Returns
BT_TRUE if the origin of clock_class is known.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
See also
bt_clock_class_origin_is_unix_epoch() — Returns whether or not the origin of a clock class is the Unix epoch.
bt_clock_class_set_origin_unknown() — Makes the origin of a clock class unknown.
bt_clock_class_set_origin_unix_epoch() — Makes the origin of a clock class the Unix epoch.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.

◆ bt_clock_class_origin_is_unix_epoch()

bt_bool bt_clock_class_origin_is_unix_epoch ( const bt_clock_class * clock_class)
extern

Returns whether or not the origin of the clock class clock_class is the Unix epoch.

See the origin property.

Parameters
[in]clock_classClock class of which to get whether or not its origin is the Unix epoch.
Returns
BT_TRUE if the origin of clock_class is the Unix epoch.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
See also
bt_clock_class_origin_is_known() — Returns whether or not the origin of a clock class is known.
bt_clock_class_set_origin_unknown() — Makes the origin of a clock class unknown.
bt_clock_class_set_origin_unix_epoch() — Makes the origin of a clock class the Unix epoch.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.

◆ bt_clock_class_get_origin_namespace()

const char * bt_clock_class_get_origin_namespace ( const bt_clock_class * clock_class)
extern

Returns the namespace of the custom origin of the clock class clock_class.

See the origin property.

Parameters
[in]clock_classClock class of which to get the custom origin namespace.
Returns

Custom origin namespace of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
The origin of clock_class is custom: bt_clock_class_origin_is_known() returns BT_TRUE and bt_clock_class_origin_is_unix_epoch() returns BT_FALSE with clock_class.
See also
bt_clock_class_get_origin_name() — Returns the name of the custom origin of a clock class.
bt_clock_class_get_origin_uid() — Returns the UID of the custom origin of a clock class.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.

◆ bt_clock_class_get_origin_name()

const char * bt_clock_class_get_origin_name ( const bt_clock_class * clock_class)
extern

Returns the name of the custom origin of the clock class clock_class.

See the origin property.

Parameters
[in]clock_classClock class of which to get the custom origin name.
Returns

Custom origin name of clock_class, or NULL if none.

If this function doesn't return NULL, then bt_clock_class_get_origin_uid() also doesn't return NULL.

The returned pointer remains valid as long as clock_class isn't modified.

Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
The origin of clock_class is custom: bt_clock_class_origin_is_known() returns BT_TRUE and bt_clock_class_origin_is_unix_epoch() returns BT_FALSE with clock_class.
See also
bt_clock_class_get_origin_namespace() — Returns the namespace of the custom origin of a clock class.
bt_clock_class_get_origin_uid() — Returns the UID of the custom origin of a clock class.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.

◆ bt_clock_class_get_origin_uid()

const char * bt_clock_class_get_origin_uid ( const bt_clock_class * clock_class)
extern

Returns the UID of the custom origin of the clock class clock_class.

See the origin property.

Parameters
[in]clock_classClock class of which to get the custom origin UID.
Returns

Custom origin UID of clock_class, or NULL if none.

If this function doesn't return NULL, then bt_clock_class_get_origin_name() also doesn't return NULL.

The returned pointer remains valid as long as clock_class isn't modified.

Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
The origin of clock_class is custom: bt_clock_class_origin_is_known() returns BT_TRUE and bt_clock_class_origin_is_unix_epoch() returns BT_FALSE with clock_class.
See also
bt_clock_class_get_origin_namespace() — Returns the namespace of the custom origin of a clock class.
bt_clock_class_get_origin_name() — Returns the name of the custom origin of a clock class.
bt_clock_class_set_origin() — Sets the custom origin of a clock class.

◆ bt_clock_class_set_namespace()

bt_clock_class_set_namespace_status bt_clock_class_set_namespace ( bt_clock_class * clock_class,
const char * ns )
extern

Sets the namespace of the clock class clock_class to a copy of ns.

See the identity property.

Parameters
[in]clock_classClock class of which to set the namespace to ns.
[in]nsNew namespace of clock_class (copied).
Return values
BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_OKSuccess.
BT_CLOCK_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROROut of memory.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
namespace is not NULL.
See also
bt_clock_class_get_namespace() — Returns the namespace of a clock class.

◆ bt_clock_class_get_namespace()

const char * bt_clock_class_get_namespace ( const bt_clock_class * clock_class)
extern

Returns the namespace of the clock class clock_class.

See the identity property.

If clock_class has no namespace, then this function returns NULL.

Parameters
[in]clock_classClock class of which to get the namespace.
Returns

Namespace of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
See also
bt_clock_class_set_namespace() — Sets the namespace of a clock class.

◆ bt_clock_class_set_name()

bt_clock_class_set_name_status bt_clock_class_set_name ( bt_clock_class * clock_class,
const char * name )
extern

Sets the name of the clock class clock_class to a copy of name.

See the identity property.

Parameters
[in]clock_classClock class of which to set the name to name.
[in]nameNew name of clock_class (copied).
Return values
BT_CLOCK_CLASS_SET_NAME_STATUS_OKSuccess.
BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROROut of memory.
Precondition
clock_class is not NULL.
clock_class is not frozen.
name is not NULL.
See also
bt_clock_class_get_name() — Returns the name of a clock class.

◆ bt_clock_class_get_name()

const char * bt_clock_class_get_name ( const bt_clock_class * clock_class)
extern

Returns the name of the clock class clock_class.

See the identity property.

If clock_class has no name, then this function returns NULL.

Parameters
[in]clock_classClock class of which to get the name.
Returns

Name of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Precondition
clock_class is not NULL.
See also
bt_clock_class_set_name() — Sets the name of a clock class.

◆ bt_clock_class_set_uid()

bt_clock_class_set_uid_status bt_clock_class_set_uid ( bt_clock_class * clock_class,
const char * uid )
extern

Sets the unique identifier (UID) of the clock class clock_class to a copy of uid.

See the identity property.

Parameters
[in]clock_classClock class of which to set the UID to uid.
[in]uidNew UID of clock_class (copied).
Return values
BT_CLOCK_CLASS_SET_UID_STATUS_OKSuccess.
BT_CLOCK_CLASS_SET_UID_STATUS_MEMORY_ERROROut of memory.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class is not frozen.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
uid is not NULL.
See also
bt_clock_class_get_uid() — Returns the UID of a clock class.

◆ bt_clock_class_get_uid()

const char * bt_clock_class_get_uid ( const bt_clock_class * clock_class)
extern

Returns the UID of the clock class clock_class.

See the identity property.

If clock_class has no UID, then this function returns NULL.

Parameters
[in]clock_classClock class of which to get the UID.
Returns

UID of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
See also
bt_clock_class_set_uid() — Sets the UID of a clock class.

◆ bt_clock_class_has_same_identity()

bt_bool bt_clock_class_has_same_identity ( const bt_clock_class * clock_class_a,
const bt_clock_class * clock_class_b )
extern

Returns whether or not the clock classes clock_class_a and clock_class_b share the same identity.

See the identity property.

Two clock classes share the same identity when all the following are true:

  • They both have a name and a UID.
  • The values of their namespace, name, and UID property tuples are the same.
Parameters
[in]clock_class_aClock class A.
[in]clock_class_bClock class B.
Returns
BT_TRUE if clock_class_a and clock_class_b share the same identity
Since
Babeltrace 2.1
Precondition
clock_class_a is not NULL.
clock_class_a was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.
clock_class_b is not NULL.
clock_class_b was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

◆ bt_clock_class_set_uuid()

void bt_clock_class_set_uuid ( bt_clock_class * clock_class,
bt_uuid uuid )
extern

Sets the UUID of the clock class clock_class to a copy of uuid.

Note
This function is only available when clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol (MIP) version 0.

See the identity property.

Parameters
[in]clock_classClock class of which to set the UUID to uuid.
[in]uuidNew UUID of clock_class (copied).
Precondition
clock_class is not NULL.
clock_class is not frozen.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  0.
uuid is not NULL.
See also
bt_clock_class_get_uuid() — Returns the UUID of a clock class.

◆ bt_clock_class_get_uuid()

bt_uuid bt_clock_class_get_uuid ( const bt_clock_class * clock_class)
extern

Returns the UUID of the clock class clock_class.

Note
This function is only available when clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol (MIP) version 0.

See the identity property.

If clock_class has no UUID, then this function returns NULL.

Parameters
[in]clock_classClock class of which to get the UUID.
Returns

UUID of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Precondition
clock_class is not NULL.
clock_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  0.
See also
bt_clock_class_set_uuid() — Sets the UUID of a clock class.

◆ bt_clock_class_set_description()

bt_clock_class_set_description_status bt_clock_class_set_description ( bt_clock_class * clock_class,
const char * description )
extern

Sets the description of the clock class clock_class to a copy of description.

See the description property.

Parameters
[in]clock_classClock class of which to set the description to description.
[in]descriptionNew description of clock_class (copied).
Return values
BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OKSuccess.
BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROROut of memory.
Precondition
clock_class is not NULL.
clock_class is not frozen.
description is not NULL.
See also
bt_clock_class_get_description() — Returns the description of a clock class.

◆ bt_clock_class_get_description()

const char * bt_clock_class_get_description ( const bt_clock_class * clock_class)
extern

Returns the description of the clock class clock_class.

See the description property.

If clock_class has no description, then this function returns NULL.

Parameters
[in]clock_classClock class of which to get the description.
Returns

Description of clock_class, or NULL if none.

The returned pointer remains valid as long as clock_class isn't modified.

Precondition
clock_class is not NULL.
See also
bt_clock_class_set_description() — Sets the description of a clock class.

◆ bt_clock_class_set_user_attributes()

void bt_clock_class_set_user_attributes ( bt_clock_class * clock_class,
const bt_value * user_attributes )
extern

Sets the user attributes of the clock class clock_class to user_attributes.

See the user attributes property.

Note
When you create a default clock class with bt_clock_class_create(), the initial user attributes of the clock class is an empty map value. Therefore you can borrow it with bt_clock_class_borrow_user_attributes() and fill it directly instead of setting a new one with this function.
Parameters
[in]clock_classClock class of which to set the user attributes to user_attributes.
[in]user_attributesNew user attributes of clock_class.
Precondition
clock_class is not NULL.
clock_class is not frozen.
user_attributes is not NULL.
user_attributes is a map value (bt_value_is_map() returns BT_TRUE).
See also
bt_clock_class_borrow_user_attributes() — Borrows the user attributes of a clock class.

◆ bt_clock_class_borrow_user_attributes()

bt_value * bt_clock_class_borrow_user_attributes ( bt_clock_class * clock_class)
extern

Borrows the user attributes of the clock class clock_class.

See the user attributes property.

Note
When you create a default clock class with bt_clock_class_create(), the initial user attributes of the clock class is an empty map value.
Parameters
[in]clock_classClock class from which to borrow the user attributes.
Returns
User attributes of clock_class (a map value).
Precondition
clock_class is not NULL.
See also
bt_clock_class_set_user_attributes() — Sets the user attributes of a clock class.
bt_clock_class_borrow_user_attributes_const()const version of this function.

◆ bt_clock_class_borrow_user_attributes_const()

const bt_value * bt_clock_class_borrow_user_attributes_const ( const bt_clock_class * clock_class)
extern

Borrows the user attributes of the clock class clock_class (const version).

See bt_clock_class_borrow_user_attributes().

◆ bt_clock_class_get_graph_mip_version()

uint64_t bt_clock_class_get_graph_mip_version ( const bt_clock_class * clock_class)
extern

Returns the effective Message Interchange Protocol (MIP) version of the trace processing graph containing the component from which clock_class was created.

Parameters
[in]clock_classClock class of which to get the effective MIP version.
Returns
Effective MIP version of clock_class.
Since
Babeltrace 2.1
Precondition
clock_class is not NULL.
See also
bt_self_component_get_graph_mip_version() — Returns the effective MIP version of the trace processing graph which contains a given component.

◆ bt_clock_class_cycles_to_ns_from_origin()

bt_clock_class_cycles_to_ns_from_origin_status bt_clock_class_cycles_to_ns_from_origin ( const bt_clock_class * clock_class,
uint64_t value,
int64_t * ns_from_origin )
extern

Converts the stream clock value value from cycles to nanoseconds from the origin of the clock class clock_class and sets *ns_from_origin to the result.

This function:

  1. Converts the "offset in cycles" property of clock_class to seconds using its frequency.
  2. Converts the value value to seconds using the frequency of clock_class.
  3. Adds the values of step 1, step 2, and the "offset in seconds" property of clock_class.
  4. Converts the value of step 3 to nanoseconds and sets *ns_from_origin to this result.

The following illustration shows the possible scenarios:

This function can fail and return the BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status code if any step of the computation process causes an integer overflow.

Parameters
[in]clock_classClass of the stream clock.
[in]valueValue of the stream clock (cycles) to convert to nanoseconds from the origin of clock_class.
[out]ns_from_originOn success, *ns_from_origin is value converted to nanoseconds from the origin of clock_class.
Return values
BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OKSuccess.
BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERRORInteger overflow while computing the result.
Precondition
clock_class is not NULL.
ns_from_origin is not NULL.
See also
bt_util_clock_cycles_to_ns_from_origin() — Converts a clock value from cycles to nanoseconds from the origin of the clock.

◆ bt_clock_class_get_ref()

void bt_clock_class_get_ref ( const bt_clock_class * clock_class)
extern

Increments the reference count of the clock class clock_class.

Parameters
[in]clock_class

Clock class of which to increment the reference count.

Can be NULL.

See also
bt_clock_class_put_ref() — Decrements the reference count of a clock class.

◆ bt_clock_class_put_ref()

void bt_clock_class_put_ref ( const bt_clock_class * clock_class)
extern

Decrements the reference count of the clock class clock_class.

Parameters
[in]clock_class

Clock class of which to decrement the reference count.

Can be NULL.

See also
bt_clock_class_get_ref() — Increments the reference count of a clock class.