Clock snapshot

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:

• Each stream has a default clock (yellow bell alarm clock): this is an instance of the stream's class's default clock class.

• Each message (objects in blue stream rectangles) created for a given stream has a default clock snapshot (yellow star): this is a snapshot of the stream's default clock.

  In other words, a default clock snapshot contains the value of the stream's default clock when this message occurred.

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:

• bt_message_stream_beginning_set_default_clock_snapshot()
• bt_message_stream_end_set_default_clock_snapshot()
• bt_message_event_create_with_default_clock_snapshot()
• bt_message_event_create_with_packet_and_default_clock_snapshot()
• bt_message_packet_beginning_create_with_default_clock_snapshot()
• bt_message_packet_end_create_with_default_clock_snapshot()
• bt_message_discarded_events_create_with_default_clock_snapshots()
• bt_message_discarded_packets_create_with_default_clock_snapshots()
• bt_message_message_iterator_inactivity_create()

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_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.
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.
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.

Type
typedef struct bt_clock_snapshot	bt_clock_snapshot
	Clock snapshot.

Enumeration Type Documentation

bt_clock_snapshot_get_ns_from_origin_status

enum 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 )

extern

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

Parameters

[in]

clock_snapshot

Clock 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 )

extern

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

Parameters

[in]

clock_snapshot

Clock 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 )

extern

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_snapshot	Clock snapshot containing the value to convert to nanoseconds from the origin of its clock class.
[out]	ns_from_origin	On 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_OK	Success.
BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR	Integer 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.