lib: add stream activity beginning/end messages
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Fri, 8 Feb 2019 22:36:38 +0000 (17:36 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Fri, 3 May 2019 22:19:37 +0000 (18:19 -0400)
commita1f053a957f7ddce25c8a4e96e3d7aa9fa8cc30b
tree90fd76096d61dd2c46a892db2e6511ffc042053f
parentb37345369d0a5a8d31934d1edb76f723a88f0038
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.026777 seconds and 4 git commands to generate.