2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_MESSAGE_H
8 #define BABELTRACE2_GRAPH_MESSAGE_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-msg Messages
24 @ingroup api-comp-cls-dev
27 Elements exchanged between \bt_p_comp.
29 <strong><em>Messages</em></strong> are the objects which are exchanged
30 between \bt_p_comp in a trace processing \bt_graph to accomplish a
33 \bt_cp_msg_iter create messages while message iterators \em and
34 \bt_p_sink_comp consume messages.
36 There are eight types of messages:
47 The type of a message is #bt_message.
49 Get the type enumerator of a message with bt_message_get_type().
51 A message is a \ref api-fund-shared-object "shared object": get a
52 new reference with bt_message_get_ref() and put an existing
53 reference with bt_message_put_ref().
55 Some library functions \ref api-fund-freezing "freeze" messages on
56 success. The documentation of those functions indicate this
59 Messages transport objects of the \ref api-tir API, which is an
60 intermediate representation of the tracing domain concepts.
62 All types of messages, except the \bt_inac_msg type, are related to a
63 specific <em>\bt_stream</em>, which represents a conceptual
64 \ref api-msg-seq "sequence of messages".
66 Some types of messages can have a default \bt_cs, depending on whether
67 or not their stream has a conceptual default clock, that is, whether or
68 not the stream's \ref api-tir-stream-cls "class" has a
69 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
70 The creation functions for those types of messages contain
71 <code>_with_default_clock_snapshot</code> (for example,
72 bt_message_event_create_with_default_clock_snapshot()).
74 For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
75 is optional, therefore they have dedicated
76 bt_message_stream_beginning_set_default_clock_snapshot() and
77 bt_message_stream_end_set_default_clock_snapshot() functions.
79 All the message creation functions take a \bt_self_msg_iter as their
80 first parameter. This is because a message iterator method is the only
81 valid context to create a message.
83 <h1>Message types</h1>
85 This section details each type of message.
87 The following table shows the creation functions and types for each type
94 <th>Creation functions
96 <td>\ref api-msg-sb "Stream beginning"
97 <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
98 <td>bt_message_stream_beginning_create()
100 <td>\ref api-msg-se "Stream end"
101 <td>#BT_MESSAGE_TYPE_STREAM_END
102 <td>bt_message_stream_end_create()
104 <td>\ref api-msg-ev "Event"
105 <td>#BT_MESSAGE_TYPE_EVENT
107 bt_message_event_create()<br>
108 bt_message_event_create_with_default_clock_snapshot()<br>
109 bt_message_event_create_with_packet()<br>
110 bt_message_event_create_with_packet_and_default_clock_snapshot()
112 <td>\ref api-msg-pb "Packet beginning"
113 <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
115 bt_message_packet_beginning_create()<br>
116 bt_message_packet_beginning_create_with_default_clock_snapshot()
118 <td>\ref api-msg-pe "Packet end"
119 <td>#BT_MESSAGE_TYPE_PACKET_END
121 bt_message_packet_end_create()<br>
122 bt_message_packet_end_create_with_default_clock_snapshot()
124 <td>\ref api-msg-disc-ev "Discarded events"
125 <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
127 bt_message_discarded_events_create()<br>
128 bt_message_discarded_events_create_with_default_clock_snapshots()
130 <td>\ref api-msg-disc-pkt "Discarded packets"
131 <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
133 bt_message_discarded_packets_create()<br>
134 bt_message_discarded_packets_create_with_default_clock_snapshots()
136 <td>\ref api-msg-inac "Message iterator inactivity"
137 <td>#BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
138 <td>bt_message_message_iterator_inactivity_create()
141 <h2>\anchor api-msg-sb Stream beginning message</h2>
143 A <strong><em>stream beginning message</em></strong> indicates the
144 beginning of a \bt_stream.
148 - A stream beginning message is always the first one in the
149 \ref api-msg-seq "message sequence".
151 - There can be only one stream beginning message.
153 Create a stream beginning message with
154 bt_message_stream_beginning_create().
156 A stream beginning message has the following properties:
159 <dt>\anchor api-msg-sb-prop-stream Stream</dt>
161 \bt_c_stream of which the message indicates the beginning.
163 You cannot change the stream once the message is created.
165 Borrow a stream beginning message's stream with
166 bt_message_stream_beginning_borrow_stream() and
167 bt_message_stream_beginning_borrow_stream_const().
171 \anchor api-msg-sb-prop-cs
172 \bt_dt_opt Default \bt_cs
175 Snapshot of the message's \bt_stream's default clock when the
178 A stream beginning message can only have a default clock snapshot
179 if its stream's \ref api-tir-stream-cls "class" has a
180 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
182 When a stream beginning message has no default clock snapshot,
183 then its time is <em>unknown</em>.
185 Set a stream beginning message's default clock snapshot with
186 bt_message_stream_beginning_set_default_clock_snapshot().
188 Borrow a stream beginning message's default clock snapshot with
189 bt_message_stream_beginning_borrow_default_clock_snapshot_const().
193 <h2>\anchor api-msg-se Stream end message</h2>
195 A <strong><em>stream end message</em></strong> indicates the
200 - A stream end message is always the last one in the
201 \ref api-msg-seq "message sequence".
203 - There can be only one stream end message.
205 Create a stream end message with bt_message_stream_end_create().
207 A stream end message has the following properties:
210 <dt>\anchor api-msg-se-prop-stream Stream</dt>
212 \bt_c_stream of which the message indicates the end.
214 You cannot change the stream once the message is created.
216 Borrow a stream end message's stream with
217 bt_message_stream_end_borrow_stream() and
218 bt_message_stream_end_borrow_stream_const().
222 \anchor api-msg-se-prop-cs
223 \bt_dt_opt Default \bt_cs
226 Snapshot of the message's \bt_stream's default clock when the
229 A stream end message can only have a default clock snapshot
230 if its stream's \ref api-tir-stream-cls "class" has a
231 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
233 When a stream end message has no default clock snapshot, then its
234 time is <em>unknown</em>.
236 Set a stream end message's default clock snapshot with
237 bt_message_stream_end_set_default_clock_snapshot().
239 Borrow a stream end message's default clock snapshot with
240 bt_message_stream_end_borrow_default_clock_snapshot_const().
244 <h2>\anchor api-msg-ev Event message</h2>
246 An <strong><em>event message</em></strong> transports an \bt_ev and has,
247 possibly, a default \bt_cs.
249 Within its \bt_stream's \ref api-msg-seq "message sequence", an event
250 message can only occur:
254 If the stream's \ref api-tir-stream-cls "class"
255 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
257 <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
260 If the stream's class does not support packets
262 <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
265 To create an event message for a given stream, use:
269 If the stream's \ref api-tir-stream-cls "class"
270 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
275 If the stream's class has a
276 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
278 <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
281 If the stream's class does not have a
282 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
284 <dd>bt_message_event_create_with_packet()</dd>
287 Those two creation functions accept a \bt_pkt parameter which is
288 the packet logically containing the message's event. A packet is
293 If the stream's class does not supports packets
298 If the stream's class has a default clock class
300 <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
303 If the stream's class does not have a
304 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
306 <dd>bt_message_event_create()</dd>
311 The four creation functions above accept an \bt_ev_cls parameter. When
312 you create the message, the library instantiates this event class as an
313 \bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
314 This event class must be part of the class of the event message's
317 An event message's event is initially <em>not set</em>: before you emit
318 the event message from a \bt_msg_iter's
319 \link api-msg-iter-cls-meth-next "next" method\endlink, you need to
320 borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
321 bt_event_borrow_specific_context_field(), and
322 bt_event_borrow_common_context_field()) and, recursively, set the values
323 of the all their inner fields.
325 An event message has the following properties:
328 <dt>\anchor api-msg-ev-prop-ev Event</dt>
330 \bt_c_ev which the message transports.
332 This is an instance of the \bt_ev_cls which was passed to the
333 message's creation function.
335 With this event, you can access its \bt_pkt (if any) with
336 bt_event_borrow_packet_const() and its
337 \bt_stream with bt_event_borrow_stream_const().
339 Borrow an event message's event with bt_message_event_borrow_event()
340 and bt_message_event_borrow_event_const().
344 \anchor api-msg-ev-prop-cs
345 \bt_dt_opt Default \bt_cs
348 Snapshot of the message's \bt_stream's default clock when the
351 An event message has a default clock snapshot
352 if its stream's \ref api-tir-stream-cls "class" has a
353 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class",
354 and has none otherwise.
356 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
357 the default clock snapshot of an event message must be greater than
358 or equal to any default clock snapshot of any previous message.
360 Borrow an event message's default clock snapshot with
361 bt_message_event_borrow_default_clock_snapshot_const().
365 <h2>\anchor api-msg-pb Packet beginning message</h2>
367 A <strong><em>packet beginning message</em></strong> indicates the
368 beginning of a \bt_pkt.
370 A packet beginning message can only exist if its \bt_stream's
371 \ref api-tir-stream-cls "class"
372 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
374 For a given packet, there can be only one packet beginning message.
376 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
377 beginning message can only occur after the \bt_sb_msg and before the
380 To create a packet beginning message for a given stream, use:
384 If, for this stream's class,
385 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
387 <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
390 If, for this stream's class, packets do not have a beginning default
393 <dd>bt_message_packet_beginning_create()</dd>
396 A packet beginning message has the following properties:
399 <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
401 \bt_c_pkt of which the message indicates the beginning.
403 You cannot change the packet once the message is created.
405 Borrow a packet beginning message's packet with
406 bt_message_packet_beginning_borrow_packet() and
407 bt_message_packet_beginning_borrow_packet_const().
411 \anchor api-msg-pb-prop-cs
412 \bt_dt_opt Default \bt_cs
415 Snapshot of the message's \bt_stream's default clock when the
418 A packet beginning message has a default clock snapshot if:
420 - Its stream's \ref api-tir-stream-cls "class" has a
421 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
423 - For its stream's class,
424 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
426 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
427 the default clock snapshot of a packet beginning message must be
428 greater than or equal to any clock snapshot of any previous message.
430 Borrow a packet beginning message's default clock snapshot with
431 bt_message_packet_beginning_borrow_default_clock_snapshot_const().
435 <h2>\anchor api-msg-pe Packet end message</h2>
437 A <strong><em>packet end message</em></strong> indicates the
440 A packet end message can only exist if its \bt_stream's
441 \ref api-tir-stream-cls "class"
442 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
444 For a given packet, there can be only one packet end message.
446 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
447 end message can only occur:
449 - After the \bt_sb_msg and before the \bt_se_msg.
450 - After a \bt_pb_msg for the same packet.
452 To create a packet end message for a given stream, use:
456 If, for this stream's class,
457 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
459 <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
462 If, for this stream's class, packets do not have an end default
465 <dd>bt_message_packet_end_create()</dd>
468 A packet end message has the following properties:
471 <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
473 \bt_c_pkt of which the message indicates the end.
475 You cannot change the packet once the message is created.
477 Borrow a packet end message's packet with
478 bt_message_packet_end_borrow_packet() and
479 bt_message_packet_end_borrow_packet_const().
483 \anchor api-msg-pe-prop-cs
484 \bt_dt_opt Default \bt_cs
487 Snapshot of the message's \bt_stream's default clock when the
490 A packet end message has a default clock snapshot if:
492 - Its stream's \ref api-tir-stream-cls "class" has a
493 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
495 - For its stream's class,
496 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
498 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
499 the default clock snapshot of a packet end message must be greater
500 than or equal to any clock snapshot of any previous message.
502 Borrow a packet end message's default clock snapshot with
503 bt_message_packet_end_borrow_default_clock_snapshot_const().
507 <h2>\anchor api-msg-disc-ev Discarded events message</h2>
509 A <strong><em>discarded events message</em></strong> indicates that
510 events were discarded at <em>tracing time</em>. It does \em not indicate
511 that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
513 A discarded events message can only exist if its \bt_stream's
514 \ref api-tir-stream-cls "class"
515 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events".
517 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
518 events message can only occur after the \bt_sb_msg and before the
521 To create a discarded events message for a given stream, use:
525 If, for this stream's class,
526 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
528 <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
531 If, for this stream's class, discarded events do not have default
534 <dd>bt_message_discarded_events_create()</dd>
537 A discarded events message has the following properties:
540 <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
542 \bt_c_stream into which events were discarded.
544 You cannot change the stream once the message is created.
546 Borrow a discarded events message's stream with
547 bt_message_discarded_events_borrow_stream() and
548 bt_message_discarded_events_borrow_stream_const().
552 \anchor api-msg-disc-ev-prop-cs-beg
553 \bt_dt_opt Beginning default \bt_cs
556 Snapshot of the message's \bt_stream's default clock which indicates
557 the beginning of the discarded events time range.
559 A discarded events message has a beginning default clock snapshot
562 - Its stream's \ref api-tir-stream-cls "class" has a
563 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
565 - For its stream's class,
566 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
568 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
569 the beginning default clock snapshot of a discarded events message
570 must be greater than or equal to any clock snapshot of any previous
573 Borrow a discarded events message's beginning default clock snapshot
575 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
579 \anchor api-msg-disc-ev-prop-cs-end
580 \bt_dt_opt End default \bt_cs
583 Snapshot of the message's \bt_stream's default clock which indicates
584 the end of the discarded events time range.
586 A discarded events message has an end default clock snapshot if:
588 - Its stream's \ref api-tir-stream-cls "class" has a
589 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
591 - For its stream's class,
592 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
594 If a discarded events message has both a
595 \ref api-msg-disc-ev-prop-cs-beg "beginning" and an end default
596 clock snapshots, the end default clock snapshot must be greater than
597 or equal to the beginning default clock snapshot.
599 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
600 the end default clock snapshot of a discarded events message must be
601 greater than or equal to any clock snapshot of any previous message.
603 Borrow a discarded events message's end default clock snapshot with
604 bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
608 \anchor api-msg-disc-ev-prop-count
609 \bt_dt_opt Discarded event count
612 Exact number of discarded events.
614 If this property is missing, then the number of discarded events
617 Use bt_message_discarded_events_set_count() and
618 bt_message_discarded_events_get_count().
622 <h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
624 A <strong><em>discarded packets message</em></strong> indicates that
625 packets were discarded at <em>tracing time</em>. It does \em not
626 indicate that whole packets were dropped during a trace processing
629 A discarded packets message can only exist if its \bt_stream's
630 \ref api-tir-stream-cls "class"
631 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets".
633 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
634 packets message can only occur:
636 - After the \bt_sb_msg.
637 - Before the \bt_se_msg.
639 - Before any \bt_pb_msg.
640 - After any \bt_pe_msg.
641 - Between a packet end and a packet beginning message.
643 To create a discarded packets message for a given stream, use:
647 If, for this stream's class,
648 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
650 <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
653 If, for this stream's class, discarded packets do not have default
656 <dd>bt_message_discarded_packets_create()</dd>
659 A discarded packets message has the following properties:
662 <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
664 \bt_c_stream into which packets were discarded.
666 You cannot change the stream once the message is created.
668 Borrow a discarded packets message's stream with
669 bt_message_discarded_packets_borrow_stream() and
670 bt_message_discarded_packets_borrow_stream_const().
674 \anchor api-msg-disc-pkt-prop-cs-beg
675 \bt_dt_opt Beginning default \bt_cs
678 Snapshot of the message's \bt_stream's default clock which indicates
679 the beginning of the discarded packets time range.
681 A discarded packets message has a beginning default clock snapshot
684 - Its stream's \ref api-tir-stream-cls "class" has a
685 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
687 - For its stream's class,
688 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
690 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
691 the beginning default clock snapshot of a discarded packets message
692 must be greater than or equal to any clock snapshot of any previous
695 Borrow a discarded packets message's beginning default clock snapshot
697 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
701 \anchor api-msg-disc-pkt-prop-cs-end
702 \bt_dt_opt End default \bt_cs
705 Snapshot of the message's \bt_stream's default clock which indicates
706 the end of the discarded packets time range.
708 A discarded packets message has an end default clock snapshot if:
710 - Its stream's \ref api-tir-stream-cls "class" has a
711 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
713 - For its stream's class,
714 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
716 If a discarded packets message has both a
717 \ref api-msg-disc-pkt-prop-cs-beg "beginning" and an end default
718 clock snapshots, the end default clock snapshot must be greater than
719 or equal to the beginning default clock snapshot.
721 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
722 the end default clock snapshot of a discarded packets message must
723 be greater than or equal to any clock snapshot of any previous
726 Borrow a discarded packets message's end default clock snapshot with
727 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
731 \anchor api-msg-disc-pkt-prop-count
732 \bt_dt_opt Discarded packet count
735 Exact number of discarded packets.
737 If this property is missing, then the number of discarded packets
740 Use bt_message_discarded_packets_set_count() and
741 bt_message_discarded_packets_get_count().
745 <h2>\anchor api-msg-inac Message iterator inactivity</h2>
747 A <strong><em>message iterator inactivity message</em></strong>
748 indicates that, within the \ref api-msg-seq "message sequence" of a
749 given \bt_msg_iter, there's no messages since the last message (if any)
750 until a given point in time.
752 A message iterator inactivity message is the only type of message that's
753 not related to a \bt_stream: it targets the whole message sequence of a
754 message iterator, and can occur at any position within the sequence.
756 This message is mostly significant for real-time message iterators: if a
757 message iterator A indicates that there's no messages until a given
758 point in time T, then a downstream filter message iterator B which
759 relies on multiple upstream message iterators does not have to wait for
760 new messages from A until T.
762 In other words, a message iterator inactivity message can help
763 downstream message iterators or \bt_p_sink_comp <em>progress</em>.
765 Create a message iterator inactivity message with
766 bt_message_message_iterator_inactivity_create(). You must pass a
767 \bt_clock_cls and the value of a fictitious (clock) instance to this
768 function so that it creates a \bt_cs.
770 A message iterator inactivity message has the following property:
774 \anchor api-msg-inac-prop-cs
778 Snapshot of a fictitious instance of the message's \bt_clock_cls
779 which indicates the point in time until when there's no messages
780 in the message iterator's \ref api-msg-seq "message sequence".
782 Within its \bt_msg_iter's message sequence, the clock snapshot of a
783 message iterator inactivity message must be greater than or equal to
784 any clock snapshot of any previous message.
786 Borrow a message iterator inactivity message's clock snapshot
788 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
792 <h1>\anchor api-msg-mip Message Interchange Protocol</h1>
794 The <em>Message Interchange Protocol</em> (MIP) is the system of rules
795 used by \bt_p_comp and \bt_p_msg_iter to exchange messages within a
796 trace processing graph.
798 The MIP covers everything related to messages and what they contain, as
799 well as how they are ordered within the \ref api-msg-seq "sequence" that
800 a message iterator produces.
804 - A valid message sequence for a given \bt_stream starts with a
805 \bt_sb_msg and ends with a \bt_se_msg.
808 \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
809 is [0, 2<sup>64</sup> − 1].
811 - The available message types are stream beginning and end, event,
812 packet beginning and end, discarded events and packets, and message
815 The MIP has a version which is a single major number, independent from
816 the \bt_name project's version.
818 If what the MIP covers changes in a breaking or semantical way in the
819 future, the MIP and \bt_name's minor versions will be bumped.
821 When you create a trace processing \bt_graph with bt_graph_create(), you
822 must pass the effective MIP version to use. Then, the components you
823 \ref api-graph-lc-add "add" to this graph can access this configured MIP
824 version with bt_self_component_get_graph_mip_version() and behave
825 accordingly. In other words, if the configured MIP version is 0, then a
826 component cannot use features introduced by MIP version 1. For
827 example, should the project introduce a new type of \bt_fc, the MIP
828 version would be bumped.
830 A component which cannot honor a given MIP can fail at
831 initialization time, making the corresponding
832 <code>bt_graph_add_*_component*()</code> call fail too. To avoid any
833 surprise, you can create a \bt_comp_descr_set with descriptors of the
834 components you intend to add to a trace processing graph and call
835 bt_get_greatest_operative_mip_version() or
836 bt_get_greatest_operative_mip_version_with_restriction() to get the
837 greatest (most recent) MIP version you can use.
839 To get the library's latest MIP version, use
840 bt_get_maximal_mip_version().
842 The ultimate goal of the MIP version feature is for the \bt_name project
843 to be able to introduce new features or even major breaking changes
844 without breaking existing \bt_p_comp_cls. This is especially important
845 considering that \bt_name supports \bt_p_plugin written by different
846 authors. Of course one of the project's objectives is to bump the MIP
847 version as rarely as possible. When it is required, though, it's a
848 welcome tool to make the project evolve gracefully.
850 The Message Interchange Protocol has no dedicated documentation as this
851 very message API (and its contained APIs, like \ref api-tir)
852 documentation is enough. You can consider that all the
853 functions of the message and trace IR objects have an implicit MIP
854 version \ref api-fund-pre-post "precondition". When a given
855 function documentation does not explicitly document a MIP version
856 precondition, it means that the effective MIP version has no effect on
857 said function's behaviour.
859 <h2>\anchor api-msg-seq Message sequence rules</h2>
861 The purpose of a \bt_msg_iter is to iterate a sequence of messages.
863 Those messages can be related to different \bt_p_stream:
865 @image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
867 However, for such a message sequence, the current \bt_mip
868 (version \bt_max_mip_version) dictates that:
872 For a given \bt_stream:
874 - The sequence must begin with a \bt_sb_msg.
875 - The sequence must end with a \bt_se_msg.
876 - <strong>If the stream's \ref api-tir-stream-cls "class"
877 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"</strong>:
878 - Any \bt_pb_msg must be followed with a \bt_pe_msg.
879 - All \bt_p_ev_msg must be between a packet beginning and a
881 - A \bt_disc_pkt_msg must be (one of):
882 - Before the first packet beginning message.
883 - Between a packet end message and a packet beginning message.
884 - After the last packet end message.
886 The rules above can be summarized by the following regular
890 <dt>Without packets</dt>
897 <dt>With packets</dt>
900 SB ((PB (E | DE)* PE) | DE | DP)* SE
909 <dd>\bt_c_sb_msg</dd>
912 <dd>\bt_c_se_msg</dd>
915 <dd>\bt_c_ev_msg</dd>
918 <dd>\bt_c_pb_msg</dd>
921 <dd>\bt_c_pe_msg</dd>
924 <dd>\bt_c_disc_ev_msg</dd>
927 <dd>\bt_c_disc_pkt_msg</dd>
930 For a given message iterator, for any message with a \bt_cs, its
931 clock snapshot must be greater than or equal to any clock snapshot
932 of any previous message.
934 For the scope of this rule, the clock snapshot of a \bt_disc_ev_msg
935 or of a \bt_disc_pkt_msg is its beginning default clock snapshot.
937 For a given message iterator, the \bt_p_cs of all the messages of
938 the sequence with a clock snapshot must be correlatable
939 (see \ref api-tir-clock-cls-origin "Clock value vs. clock class origin").
949 @typedef struct bt_message bt_message;
964 Message type enumerators.
966 typedef enum bt_message_type
{
971 BT_MESSAGE_TYPE_STREAM_BEGINNING
= 1 << 0,
977 BT_MESSAGE_TYPE_STREAM_END
= 1 << 1,
983 BT_MESSAGE_TYPE_EVENT
= 1 << 2,
989 BT_MESSAGE_TYPE_PACKET_BEGINNING
= 1 << 3,
995 BT_MESSAGE_TYPE_PACKET_END
= 1 << 4,
1001 BT_MESSAGE_TYPE_DISCARDED_EVENTS
= 1 << 5,
1007 BT_MESSAGE_TYPE_DISCARDED_PACKETS
= 1 << 6,
1013 BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
= 1 << 7,
1018 Returns the type enumerator of the message \bt_p{message}.
1021 Message of which to get the type enumerator
1024 Type enumerator of \bt_p{message}.
1026 @bt_pre_not_null{message}
1028 extern bt_message_type
bt_message_get_type(const bt_message
*message
)
1034 @name Common stream message
1041 bt_message_stream_beginning_borrow_default_clock_snapshot_const()
1043 bt_message_stream_end_borrow_default_clock_snapshot_const().
1045 typedef enum bt_message_stream_clock_snapshot_state
{
1050 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
= 1,
1054 Unknown (no) \bt_cs.
1056 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
= 0,
1057 } bt_message_stream_clock_snapshot_state
;
1062 @name Stream beginning message
1068 Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
1069 \bt_msg_iter \bt_p{self_message_iterator}.
1071 On success, the returned stream beginning message has the following
1079 <td>\ref api-msg-sb-prop-stream "Stream"
1082 <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
1086 @param[in] self_message_iterator
1087 Self message iterator from which to create the stream beginning
1090 Stream of which the message to create indicates the beginning.
1093 New stream beginning message reference, or \c NULL on memory error.
1095 @bt_pre_not_null{self_message_iterator}
1096 @bt_pre_not_null{stream}
1098 @bt_post_success_frozen{stream}
1101 bt_message
*bt_message_stream_beginning_create(
1102 bt_self_message_iterator
*self_message_iterator
,
1103 const bt_stream
*stream
) __BT_NOEXCEPT
;
1107 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
1109 See the \ref api-msg-sb-prop-stream "stream" property.
1112 Stream beginning message from which to borrow the stream.
1116 \em Borrowed reference of the stream of \bt_p{message}.
1118 The returned pointer remains valid as long as \bt_p{message} exists.
1121 @bt_pre_not_null{message}
1122 @bt_pre_is_sb_msg{message}
1124 @sa bt_message_stream_beginning_borrow_stream_const() —
1125 \c const version of this function.
1127 extern bt_stream
*bt_message_stream_beginning_borrow_stream(
1128 bt_message
*message
) __BT_NOEXCEPT
;
1132 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
1135 See bt_message_stream_beginning_borrow_stream().
1137 extern const bt_stream
*bt_message_stream_beginning_borrow_stream_const(
1138 const bt_message
*message
) __BT_NOEXCEPT
;
1142 Sets the value, in clock cycles, of the default \bt_cs of the
1143 \bt_sb_msg \bt_p{message} to \bt_p{value}.
1145 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1148 Stream beginning message of which to set the default clock snapshot
1149 value to \bt_p{value}.
1151 New value (clock cycles) of the default clock snapshot of
1154 @bt_pre_not_null{message}
1155 @bt_pre_hot{message}
1156 @bt_pre_is_sb_msg{message}
1158 The \bt_stream_cls of \bt_p{message} has a
1159 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1161 @sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() —
1162 Borrows the default clock snapshot of a stream beginning message.
1165 void bt_message_stream_beginning_set_default_clock_snapshot(
1166 bt_message
*message
, uint64_t value
) __BT_NOEXCEPT
;
1170 Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
1172 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1175 Stream beginning message from which to borrow the default clock
1177 @param[out] clock_snapshot
1178 <strong>If this function returns
1179 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1180 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1181 clock snapshot of \bt_p{message}.
1183 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1184 The default clock snapshot of \bt_p{message} is known and returned
1185 as \bt_p{*clock_snapshot}.
1186 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1187 \bt_p{message} has no default clock snapshot: its time is unknown.
1189 @bt_pre_not_null{message}
1190 @bt_pre_is_sb_msg{message}
1192 The \bt_stream_cls of \bt_p{message} has a
1193 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1194 @bt_pre_not_null{clock_snapshot}
1196 @sa bt_message_stream_beginning_set_default_clock_snapshot() —
1197 Sets the default clock snapshot of a stream beginning message.
1199 extern bt_message_stream_clock_snapshot_state
1200 bt_message_stream_beginning_borrow_default_clock_snapshot_const(
1201 const bt_message
*message
,
1202 const bt_clock_snapshot
**clock_snapshot
) __BT_NOEXCEPT
;
1206 Borrows the default \bt_clock_cls of the \bt_stream_cls
1207 of the \bt_sb_msg \bt_p{message}.
1209 See the stream class's
1210 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1213 This is a helper which is equivalent to
1216 bt_stream_class_borrow_default_clock_class_const(
1217 bt_stream_borrow_class_const(
1218 bt_message_stream_beginning_borrow_stream_const(message)))
1222 Stream beginning message from which to borrow its stream's class's
1223 default clock class.
1226 \em Borrowed reference of the default clock class of
1227 the stream class of \bt_p{message}, or \c NULL if none.
1229 @bt_pre_not_null{message}
1230 @bt_pre_is_sb_msg{message}
1232 extern const bt_clock_class
*
1233 bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
1234 const bt_message
*message
) __BT_NOEXCEPT
;
1239 @name Stream end message
1245 Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
1246 \bt_msg_iter \bt_p{self_message_iterator}.
1248 On success, the returned stream end message has the following
1256 <td>\ref api-msg-se-prop-stream "Stream"
1259 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1263 @param[in] self_message_iterator
1264 Self message iterator from which to create the stream end
1267 Stream of which the message to create indicates the end.
1270 New stream end message reference, or \c NULL on memory error.
1272 @bt_pre_not_null{self_message_iterator}
1273 @bt_pre_not_null{stream}
1275 @bt_post_success_frozen{stream}
1278 bt_message
*bt_message_stream_end_create(
1279 bt_self_message_iterator
*self_message_iterator
,
1280 const bt_stream
*stream
) __BT_NOEXCEPT
;
1284 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
1286 See the \ref api-msg-se-prop-stream "stream" property.
1289 Stream end message from which to borrow the stream.
1293 \em Borrowed reference of the stream of \bt_p{message}.
1295 The returned pointer remains valid as long as \bt_p{message} exists.
1298 @bt_pre_not_null{message}
1299 @bt_pre_is_se_msg{message}
1301 @sa bt_message_stream_end_borrow_stream_const() —
1302 \c const version of this function.
1304 extern bt_stream
*bt_message_stream_end_borrow_stream(
1305 bt_message
*message
) __BT_NOEXCEPT
;
1309 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
1312 See bt_message_stream_end_borrow_stream().
1314 extern const bt_stream
*bt_message_stream_end_borrow_stream_const(
1315 const bt_message
*message
) __BT_NOEXCEPT
;
1319 Sets the value, in clock cycles, of the default \bt_cs of the
1320 \bt_se_msg \bt_p{message} to \bt_p{value}.
1322 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1325 Stream end message of which to set the default clock snapshot
1326 value to \bt_p{value}.
1328 New value (clock cycles) of the default clock snapshot of
1331 @bt_pre_not_null{message}
1332 @bt_pre_hot{message}
1333 @bt_pre_is_se_msg{message}
1335 The \bt_stream_cls of \bt_p{message} has a
1336 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1338 @sa bt_message_stream_end_borrow_default_clock_snapshot_const() —
1339 Borrows the default clock snapshot of a stream end message.
1342 void bt_message_stream_end_set_default_clock_snapshot(
1343 bt_message
*message
, uint64_t value
) __BT_NOEXCEPT
;
1347 Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
1349 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1352 Stream end message from which to borrow the default clock
1354 @param[out] clock_snapshot
1355 <strong>If this function returns
1356 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1357 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1358 clock snapshot of \bt_p{message}.
1360 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1361 The default clock snapshot of \bt_p{message} is known and returned
1362 as \bt_p{*clock_snapshot}.
1363 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1364 \bt_p{message} has no default clock snapshot: its time is unknown.
1366 @bt_pre_not_null{message}
1367 @bt_pre_is_se_msg{message}
1369 The \bt_stream_cls of \bt_p{message} has a
1370 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1371 @bt_pre_not_null{clock_snapshot}
1373 @sa bt_message_stream_end_set_default_clock_snapshot() —
1374 Sets the default clock snapshot of a stream end message.
1376 extern bt_message_stream_clock_snapshot_state
1377 bt_message_stream_end_borrow_default_clock_snapshot_const(
1378 const bt_message
*message
,
1379 const bt_clock_snapshot
**clock_snapshot
) __BT_NOEXCEPT
;
1383 Borrows the default \bt_clock_cls of the \bt_stream_cls
1384 of the \bt_se_msg \bt_p{message}.
1386 See the stream class's
1387 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1390 This is a helper which is equivalent to
1393 bt_stream_class_borrow_default_clock_class_const(
1394 bt_stream_borrow_class_const(
1395 bt_message_stream_end_borrow_stream_const(message)))
1399 Stream end message from which to borrow its stream's class's
1400 default clock class.
1403 \em Borrowed reference of the default clock class of
1404 the stream class of \bt_p{message}, or \c NULL if none.
1406 @bt_pre_not_null{message}
1407 @bt_pre_is_se_msg{message}
1409 extern const bt_clock_class
*
1410 bt_message_stream_end_borrow_stream_class_default_clock_class_const(
1411 const bt_message
*message
) __BT_NOEXCEPT
;
1422 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1423 \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
1424 \bt_msg_iter \bt_p{self_message_iterator}.
1428 Only use this function if
1431 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1434 returns #BT_FALSE and
1437 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1443 bt_message_event_create_with_default_clock_snapshot(),
1444 bt_message_event_create_with_packet(), or
1445 bt_message_event_create_with_packet_and_default_clock_snapshot().
1448 On success, the returned event message has the following property
1456 <td>\ref api-msg-ev-prop-ev "Event"
1458 An instance (with \bt_p_field that are not set) of
1461 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1465 @param[in] self_message_iterator
1466 Self message iterator from which to create the event message.
1467 @param[in] event_class
1468 Class of the \bt_ev of the message to create.
1470 Stream conceptually containing the event of the message to create.
1473 New event message reference, or \c NULL on memory error.
1475 @bt_pre_not_null{self_message_iterator}
1477 The \bt_stream_cls of \bt_p{event_class} is also the class of
1478 \bt_p{stream}, that is,
1479 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1481 <code>bt_stream_borrow_class_const(stream)</code> have the
1483 @bt_pre_not_null{stream}
1485 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1488 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1491 @bt_post_success_frozen{event_class}
1492 @bt_post_success_frozen{stream}
1495 bt_message
*bt_message_event_create(
1496 bt_self_message_iterator
*self_message_iterator
,
1497 const bt_event_class
*event_class
,
1498 const bt_stream
*stream
) __BT_NOEXCEPT
;
1502 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1503 \bt_p{event_class} and a default \bt_cs with the value
1504 \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
1505 the \bt_msg_iter \bt_p{self_message_iterator}.
1509 Only use this function if
1512 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1515 returns #BT_FALSE and
1518 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1521 does \em not return \c NULL.
1524 bt_message_event_create(),
1525 bt_message_event_create_with_packet(), or
1526 bt_message_event_create_with_packet_and_default_clock_snapshot().
1529 On success, the returned event message has the following property
1537 <td>\ref api-msg-ev-prop-ev "Event"
1539 An instance (with \bt_p_field that are not set) of
1542 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1543 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1546 @param[in] self_message_iterator
1547 Self message iterator from which to create the event message.
1548 @param[in] event_class
1549 Class of the \bt_ev of the message to create.
1551 Stream conceptually containing the event of the message to create.
1552 @param[in] clock_snapshot_value
1553 Value (clock cycles) of the default clock snapshot of
1557 New event message reference, or \c NULL on memory error.
1559 @bt_pre_not_null{self_message_iterator}
1561 The \bt_stream_cls of \bt_p{event_class} is also the class of
1562 \bt_p{stream}, that is,
1563 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1565 <code>bt_stream_borrow_class_const(stream)</code> have the
1567 @bt_pre_not_null{stream}
1569 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1572 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1573 does \em not return \c NULL.
1575 @bt_post_success_frozen{event_class}
1576 @bt_post_success_frozen{stream}
1579 bt_message
*bt_message_event_create_with_default_clock_snapshot(
1580 bt_self_message_iterator
*self_message_iterator
,
1581 const bt_event_class
*event_class
,
1582 const bt_stream
*stream
, uint64_t clock_snapshot_value
)
1587 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1588 \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
1589 \bt_msg_iter \bt_p{self_message_iterator}.
1593 Only use this function if
1596 bt_stream_class_supports_packets(
1597 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1600 returns #BT_TRUE and
1603 bt_stream_class_borrow_default_clock_class_const(
1604 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1610 bt_message_event_create(),
1611 bt_message_event_create_with_default_clock_snapshot(), or
1612 bt_message_event_create_with_packet_and_default_clock_snapshot().
1615 On success, the returned event message has the following property
1623 <td>\ref api-msg-ev-prop-ev "Event"
1625 An instance (with \bt_p_field that are not set) of
1628 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1632 @param[in] self_message_iterator
1633 Self message iterator from which to create the event message.
1634 @param[in] event_class
1635 Class of the \bt_ev of the message to create.
1637 Packet conceptually containing the event of the message to create.
1640 New event message reference, or \c NULL on memory error.
1642 @bt_pre_not_null{self_message_iterator}
1644 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1645 \bt_p{packet}, that is,
1646 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1648 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1649 have the same value.
1650 @bt_pre_not_null{packet}
1652 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1655 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1658 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1659 any, and all its contained \bt_p_field, recursively, are set.
1661 @bt_post_success_frozen{event_class}
1662 @bt_post_success_frozen{packet}
1665 bt_message
*bt_message_event_create_with_packet(
1666 bt_self_message_iterator
*self_message_iterator
,
1667 const bt_event_class
*event_class
,
1668 const bt_packet
*packet
) __BT_NOEXCEPT
;
1672 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1673 \bt_p{event_class} and a default \bt_cs with the value
1674 \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
1675 the \bt_msg_iter \bt_p{self_message_iterator}.
1679 Only use this function if
1682 bt_stream_class_supports_packets(
1683 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1686 returns #BT_TRUE and
1689 bt_stream_class_borrow_default_clock_class_const(
1690 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1693 does \em not return \c NULL.
1696 bt_message_event_create(),
1697 bt_message_event_create_with_default_clock_snapshot(), or
1698 bt_message_event_create_with_packet().
1701 On success, the returned event message has the following property
1709 <td>\ref api-msg-ev-prop-ev "Event"
1711 An instance (with \bt_p_field that are not set) of
1714 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1715 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1718 @param[in] self_message_iterator
1719 Self message iterator from which to create the event message.
1720 @param[in] event_class
1721 Class of the \bt_ev of the message to create.
1723 Packet conceptually containing the event of the message to create.
1724 @param[in] clock_snapshot_value
1725 Value (clock cycles) of the default clock snapshot of
1729 New event message reference, or \c NULL on memory error.
1731 @bt_pre_not_null{self_message_iterator}
1733 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1734 \bt_p{packet}, that is,
1735 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1737 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1738 have the same value.
1739 @bt_pre_not_null{packet}
1741 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1744 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1745 does \em not return \c NULL.
1747 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1748 any, and all its contained \bt_p_field, recursively, are set.
1750 @bt_post_success_frozen{event_class}
1751 @bt_post_success_frozen{stream}
1754 bt_message
*bt_message_event_create_with_packet_and_default_clock_snapshot(
1755 bt_self_message_iterator
*self_message_iterator
,
1756 const bt_event_class
*event_class
,
1757 const bt_packet
*packet
, uint64_t clock_snapshot_value
)
1762 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
1764 See the \ref api-msg-ev-prop-ev "event" property.
1767 Event message from which to borrow the event.
1771 \em Borrowed reference of the event of \bt_p{message}.
1773 The returned pointer remains valid as long as \bt_p{message} exists.
1776 @bt_pre_not_null{message}
1777 @bt_pre_is_ev_msg{message}
1779 @sa bt_message_event_borrow_event_const() —
1780 \c const version of this function.
1782 extern bt_event
*bt_message_event_borrow_event(bt_message
*message
)
1787 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
1790 See bt_message_event_borrow_event().
1792 extern const bt_event
*bt_message_event_borrow_event_const(
1793 const bt_message
*message
) __BT_NOEXCEPT
;
1797 Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
1799 See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
1802 Event message from which to borrow the default clock snapshot.
1805 Default clock snapshot of \bt_p{message}.
1807 @bt_pre_not_null{message}
1808 @bt_pre_is_ev_msg{message}
1810 The \bt_stream_cls of \bt_p{message} has a
1811 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1813 extern const bt_clock_snapshot
*
1814 bt_message_event_borrow_default_clock_snapshot_const(const bt_message
*message
)
1819 Borrows the default \bt_clock_cls of the \bt_stream_cls
1820 of the \bt_ev_msg \bt_p{message}.
1822 See the stream class's
1823 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1826 This is a helper which is equivalent to
1829 bt_stream_class_borrow_default_clock_class_const(
1830 bt_stream_borrow_class_const(
1831 bt_event_borrow_stream_const(
1832 bt_message_event_borrow_event_const(message))))
1836 Event message from which to borrow its stream's class's
1837 default clock class.
1840 \em Borrowed reference of the default clock class of
1841 the stream class of \bt_p{message}, or \c NULL if none.
1843 @bt_pre_not_null{message}
1844 @bt_pre_is_ev_msg{message}
1846 extern const bt_clock_class
*
1847 bt_message_event_borrow_stream_class_default_clock_class_const(
1848 const bt_message
*message
) __BT_NOEXCEPT
;
1853 @name Packet beginning message
1859 Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
1860 \bt_msg_iter \bt_p{self_message_iterator}.
1864 Only use this function if
1867 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1868 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1874 bt_message_packet_beginning_create_with_default_clock_snapshot().
1877 On success, the returned packet beginning message has the following
1885 <td>\ref api-msg-pb-prop-pkt "Packet"
1888 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1892 @param[in] self_message_iterator
1893 Self message iterator from which to create the packet beginning
1896 Packet of which the message to create indicates the beginning.
1899 New packet beginning message reference, or \c NULL on memory error.
1901 @bt_pre_not_null{self_message_iterator}
1902 @bt_pre_not_null{packet}
1904 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1905 returns #BT_FALSE for
1906 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1908 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1909 any, and all its contained \bt_p_field, recursively, are set.
1911 @bt_post_success_frozen{packet}
1914 bt_message
*bt_message_packet_beginning_create(
1915 bt_self_message_iterator
*self_message_iterator
,
1916 const bt_packet
*packet
) __BT_NOEXCEPT
;
1920 Creates a \bt_pb_msg having a default \bt_cs with the value
1921 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
1922 \bt_msg_iter \bt_p{self_message_iterator}.
1926 Only use this function if
1929 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1930 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1936 bt_message_packet_beginning_create().
1939 On success, the returned packet beginning message has the following
1947 <td>\ref api-msg-pb-prop-pkt "Packet"
1950 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1951 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1954 @param[in] self_message_iterator
1955 Self message iterator from which to create the packet beginning
1958 Packet of which the message to create indicates the beginning.
1959 @param[in] clock_snapshot_value
1960 Value (clock cycles) of the default clock snapshot of
1964 New packet beginning message reference, or \c NULL on memory error.
1966 @bt_pre_not_null{self_message_iterator}
1967 @bt_pre_not_null{packet}
1969 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1970 returns #BT_TRUE for
1971 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1973 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1974 any, and all its contained \bt_p_field, recursively, are set.
1976 @bt_post_success_frozen{packet}
1979 bt_message
*bt_message_packet_beginning_create_with_default_clock_snapshot(
1980 bt_self_message_iterator
*self_message_iterator
,
1981 const bt_packet
*packet
, uint64_t clock_snapshot_value
)
1986 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
1988 See the \ref api-msg-pb-prop-pkt "packet" property.
1991 Packet beginning message from which to borrow the packet.
1995 \em Borrowed reference of the packet of \bt_p{message}.
1997 The returned pointer remains valid as long as \bt_p{message} exists.
2000 @bt_pre_not_null{message}
2001 @bt_pre_is_pb_msg{message}
2003 @sa bt_message_packet_beginning_borrow_packet_const() —
2004 \c const version of this function.
2006 extern bt_packet
*bt_message_packet_beginning_borrow_packet(
2007 bt_message
*message
) __BT_NOEXCEPT
;
2011 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
2014 See bt_message_packet_beginning_borrow_packet().
2016 extern const bt_packet
*bt_message_packet_beginning_borrow_packet_const(
2017 const bt_message
*message
) __BT_NOEXCEPT
;
2021 Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
2023 See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
2026 Packet beginning message from which to borrow the default clock
2030 Default clock snapshot of \bt_p{message}.
2032 @bt_pre_not_null{message}
2033 @bt_pre_is_pb_msg{message}
2035 The packets of the \bt_stream_cls of \bt_p{message}
2036 \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
2038 extern const bt_clock_snapshot
*
2039 bt_message_packet_beginning_borrow_default_clock_snapshot_const(
2040 const bt_message
*message
) __BT_NOEXCEPT
;
2044 Borrows the default \bt_clock_cls of the \bt_stream_cls
2045 of the \bt_pb_msg \bt_p{message}.
2047 See the stream class's
2048 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2051 This is a helper which is equivalent to
2054 bt_stream_class_borrow_default_clock_class_const(
2055 bt_stream_borrow_class_const(
2056 bt_packet_borrow_stream_const(
2057 bt_message_packet_beginning_borrow_packet_const(message))))
2061 Packet beginning message from which to borrow its stream's class's
2062 default clock class.
2065 \em Borrowed reference of the default clock class of
2066 the stream class of \bt_p{message}, or \c NULL if none.
2068 @bt_pre_not_null{message}
2069 @bt_pre_is_pb_msg{message}
2071 extern const bt_clock_class
*
2072 bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
2073 const bt_message
*message
) __BT_NOEXCEPT
;
2078 @name Packet end message
2084 Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
2085 \bt_msg_iter \bt_p{self_message_iterator}.
2089 Only use this function if
2092 bt_stream_class_packets_have_end_default_clock_snapshot(
2093 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2099 bt_message_packet_end_create_with_default_clock_snapshot().
2102 On success, the returned packet end message has the following
2110 <td>\ref api-msg-pe-prop-pkt "Packet"
2113 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2117 @param[in] self_message_iterator
2118 Self message iterator from which to create the packet end message.
2120 Packet of which the message to create indicates the end.
2123 New packet end message reference, or \c NULL on memory error.
2125 @bt_pre_not_null{self_message_iterator}
2126 @bt_pre_not_null{packet}
2128 bt_stream_class_packets_have_end_default_clock_snapshot()
2129 returns #BT_FALSE for
2130 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2132 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2133 any, and all its contained \bt_p_field, recursively, are set.
2135 @bt_post_success_frozen{packet}
2138 bt_message
*bt_message_packet_end_create(
2139 bt_self_message_iterator
*self_message_iterator
,
2140 const bt_packet
*packet
) __BT_NOEXCEPT
;
2144 Creates a \bt_pe_msg having a default \bt_cs with the value
2145 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
2146 \bt_msg_iter \bt_p{self_message_iterator}.
2150 Only use this function if
2153 bt_stream_class_packets_have_end_default_clock_snapshot(
2154 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2160 bt_message_packet_end_create().
2163 On success, the returned packet end message has the following
2171 <td>\ref api-msg-pe-prop-pkt "Packet"
2174 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2175 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
2178 @param[in] self_message_iterator
2179 Self message iterator from which to create the packet end
2182 Packet of which the message to create indicates the end.
2183 @param[in] clock_snapshot_value
2184 Value (clock cycles) of the default clock snapshot of
2188 New packet end message reference, or \c NULL on memory error.
2190 @bt_pre_not_null{self_message_iterator}
2191 @bt_pre_not_null{packet}
2193 bt_stream_class_packets_have_end_default_clock_snapshot()
2194 returns #BT_TRUE for
2195 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2197 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2198 any, and all its contained \bt_p_field, recursively, are set.
2200 @bt_post_success_frozen{packet}
2203 bt_message
*bt_message_packet_end_create_with_default_clock_snapshot(
2204 bt_self_message_iterator
*self_message_iterator
,
2205 const bt_packet
*packet
, uint64_t clock_snapshot_value
)
2210 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
2212 See the \ref api-msg-pe-prop-pkt "packet" property.
2215 Packet end message from which to borrow the packet.
2219 \em Borrowed reference of the packet of \bt_p{message}.
2221 The returned pointer remains valid as long as \bt_p{message} exists.
2224 @bt_pre_not_null{message}
2225 @bt_pre_is_pe_msg{message}
2227 @sa bt_message_packet_end_borrow_packet_const() —
2228 \c const version of this function.
2230 extern bt_packet
*bt_message_packet_end_borrow_packet(
2231 bt_message
*message
) __BT_NOEXCEPT
;
2235 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
2238 See bt_message_packet_end_borrow_packet().
2240 extern const bt_packet
*bt_message_packet_end_borrow_packet_const(
2241 const bt_message
*message
) __BT_NOEXCEPT
;
2245 Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
2247 See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
2250 Packet end message from which to borrow the default clock
2254 Default clock snapshot of \bt_p{message}.
2256 @bt_pre_not_null{message}
2257 @bt_pre_is_pe_msg{message}
2259 The packets of the \bt_stream_cls of \bt_p{message}
2260 \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
2262 extern const bt_clock_snapshot
*
2263 bt_message_packet_end_borrow_default_clock_snapshot_const(
2264 const bt_message
*message
) __BT_NOEXCEPT
;
2268 Borrows the default \bt_clock_cls of the \bt_stream_cls
2269 of the \bt_pe_msg \bt_p{message}.
2271 See the stream class's
2272 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2275 This is a helper which is equivalent to
2278 bt_stream_class_borrow_default_clock_class_const(
2279 bt_stream_borrow_class_const(
2280 bt_packet_borrow_stream_const(
2281 bt_message_packet_end_borrow_packet_const(message))))
2285 Packet end message from which to borrow its stream's class's
2286 default clock class.
2289 \em Borrowed reference of the default clock class of
2290 the stream class of \bt_p{message}, or \c NULL if none.
2292 @bt_pre_not_null{message}
2293 @bt_pre_is_pe_msg{message}
2295 extern const bt_clock_class
*
2296 bt_message_packet_end_borrow_stream_class_default_clock_class_const(
2297 const bt_message
*message
) __BT_NOEXCEPT
;
2302 @name Discarded events message
2308 Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
2309 \bt_msg_iter \bt_p{self_message_iterator}.
2313 Only use this function if
2316 bt_stream_class_discarded_events_have_default_clock_snapshots(
2317 bt_stream_borrow_class_const(stream))
2323 bt_message_discarded_events_create_with_default_clock_snapshots().
2326 On success, the returned discarded events message has the following
2334 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2337 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2340 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2343 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2347 @param[in] self_message_iterator
2348 Self message iterator from which to create the discarded events
2351 Stream from which the events were discarded.
2354 New discarded events message reference, or \c NULL on memory error.
2356 @bt_pre_not_null{self_message_iterator}
2357 @bt_pre_not_null{stream}
2359 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2362 @bt_post_success_frozen{stream}
2364 extern bt_message
*bt_message_discarded_events_create(
2365 bt_self_message_iterator
*self_message_iterator
,
2366 const bt_stream
*stream
) __BT_NOEXCEPT
;
2370 Creates a \bt_disc_ev_msg having the beginning and end default
2371 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2372 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2373 from the \bt_msg_iter \bt_p{self_message_iterator}.
2377 Only use this function if
2380 bt_stream_class_discarded_events_have_default_clock_snapshots(
2381 bt_stream_borrow_class_const(stream))
2387 bt_message_discarded_events_create().
2390 On success, the returned discarded events message has the following
2398 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2401 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2402 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2404 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2405 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2407 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2411 @param[in] self_message_iterator
2412 Self message iterator from which to create the discarded events
2415 Stream from which the events were discarded.
2416 @param[in] beginning_clock_snapshot_value
2417 Value (clock cycles) of the beginning default clock snapshot of
2419 @param[in] end_clock_snapshot_value
2420 Value (clock cycles) of the end default clock snapshot of
2424 New discarded events message reference, or \c NULL on memory error.
2426 @bt_pre_not_null{self_message_iterator}
2427 @bt_pre_not_null{stream}
2429 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2431 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2433 @bt_post_success_frozen{stream}
2435 extern bt_message
*bt_message_discarded_events_create_with_default_clock_snapshots(
2436 bt_self_message_iterator
*self_message_iterator
,
2437 const bt_stream
*stream
,
2438 uint64_t beginning_clock_snapshot_value
,
2439 uint64_t end_clock_snapshot_value
)
2444 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2446 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2449 Discarded events message from which to borrow the stream.
2453 \em Borrowed reference of the stream of \bt_p{message}.
2455 The returned pointer remains valid as long as \bt_p{message} exists.
2458 @bt_pre_not_null{message}
2459 @bt_pre_is_disc_ev_msg{message}
2461 @sa bt_message_discarded_events_borrow_stream_const() —
2462 \c const version of this function.
2464 extern bt_stream
*bt_message_discarded_events_borrow_stream(
2465 bt_message
*message
) __BT_NOEXCEPT
;
2469 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2472 See bt_message_discarded_events_borrow_stream().
2474 extern const bt_stream
*
2475 bt_message_discarded_events_borrow_stream_const(const bt_message
*message
)
2480 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2484 \ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2488 Discarded events message from which to borrow the beginning default
2492 Beginning default clock snapshot of \bt_p{message}.
2494 @bt_pre_not_null{message}
2495 @bt_pre_is_disc_ev_msg{message}
2497 The discarded packets messages of the \bt_stream_cls of
2499 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2501 extern const bt_clock_snapshot
*
2502 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
2503 const bt_message
*message
) __BT_NOEXCEPT
;
2507 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2511 \ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2515 Discarded events message from which to borrow the end default clock
2519 End default clock snapshot of \bt_p{message}.
2521 @bt_pre_not_null{message}
2522 @bt_pre_is_disc_ev_msg{message}
2524 The discarded packets messages of the \bt_stream_cls of
2526 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2528 extern const bt_clock_snapshot
*
2529 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
2530 const bt_message
*message
) __BT_NOEXCEPT
;
2534 Borrows the default \bt_clock_cls of the \bt_stream_cls
2535 of the \bt_disc_ev_msg \bt_p{message}.
2537 See the stream class's
2538 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2541 This is a helper which is equivalent to
2544 bt_stream_class_borrow_default_clock_class_const(
2545 bt_stream_borrow_class_const(
2546 bt_message_discarded_events_borrow_stream_const(message)))
2550 Discarded events message from which to borrow its stream's class's
2551 default clock class.
2554 \em Borrowed reference of the default clock class of
2555 the stream class of \bt_p{message}, or \c NULL if none.
2557 @bt_pre_not_null{message}
2558 @bt_pre_is_disc_ev_msg{message}
2560 extern const bt_clock_class
*
2561 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
2562 const bt_message
*message
) __BT_NOEXCEPT
;
2566 Sets the number of discarded events of the \bt_disc_ev_msg
2567 \bt_p{message} to \bt_p{count}.
2569 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2573 Discarded events message of which to set the number of discarded
2574 events to \bt_p{count}.
2576 New number of discarded events of \bt_p{message}.
2578 @bt_pre_not_null{message}
2579 @bt_pre_hot{message}
2580 @bt_pre_is_disc_ev_msg{message}
2584 @sa bt_message_discarded_events_get_count() —
2585 Returns the number of discarded events of a discarded events
2588 extern void bt_message_discarded_events_set_count(bt_message
*message
,
2589 uint64_t count
) __BT_NOEXCEPT
;
2593 Returns the number of discarded events of the \bt_disc_ev_msg
2596 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2600 Discarded events message of which to get the number of discarded
2603 <strong>If this function returns
2604 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2605 the number of discarded events of \bt_p{message}.
2607 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2608 The number of discarded events of \bt_p{message} is available.
2609 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2610 The number of discarded events of \bt_p{message} is not available.
2612 @bt_pre_not_null{message}
2613 @bt_pre_is_disc_ev_msg{message}
2614 @bt_pre_not_null{count}
2616 @sa bt_message_discarded_events_set_count() —
2617 Sets the number of discarded events of a discarded events message.
2619 extern bt_property_availability
bt_message_discarded_events_get_count(
2620 const bt_message
*message
, uint64_t *count
) __BT_NOEXCEPT
;
2625 @name Discarded packets message
2631 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2632 \bt_msg_iter \bt_p{self_message_iterator}.
2636 Only use this function if
2639 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2640 bt_stream_borrow_class_const(stream))
2646 bt_message_discarded_packets_create_with_default_clock_snapshots().
2649 On success, the returned discarded packets message has the following
2657 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2660 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2663 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2666 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2670 @param[in] self_message_iterator
2671 Self message iterator from which to create the discarded packets
2674 Stream from which the packets were discarded.
2677 New discarded packets message reference, or \c NULL on memory error.
2679 @bt_pre_not_null{self_message_iterator}
2680 @bt_pre_not_null{stream}
2682 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2685 @bt_post_success_frozen{stream}
2687 extern bt_message
*bt_message_discarded_packets_create(
2688 bt_self_message_iterator
*self_message_iterator
,
2689 const bt_stream
*stream
) __BT_NOEXCEPT
;
2693 Creates a \bt_disc_pkt_msg having the beginning and end default
2694 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2695 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2696 from the \bt_msg_iter \bt_p{self_message_iterator}.
2700 Only use this function if
2703 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2704 bt_stream_borrow_class_const(stream))
2710 bt_message_discarded_packets_create().
2713 On success, the returned discarded packets message has the following
2721 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2724 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2725 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2727 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2728 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2730 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2734 @param[in] self_message_iterator
2735 Self message iterator from which to create the discarded packets
2738 Stream from which the packets were discarded.
2739 @param[in] beginning_clock_snapshot_value
2740 Value (clock cycles) of the beginning default clock snapshot of
2742 @param[in] end_clock_snapshot_value
2743 Value (clock cycles) of the end default clock snapshot of
2747 New discarded packets message reference, or \c NULL on memory error.
2749 @bt_pre_not_null{self_message_iterator}
2750 @bt_pre_not_null{stream}
2752 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2754 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2756 @bt_post_success_frozen{stream}
2758 extern bt_message
*bt_message_discarded_packets_create_with_default_clock_snapshots(
2759 bt_self_message_iterator
*self_message_iterator
,
2760 const bt_stream
*stream
, uint64_t beginning_clock_snapshot_value
,
2761 uint64_t end_clock_snapshot_value
) __BT_NOEXCEPT
;
2765 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2767 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2770 Discarded packets message from which to borrow the stream.
2774 \em Borrowed reference of the stream of \bt_p{message}.
2776 The returned pointer remains valid as long as \bt_p{message} exists.
2779 @bt_pre_not_null{message}
2780 @bt_pre_is_disc_pkt_msg{message}
2782 @sa bt_message_discarded_packets_borrow_stream_const() —
2783 \c const version of this function.
2785 extern bt_stream
*bt_message_discarded_packets_borrow_stream(
2786 bt_message
*message
) __BT_NOEXCEPT
;
2790 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2793 See bt_message_discarded_packets_borrow_stream().
2795 extern const bt_stream
*
2796 bt_message_discarded_packets_borrow_stream_const(const bt_message
*message
)
2801 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2805 \ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2809 Discarded packets message from which to borrow the beginning default
2813 Beginning default clock snapshot of \bt_p{message}.
2815 @bt_pre_not_null{message}
2816 @bt_pre_is_disc_pkt_msg{message}
2818 The discarded packets messages of the \bt_stream_cls of
2820 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2822 extern const bt_clock_snapshot
*
2823 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
2824 const bt_message
*message
) __BT_NOEXCEPT
;
2828 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2832 \ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2836 Discarded packets message from which to borrow the end default clock
2840 End default clock snapshot of \bt_p{message}.
2842 @bt_pre_not_null{message}
2843 @bt_pre_is_disc_pkt_msg{message}
2845 The discarded packets messages of the \bt_stream_cls of
2847 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2849 extern const bt_clock_snapshot
*
2850 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
2851 const bt_message
*message
) __BT_NOEXCEPT
;
2855 Borrows the default \bt_clock_cls of the \bt_stream_cls
2856 of the \bt_disc_pkt_msg \bt_p{message}.
2858 See the stream class's
2859 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2862 This is a helper which is equivalent to
2865 bt_stream_class_borrow_default_clock_class_const(
2866 bt_stream_borrow_class_const(
2867 bt_message_discarded_packets_borrow_stream_const(message)))
2871 Discarded packets message from which to borrow its stream's class's
2872 default clock class.
2875 \em Borrowed reference of the default clock class of
2876 the stream class of \bt_p{message}, or \c NULL if none.
2878 @bt_pre_not_null{message}
2879 @bt_pre_is_disc_pkt_msg{message}
2881 extern const bt_clock_class
*
2882 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
2883 const bt_message
*message
) __BT_NOEXCEPT
;
2887 Sets the number of discarded packets of the \bt_disc_pkt_msg
2888 \bt_p{message} to \bt_p{count}.
2890 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2894 Discarded packets message of which to set the number of discarded
2895 packets to \bt_p{count}.
2897 New number of discarded packets of \bt_p{message}.
2899 @bt_pre_not_null{message}
2900 @bt_pre_hot{message}
2901 @bt_pre_is_disc_pkt_msg{message}
2905 @sa bt_message_discarded_packets_get_count() —
2906 Returns the number of discarded packets of a discarded packets
2909 extern void bt_message_discarded_packets_set_count(bt_message
*message
,
2910 uint64_t count
) __BT_NOEXCEPT
;
2914 Returns the number of discarded packets of the \bt_disc_pkt_msg
2917 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2921 Discarded packets message of which to get the number of discarded
2924 <strong>If this function returns
2925 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2926 the number of discarded packets of \bt_p{message}.
2928 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2929 The number of discarded packets of \bt_p{message} is available.
2930 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2931 The number of discarded packets of \bt_p{message} is not available.
2933 @bt_pre_not_null{message}
2934 @bt_pre_is_disc_pkt_msg{message}
2935 @bt_pre_not_null{count}
2937 @sa bt_message_discarded_packets_set_count() —
2938 Sets the number of discarded packets of a discarded packets message.
2940 extern bt_property_availability
bt_message_discarded_packets_get_count(
2941 const bt_message
*message
, uint64_t *count
) __BT_NOEXCEPT
;
2946 @name Message iterator inactivity message
2952 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2953 the \bt_clock_cls \bt_p{clock_class} with the value
2954 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2955 \bt_p{self_message_iterator}.
2957 On success, the returned message iterator inactivity message has the
2958 following property values:
2965 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2967 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2968 with the value \bt_p{clock_snapshot_value}.
2971 @param[in] self_message_iterator
2972 Self message iterator from which to create the message iterator
2974 @param[in] clock_class
2975 Class of the fictitious instance of which
2976 \bt_p{clock_snapshot_value} is the value of its snapshot.
2977 @param[in] clock_snapshot_value
2978 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2981 New message iterator inactivity message reference, or \c NULL on
2984 @bt_pre_not_null{self_message_iterator}
2985 @bt_pre_not_null{clock_class}
2987 @bt_post_success_frozen{clock_class}
2990 bt_message
*bt_message_message_iterator_inactivity_create(
2991 bt_self_message_iterator
*self_message_iterator
,
2992 const bt_clock_class
*clock_class
,
2993 uint64_t clock_snapshot_value
) __BT_NOEXCEPT
;
2997 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2999 See the \ref api-msg-inac-prop-cs "clock snapshot" property.
3002 Message iterator inactivity message from which to borrow the clock
3006 Clock snapshot of \bt_p{message}.
3008 @bt_pre_not_null{message}
3009 @bt_pre_is_inac_msg{message}
3011 extern const bt_clock_snapshot
*
3012 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
3013 const bt_message
*message
) __BT_NOEXCEPT
;
3018 @name Message reference count
3024 Increments the \ref api-fund-shared-object "reference count" of
3025 the message \bt_p{message}.
3029 Message of which to increment the reference count.
3034 @sa bt_message_put_ref() —
3035 Decrements the reference count of a message.
3037 extern void bt_message_get_ref(const bt_message
*message
) __BT_NOEXCEPT
;
3041 Decrements the \ref api-fund-shared-object "reference count" of
3042 the message \bt_p{message}.
3046 Message of which to decrement the reference count.
3051 @sa bt_message_get_ref() —
3052 Increments the reference count of a message.
3054 extern void bt_message_put_ref(const bt_message
*message
) __BT_NOEXCEPT
;
3058 Decrements the reference count of the message \bt_p{_message}, and
3059 then sets \bt_p{_message} to \c NULL.
3063 Message of which to decrement the reference count.
3065 Can contain \c NULL.
3068 @bt_pre_assign_expr{_message}
3070 #define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3072 bt_message_put_ref(_message); \
3073 (_message) = NULL; \
3078 Decrements the reference count of the message \bt_p{_dst}, sets
3079 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3081 This macro effectively moves a message reference from the expression
3082 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3083 \bt_p{_dst} reference.
3087 Destination expression.
3089 Can contain \c NULL.
3095 Can contain \c NULL.
3098 @bt_pre_assign_expr{_dst}
3099 @bt_pre_assign_expr{_src}
3101 #define BT_MESSAGE_MOVE_REF(_dst, _src) \
3103 bt_message_put_ref(_dst); \
3111 @name Message Interchange Protocol version
3117 Status codes for bt_get_greatest_operative_mip_version()
3118 and bt_get_greatest_operative_mip_version_with_restriction().
3120 typedef enum bt_get_greatest_operative_mip_version_status
{
3125 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3131 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
= __BT_FUNC_STATUS_NO_MATCH
,
3137 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3143 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
3144 } bt_get_greatest_operative_mip_version_status
;
3148 Computes the greatest \bt_mip version which
3149 you can use to create a trace processing \bt_graph to which you
3150 intend to \ref api-graph-lc-add "add components" described by the
3151 component descriptors \bt_p{component_descriptors}, and sets
3152 \bt_p{*mip_version} to the result.
3154 This function is equivalent to calling
3155 bt_get_greatest_operative_mip_version_with_restriction() with
3156 \bt_p{mip_version_restriction} set to \c NULL (no restriction).
3158 @param[in] component_descriptors
3159 Component descriptors for which to get the supported MIP versions
3160 to compute the greatest operative MIP version.
3161 @param[in] logging_level
3162 Logging level to use when calling the "get supported MIP versions"
3163 method for each component descriptor in
3164 \bt_p{component_descriptors}.
3165 @param[out] mip_version
3166 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3167 operative MIP version of all the component descriptors in
3168 \bt_p{component_descriptors}.
3170 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3172 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3173 No operative MIP version exists for the component descriptors of
3174 \bt_p{component_descriptors}.
3175 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3177 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3180 @bt_pre_not_null{component_descriptors}
3182 \bt_p{component_descriptors} contains one or more component
3184 @bt_pre_not_null{mip_version}
3186 @sa bt_get_greatest_operative_mip_version_with_restriction() —
3187 Computes the greatest MIP version for specific components
3188 with a MIP version restriction.
3190 extern bt_get_greatest_operative_mip_version_status
3191 bt_get_greatest_operative_mip_version(
3192 const bt_component_descriptor_set
*component_descriptors
,
3193 bt_logging_level logging_level
, uint64_t *mip_version
)
3198 Computes the greatest \bt_mip version, restricted to the set of
3199 versions \bt_p{mip_version_restriction}, which
3200 you can use to create a trace processing \bt_graph to which you
3201 intend to \ref api-graph-lc-add "add components" described by the
3202 component descriptors \bt_p{component_descriptors}, and sets
3203 \bt_p{*mip_version} to the result.
3205 This function calls the
3206 \link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3207 method for each component descriptor in \bt_p{component_descriptors},
3208 and then sets \bt_p{*mip_version} to the greatest common (operative)
3209 MIP version which is part of the set \bt_p{mip_version_restriction},
3210 if any. The "get supported MIP versions" method receives
3211 \bt_p{logging_level} as its \bt_p{logging_level} parameter.
3213 For example, if all the components would support both MIP
3214 versions 0 and 1,
3215 but \bt_p{mip_version_restriction} only contains the
3216 [0, 0] range, then this function sets \bt_p{*mip_version}
3219 If \bt_p{mip_version_restriction} is \c NULL, then it's equivalent to
3220 the single range [0, \bt_max_mip_version], that is, all the
3221 possible MIP versions as of \bt_name_version_min_maj.
3223 If this function doesn't find an operative MIP version within
3224 \bt_p{mip_version_restriction} for the component descriptors of
3225 \bt_p{component_descriptors}, then it returns
3226 #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3228 @param[in] component_descriptors
3229 Component descriptors for which to get the supported MIP versions
3230 to compute the greatest operative MIP version.
3231 @param[in] logging_level
3232 Logging level to use when calling the "get supported MIP versions"
3233 method for each component descriptor in
3234 \bt_p{component_descriptors}.
3235 @param[in] mip_version_restriction
3237 Set of MIP versions of which \bt_p{*mip_version} must be part of.
3241 @param[out] mip_version
3242 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3243 operative MIP version, within \bt_p{mip_version_restriction}, of
3244 all the component descriptors in \bt_p{component_descriptors}.
3246 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3248 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3249 No operative MIP version exists within
3250 \bt_p{mip_version_restriction} for the component descriptors of
3251 \bt_p{component_descriptors}.
3252 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3254 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3257 @bt_pre_not_null{component_descriptors}
3259 \bt_p{component_descriptors} contains one or more component
3262 <strong>If \bt_p{mip_version_restriction} is not \c NULL</strong>,
3263 then no upper value within the ranges of
3264 \bt_p{mip_version_restriction} is greater
3265 than \bt_max_mip_version
3266 (the return value of bt_get_maximal_mip_version()).
3267 @bt_pre_not_null{mip_version}
3269 @sa bt_get_greatest_operative_mip_version() —
3270 Computes the greatest MIP version for specific components.
3272 extern enum bt_get_greatest_operative_mip_version_status
3273 bt_get_greatest_operative_mip_version_with_restriction(
3274 const struct bt_component_descriptor_set
*comp_descr_set
,
3275 enum bt_logging_level log_level
,
3276 const bt_integer_range_set_unsigned
*mip_version_restriction
,
3277 uint64_t *mip_version
)
3282 Returns the maximal available \bt_mip version as of
3283 \bt_name_version_min_maj.
3285 As of \bt_name_version_min_maj, this function returns
3286 \bt_max_mip_version.
3289 Maximal available MIP version (\bt_max_mip_version).
3291 extern uint64_t bt_get_maximal_mip_version(void) __BT_NOEXCEPT
;
3301 #endif /* BABELTRACE2_GRAPH_MESSAGE_H */