lib: add stream activity beginning/end messages
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Fri, 8 Feb 2019 22:36:38 +0000 (17:36 -0500)
committerFrancis Deslauriers <francis.deslauriers@efficios.com>
Thu, 2 May 2019 20:50:15 +0000 (20:50 +0000)
commit5df26c89c52ed58a96fc1bce64d6e49d69b655ee
tree06af0529c07c4384feec5a06a94bff68ee147368
parent8ca9c2f15b3efb3d16a44b8839b085d1f5cf903d
lib: add stream activity beginning/end messages

Those new messages are meant to indicate the beginning and end of the
activity of a given stream, with optional clock snapshots. Eventually
all stream messages except stream beginning/end messages must be
"between" stream activity beginning and end messages.

The purpose of such messages is to indicate where tracing activity
starts and stops, for example when the LTTng `start` and `stop` commands
are executed (not supported by LTTng as of this date). This information
can be important for some filters and sinks to acknowledge the real
beginning and end of a stream, for example:

    [------------############################------#######-------------]

    ^ stream activity beginning                    stream activity end ^

     ^^^^^^^^^^^^ tracing, but no activity   ^^^^^^       ^^^^^^^^^^^^^

                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^      ^^^^^^^ activity

We also plan to make flt.utils.trimmer remove those messages for a given
stream and "inject" its own stream activity messages to emulate a
potentially reduced stream activity, depending on the message
intersection between the requested time range to keep and the stream's
time range.

You can use the following functions to set the message's default
clock snapshot:

* bt_message_stream_activity_beginning_set_default_clock_snapshot()
* bt_message_stream_activity_end_set_default_clock_snapshot()

and borrow it with:

* bt_message_stream_activity_beginning_borrow_default_clock_snapshot_const()
* bt_message_stream_activity_end_borrow_default_clock_snapshot_const()

The message's stream's class must have a defined default clock class in
order to use the setting functions.

When you set a stream activity message's default clock snapshot, the
clock snapshot's state within this message is
`BT_MESSAGE_STREAM_ACTIVITY_CLOCK_SNAPSHOT_STATE_KNOWN`. The other
possible states are:

`BT_MESSAGE_STREAM_ACTIVITY_CLOCK_SNAPSHOT_STATE_UNKNOWN` (default):
    It is not possible to know the exact time of this stream activity
    message at the source level.

`BT_MESSAGE_STREAM_ACTIVITY_CLOCK_SNAPSHOT_STATE_INFINITE`:
    The stream is considered to have always existed (for a stream
    activity beginning message) or to exist forever (for a stream
    activity end message).

    A stream activity message with such a default clock snapshot state
    must either immediately follow a stream beginning message or
    immediately precede a stream end message.

You can set an explicit default clock snapshot state with:

* bt_message_stream_activity_beginning_set_default_clock_snapshot_state()
* bt_message_stream_activity_end_set_default_clock_snapshot_state()

bt_message_stream_activity_beginning_borrow_default_clock_snapshot_const()
and bt_message_stream_activity_end_borrow_default_clock_snapshot_const()
return the default clock snapshot's state.

Also in this patch: refactor the packet beginning/end and stream
beginning/end messages to avoid code duplication, and put the functions
in their own header file.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
32 files changed:
include/Makefile.am
include/babeltrace/babeltrace.h
include/babeltrace/graph/message-const.h
include/babeltrace/graph/message-internal.h
include/babeltrace/graph/message-packet-beginning-const.h [new file with mode: 0644]
include/babeltrace/graph/message-packet-beginning.h [new file with mode: 0644]
include/babeltrace/graph/message-packet-const.h [deleted file]
include/babeltrace/graph/message-packet-end-const.h [new file with mode: 0644]
include/babeltrace/graph/message-packet-end.h [new file with mode: 0644]
include/babeltrace/graph/message-packet-internal.h
include/babeltrace/graph/message-packet.h [deleted file]
include/babeltrace/graph/message-stream-activity-beginning-const.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-activity-beginning.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-activity-const.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-activity-end-const.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-activity-end.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-activity-internal.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-beginning-const.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-beginning.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-const.h [deleted file]
include/babeltrace/graph/message-stream-end-const.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-end.h [new file with mode: 0644]
include/babeltrace/graph/message-stream-internal.h
include/babeltrace/graph/message-stream.h [deleted file]
lib/graph/graph.c
lib/graph/iterator.c
lib/graph/message/Makefile.am
lib/graph/message/message.c
lib/graph/message/packet.c
lib/graph/message/stream-activity.c [new file with mode: 0644]
lib/graph/message/stream.c
lib/lib-logging.c
This page took 0.027853 seconds and 4 git commands to generate.