lib: make packets and packet messages optional, disabled by default
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Mon, 8 Jul 2019 16:33:30 +0000 (12:33 -0400)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Thu, 18 Jul 2019 15:53:34 +0000 (11:53 -0400)
commit37a93d415ba5a4d839a89157d91496f21c367a96
tree199496d6f6e532bb33226f67076fdcab1a5c1819
parente868448768db5bda285075e29cf21b8357f49874
lib: make packets and packet messages optional, disabled by default

This patch makes it optional for the streams of a given stream class to
support the concept of packets, much like the support for discarded
events and discarded packets is already optional.

Packets exist to support trace formats which group events into packets,
all the packet's events sharing the same packet context information. CTF
is currently the single input format which needs the packet concept.
Other, more simple sources (existing and future) which do not need the
packet concept need, before this patch, to create at least one and, for
each stream, to emit the packet beginning and packet end messages at the
right locations within the message flow. This makes this part of the API
cumbersome and unnecessary.

With this patch, a message iterator can simply emit:

1. Stream beginning message
2. Event messages
3. Stream end message

API changes
===========
When you create a stream class with bt_stream_class_create() or
bt_stream_class_create_with_id(), the created stream class does NOT
support packets by default. This is to make the initial stream class's
configuration as simple as possible. This means that:

* You cannot create packet objects from the instances of this stream
  class (bt_packet_create()).

* You cannot create packet beginning and packet end messages for the
  instances of this stream class because you don't have any packet
  object (bt_message_packet_beginning_create(),
  bt_message_packet_beginning_create_with_default_clock_snapshot(),
  bt_message_packet_end_create(), and
  bt_message_packet_end_create_with_default_clock_snapshot()).

* The stream class cannot support discarded packets
  (bt_stream_class_set_supports_discarded_packets()).

* The stream class cannot have a packet context field class
  (bt_stream_class_set_packet_context_field_class()).

* You cannot create a detached packet context field from this stream
  class (bt_packet_context_field_create()).

* You cannot create an event message with a packet object
  (bt_message_event_create() and
  bt_message_event_create_with_default_clock_snapshot(); more about this
  below).

To make a stream class support packets, you need to call
bt_stream_class_set_supports_packets(). This is also where you specify
whether or not the stream class's stream packets have a beginning and/or
an end default clock snapshot from now on.

You can use bt_stream_class_supports_packets() to know if a given stream
class supports packets.

The functions bt_message_event_create() and
bt_message_event_create_with_default_clock_snapshot() are renamed to
bt_message_event_create_with_packet() and
bt_message_event_create_with_packet_and_default_clock_snapshot(). The
functions bt_message_event_create() and
bt_message_event_create_with_default_clock_snapshot() now accept a
`const bt_stream *` parameter to associate the event to a stream.

You can borrow the stream to which an event is associated with
bt_event_borrow_stream_const(), however it was created.
bt_event_borrow_packet_const() returns `NULL` if the event's stream
class does not support packets.

When a stream class supports packets, it is required that you emit the
packet beginning and packet end messages at the correct locations within
an iterator's message flow for a given instance of this stream class.

When a stream class does not support packets, it is required that you do
not create packet beginning and packet end messages for the instances of
this stream class.

Plugin changes
==============
`src.ctf.fs` and `src.ctf.lttng-live`:
    The message iterators always create stream classes supporting
    packets.

`sink.ctf.fs`:
    The component requires that packets are supported if a stream class
    also supports discarded events. This is because the way to indicate
    discarded events in CTF 1.8 is with packet contexts.

    When packets are not supported for a given stream, the component
    creates "artificial" packets. I chose to make it create packets of
    about 4 MiB. This could become configurable in the future.

`flt.lttng-utils.debug-info`:
    The message iterator copies whether or not the stream class supports
    packets.

`src.text.dmesg`:
    The message iterator does not emit packet beginning and end messages
    anymore.

`sink.text.details`:
    The component prints whether or not a given stream class supports
    packets. The component only prints the "packets have beginning
    default clock snapshot" and "packets have end default clock
    snapshot" stream class properties if packets are supported to reduce
    textual noise.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I79a8063b4a85140004789d024364cf37ef076c45
Reviewed-on: https://review.lttng.org/c/babeltrace/+/1656
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>
46 files changed:
include/babeltrace2/graph/message-event.h
include/babeltrace2/trace-ir/stream-class-const.h
include/babeltrace2/trace-ir/stream-class.h
src/bindings/python/bt2/bt2/__init__.py.in
src/bindings/python/bt2/bt2/event.py
src/bindings/python/bt2/bt2/message.py
src/bindings/python/bt2/bt2/message_iterator.py
src/bindings/python/bt2/bt2/stream.py
src/bindings/python/bt2/bt2/stream_class.py
src/bindings/python/bt2/bt2/trace_class.py
src/lib/graph/message/event.c
src/lib/graph/message/packet.c
src/lib/lib-logging.c
src/lib/trace-ir/event.c
src/lib/trace-ir/event.h
src/lib/trace-ir/packet-context-field.c
src/lib/trace-ir/packet.c
src/lib/trace-ir/stream-class.c
src/lib/trace-ir/stream-class.h
src/plugins/ctf/common/metadata/ctf-meta-translate.c
src/plugins/ctf/common/msg-iter/msg-iter.c
src/plugins/ctf/fs-sink/fs-sink-ctf-meta.h
src/plugins/ctf/fs-sink/fs-sink-stream.c
src/plugins/ctf/fs-sink/fs-sink-stream.h
src/plugins/ctf/fs-sink/fs-sink.c
src/plugins/lttng-utils/debug-info/debug-info.c
src/plugins/lttng-utils/debug-info/trace-ir-metadata-copy.c
src/plugins/text/details/write.c
src/plugins/text/dmesg/dmesg.c
src/plugins/text/pretty/print.c
src/plugins/utils/trimmer/trimmer.c
tests/bindings/python/bt2/test_clock_class.py
tests/bindings/python/bt2/test_event.py
tests/bindings/python/bt2/test_field.py
tests/bindings/python/bt2/test_field_class.py
tests/bindings/python/bt2/test_graph.py
tests/bindings/python/bt2/test_message.py
tests/bindings/python/bt2/test_message_iterator.py
tests/bindings/python/bt2/test_packet.py
tests/bindings/python/bt2/test_stream_class.py
tests/data/plugins/flt.utils.trimmer/bt_plugin_trimmer_test.py
tests/data/plugins/sink.ctf.fs/succeed/trace-double.expect
tests/data/plugins/sink.ctf.fs/succeed/trace-float.expect
tests/data/plugins/src.ctf.fs/succeed/trace-simple.expect
tests/data/plugins/src.ctf.fs/succeed/trace-smalltrace.expect
tests/lib/test_trace_ir_ref.c
This page took 0.033106 seconds and 4 git commands to generate.