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'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:

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

• 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 default clock of the stream.

  In other words, a default clock snapshot contains the value of the default clock of the stream 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 the clock snapshot of a message 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 the value of a clock 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 the value of a clock snapshot.

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 step 1, step 2, and the "offset in seconds" property of the clock class of clock_snapshot.
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_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 origin of a clock.

bt_clock_class_cycles_to_ns_from_origin() — Converts a clock value from cycles to nanoseconds from the origin of a clock class.