Babeltrace 2 C API  2.0.0
Open-source trace manipulation framework
Typedefs | Enumerations | Functions

Detailed Description

Snapshot of a stream clock.

A clock snapshot is a snapshot of the value of a stream clock (a clock class instance).

A clock snapshot is a trace IR data object.

Stream clocks only exist conceptually in Babeltrace 2 because they are 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 a stream's default clock (a clock class instance):

In the illustration above, notice that:

A clock snapshot is a unique object: it belongs to a message.

The type of a clock snapshot is bt_clock_snapshot.

You cannot create a clock snapshot: you specify a clock snapshot value (in clock cycles, a uint64_t value) when you create a message or set a message's clock snapshot with one of:

See Clock value vs. clock class origin to understand the meaning of a clock's value in relation to the properties of its class.

Typedefs

typedef enum bt_clock_snapshot_get_ns_from_origin_status bt_clock_snapshot_get_ns_from_origin_status
 Status codes for bt_clock_snapshot_get_ns_from_origin().
 

Enumerations

enum  bt_clock_snapshot_get_ns_from_origin_status {
  BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK,
  BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
}
 Status codes for bt_clock_snapshot_get_ns_from_origin(). More...
 

Functions

const bt_clock_classbt_clock_snapshot_borrow_clock_class_const (const bt_clock_snapshot *clock_snapshot)
 Borrows the class of the clock of which clock_snapshot is a snapshot. More...
 
uint64_t bt_clock_snapshot_get_value (const bt_clock_snapshot *clock_snapshot)
 Returns the value, in clock cycles, of the clock snapshot clock_snapshot. More...
 
bt_clock_snapshot_get_ns_from_origin_status bt_clock_snapshot_get_ns_from_origin (const bt_clock_snapshot *clock_snapshot, int64_t *ns_from_origin)
 Converts the value of the clock snapshot clock_snapshot from cycles to nanoseconds from the origin of its clock class and sets *ns_from_origin to the result. More...
 

Type

typedef struct bt_clock_snapshot bt_clock_snapshot
 Clock snapshot.
 

Enumeration Type Documentation

◆ bt_clock_snapshot_get_ns_from_origin_status

Status codes for bt_clock_snapshot_get_ns_from_origin().

Enumerator
BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK 

Success.

BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR 

Integer overflow while computing the result.

Function Documentation

◆ bt_clock_snapshot_borrow_clock_class_const()

const bt_clock_class* bt_clock_snapshot_borrow_clock_class_const ( const bt_clock_snapshot clock_snapshot)

Borrows the class of the clock of which clock_snapshot is a snapshot.

Parameters
[in]clock_snapshotClock snapshot of which to borrow the clock class.
Returns
Borrowed reference of the clock class of clock_snapshot.
Precondition
clock_snapshot is not NULL.

◆ bt_clock_snapshot_get_value()

uint64_t bt_clock_snapshot_get_value ( const bt_clock_snapshot clock_snapshot)

Returns the value, in clock cycles, of the clock snapshot clock_snapshot.

Parameters
[in]clock_snapshotClock snapshot of which to get the value.
Returns
Value of clock_snapshot (clock cycles).
Precondition
clock_snapshot is not NULL.
See also
bt_clock_snapshot_get_ns_from_origin() — Returns the equivalent nanoseconds from clock class origin of a clock snapshot's value.

◆ bt_clock_snapshot_get_ns_from_origin()

bt_clock_snapshot_get_ns_from_origin_status bt_clock_snapshot_get_ns_from_origin ( const bt_clock_snapshot clock_snapshot,
int64_t *  ns_from_origin 
)

Converts the value of the clock snapshot clock_snapshot from cycles to nanoseconds from the origin of its clock class and sets *ns_from_origin to the result.

This function:

  1. Converts the "offset in cycles" property of the clock class of clock_snapshot to seconds using its frequency.
  2. Converts the value of clock_snapshot to seconds using the frequency of its clock class.
  3. Adds the values of 1., 2., and the "offset in seconds" property of the clock class of clock_snapshot.
  4. Converts the value of 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_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status code if any step of the computation process causes an integer overflow.

Parameters
[in]clock_snapshotClock snapshot containing the value to convert to nanoseconds from the origin of its clock class.
[out]ns_from_originOn success, *ns_from_origin is the value of clock_snapshot converted to nanoseconds from the origin of its clock class.
Return values
BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OKSuccess.
BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERRORInteger overflow while computing the result.
Precondition
clock_snapshot 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 clock's origin.
bt_clock_class_cycles_to_ns_from_origin() — Converts a clock value from cycles to nanoseconds from a clock class's origin.