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:
This page took 0.029436 seconds and 4 git commands to generate.