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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
21 @defgroup api-msg Messages
22 @ingroup api-comp-cls-dev
25 Elements exchanged between \bt_p_comp.
27 <strong><em>Messages</em></strong> are the objects which are exchanged
28 between \bt_p_comp in a trace processing \bt_graph to accomplish a
31 \bt_cp_msg_iter create messages while message iterators \em and
32 \bt_p_sink_comp consume messages.
34 There are eight types of messages:
45 The type of a message is #bt_message.
47 Get the type enumerator of a message with bt_message_get_type().
49 A message is a \ref api-fund-shared-object "shared object": get a
50 new reference with bt_message_get_ref() and put an existing
51 reference with bt_message_put_ref().
53 Some library functions \ref api-fund-freezing "freeze" messages on
54 success. The documentation of those functions indicate this
57 Messages transport objects of the \ref api-tir API, which is an
58 intermediate representation of the tracing domain concepts.
60 All types of messages, except the \bt_inac_msg type, are related to a
61 specific <em>\bt_stream</em>, which represents a conceptual
62 \ref api-msg-seq "sequence of messages".
64 Some types of messages can have a default \bt_cs, depending on whether
65 or not their stream has a conceptual default clock, that is, whether or
66 not the stream's \ref api-tir-stream-cls "class" has a
67 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
68 The creation functions for those types of messages contain
69 <code>_with_default_clock_snapshot</code> (for example,
70 bt_message_event_create_with_default_clock_snapshot()).
72 For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
73 is optional, therefore they have dedicated
74 bt_message_stream_beginning_set_default_clock_snapshot() and
75 bt_message_stream_end_set_default_clock_snapshot() functions.
77 All the message creation functions take a \bt_self_msg_iter as their
78 first parameter. This is because a message iterator method is the only
79 valid context to create a message.
81 <h1>Message types</h1>
83 This section details each type of message.
85 The following table shows the creation functions and types for each type
92 <th>Creation functions
94 <td>\ref api-msg-sb "Stream beginning"
95 <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
96 <td>bt_message_stream_beginning_create()
98 <td>\ref api-msg-se "Stream end"
99 <td>#BT_MESSAGE_TYPE_STREAM_END
100 <td>bt_message_stream_end_create()
102 <td>\ref api-msg-ev "Event"
103 <td>#BT_MESSAGE_TYPE_EVENT
105 bt_message_event_create()<br>
106 bt_message_event_create_with_default_clock_snapshot()<br>
107 bt_message_event_create_with_packet()<br>
108 bt_message_event_create_with_packet_and_default_clock_snapshot()
110 <td>\ref api-msg-pb "Packet beginning"
111 <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
113 bt_message_packet_beginning_create()<br>
114 bt_message_packet_beginning_create_with_default_clock_snapshot()
116 <td>\ref api-msg-pe "Packet end"
117 <td>#BT_MESSAGE_TYPE_PACKET_END
119 bt_message_packet_end_create()<br>
120 bt_message_packet_end_create_with_default_clock_snapshot()
122 <td>\ref api-msg-disc-ev "Discarded events"
123 <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
125 bt_message_discarded_events_create()<br>
126 bt_message_discarded_events_create_with_default_clock_snapshots()
128 <td>\ref api-msg-disc-pkt "Discarded packets"
129 <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
131 bt_message_discarded_packets_create()<br>
132 bt_message_discarded_packets_create_with_default_clock_snapshots()
134 <td>\ref api-msg-inac "Message iterator inactivity"
135 <td>#BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
136 <td>bt_message_message_iterator_inactivity_create()
139 <h2>\anchor api-msg-sb Stream beginning message</h2>
141 A <strong><em>stream beginning message</em></strong> indicates the
142 beginning of a \bt_stream.
146 - A stream beginning message is always the first one in the
147 \ref api-msg-seq "message sequence".
149 - There can be only one stream beginning message.
151 Create a stream beginning message with
152 bt_message_stream_beginning_create().
154 A stream beginning message has the following properties:
157 <dt>\anchor api-msg-sb-prop-stream Stream</dt>
159 \bt_c_stream of which the message indicates the beginning.
161 You cannot change the stream once the message is created.
163 Borrow a stream beginning message's stream with
164 bt_message_stream_beginning_borrow_stream() and
165 bt_message_stream_beginning_borrow_stream_const().
169 \anchor api-msg-sb-prop-cs
170 \bt_dt_opt Default \bt_cs
173 Snapshot of the message's \bt_stream's default clock when the
176 A stream beginning message can only have a default clock snapshot
177 if its stream's \ref api-tir-stream-cls "class" has a
178 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
180 When a stream beginning message has no default clock snapshot,
181 then its time is <em>unknown</em>.
183 Set a stream beginning message's default clock snapshot with
184 bt_message_stream_beginning_set_default_clock_snapshot().
186 Borrow a stream beginning message's default clock snapshot with
187 bt_message_stream_beginning_borrow_default_clock_snapshot_const().
191 <h2>\anchor api-msg-se Stream end message</h2>
193 A <strong><em>stream end message</em></strong> indicates the
198 - A stream end message is always the last one in the
199 \ref api-msg-seq "message sequence".
201 - There can be only one stream end message.
203 Create a stream end message with bt_message_stream_end_create().
205 A stream end message has the following properties:
208 <dt>\anchor api-msg-se-prop-stream Stream</dt>
210 \bt_c_stream of which the message indicates the end.
212 You cannot change the stream once the message is created.
214 Borrow a stream end message's stream with
215 bt_message_stream_end_borrow_stream() and
216 bt_message_stream_end_borrow_stream_const().
220 \anchor api-msg-se-prop-cs
221 \bt_dt_opt Default \bt_cs
224 Snapshot of the message's \bt_stream's default clock when the
227 A stream end message can only have a default clock snapshot
228 if its stream's \ref api-tir-stream-cls "class" has a
229 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
231 When a stream end message has no default clock snapshot, then its
232 time is <em>unknown</em>.
234 Set a stream end message's default clock snapshot with
235 bt_message_stream_end_set_default_clock_snapshot().
237 Borrow a stream end message's default clock snapshot with
238 bt_message_stream_end_borrow_default_clock_snapshot_const().
242 <h2>\anchor api-msg-ev Event message</h2>
244 An <strong><em>event message</em></strong> transports an \bt_ev and has,
245 possibly, a default \bt_cs.
247 Within its \bt_stream's \ref api-msg-seq "message sequence", an event
248 message can only occur:
252 If the stream's \ref api-tir-stream-cls "class"
253 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
255 <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
258 If the stream's class does not support packets
260 <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
263 To create an event message for a given stream, use:
267 If the stream's \ref api-tir-stream-cls "class"
268 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
273 If the stream's class has a
274 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
276 <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
279 If the stream's class does not have a
280 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
282 <dd>bt_message_event_create_with_packet()</dd>
285 Those two creation functions accept a \bt_pkt parameter which is
286 the packet logically containing the message's event. A packet is
291 If the stream's class does not supports packets
296 If the stream's class has a default clock class
298 <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
301 If the stream's class does not have a
302 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
304 <dd>bt_message_event_create()</dd>
309 The four creation functions above accept an \bt_ev_cls parameter. When
310 you create the message, the library instantiates this event class as an
311 \bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
312 This event class must be part of the class of the event message's
315 An event message's event is initially <em>not set</em>: before you emit
316 the event message from a \bt_msg_iter's
317 \link api-msg-iter-cls-meth-next "next" method\endlink, you need to
318 borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
319 bt_event_borrow_specific_context_field(), and
320 bt_event_borrow_common_context_field()) and, recursively, set the values
321 of the all their inner fields.
323 An event message has the following properties:
326 <dt>\anchor api-msg-ev-prop-ev Event</dt>
328 \bt_c_ev which the message transports.
330 This is an instance of the \bt_ev_cls which was passed to the
331 message's creation function.
333 With this event, you can access its \bt_pkt (if any) with
334 bt_event_borrow_packet_const() and its
335 \bt_stream with bt_event_borrow_stream_const().
337 Borrow an event message's event with bt_message_event_borrow_event()
338 and bt_message_event_borrow_event_const().
342 \anchor api-msg-ev-prop-cs
343 \bt_dt_opt Default \bt_cs
346 Snapshot of the message's \bt_stream's default clock when the
349 An event message has a default clock snapshot
350 if its stream's \ref api-tir-stream-cls "class" has a
351 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class",
352 and has none otherwise.
354 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
355 the default clock snapshot of an event message must be greater than
356 or equal to any default clock snapshot of any previous message.
358 Borrow an event message's default clock snapshot with
359 bt_message_event_borrow_default_clock_snapshot_const().
363 <h2>\anchor api-msg-pb Packet beginning message</h2>
365 A <strong><em>packet beginning message</em></strong> indicates the
366 beginning of a \bt_pkt.
368 A packet beginning message can only exist if its \bt_stream's
369 \ref api-tir-stream-cls "class"
370 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
372 For a given packet, there can be only one packet beginning message.
374 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
375 beginning message can only occur after the \bt_sb_msg and before the
378 To create a packet beginning message for a given stream, use:
382 If, for this stream's class,
383 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
385 <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
388 If, for this stream's class, packets do not have a beginning default
391 <dd>bt_message_packet_beginning_create()</dd>
394 A packet beginning message has the following properties:
397 <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
399 \bt_c_pkt of which the message indicates the beginning.
401 You cannot change the packet once the message is created.
403 Borrow a packet beginning message's packet with
404 bt_message_packet_beginning_borrow_packet() and
405 bt_message_packet_beginning_borrow_packet_const().
409 \anchor api-msg-pb-prop-cs
410 \bt_dt_opt Default \bt_cs
413 Snapshot of the message's \bt_stream's default clock when the
416 A packet beginning message has a default clock snapshot if:
418 - Its stream's \ref api-tir-stream-cls "class" has a
419 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
421 - For its stream's class,
422 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
424 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
425 the default clock snapshot of a packet beginning message must be
426 greater than or equal to any clock snapshot of any previous message.
428 Borrow a packet beginning message's default clock snapshot with
429 bt_message_packet_beginning_borrow_default_clock_snapshot_const().
433 <h2>\anchor api-msg-pe Packet end message</h2>
435 A <strong><em>packet end message</em></strong> indicates the
438 A packet end message can only exist if its \bt_stream's
439 \ref api-tir-stream-cls "class"
440 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
442 For a given packet, there can be only one packet end message.
444 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
445 end message can only occur:
447 - After the \bt_sb_msg and before the \bt_se_msg.
448 - After a \bt_pb_msg for the same packet.
450 To create a packet end message for a given stream, use:
454 If, for this stream's class,
455 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
457 <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
460 If, for this stream's class, packets do not have an end default
463 <dd>bt_message_packet_end_create()</dd>
466 A packet end message has the following properties:
469 <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
471 \bt_c_pkt of which the message indicates the end.
473 You cannot change the packet once the message is created.
475 Borrow a packet end message's packet with
476 bt_message_packet_end_borrow_packet() and
477 bt_message_packet_end_borrow_packet_const().
481 \anchor api-msg-pe-prop-cs
482 \bt_dt_opt Default \bt_cs
485 Snapshot of the message's \bt_stream's default clock when the
488 A packet end message has a default clock snapshot if:
490 - Its stream's \ref api-tir-stream-cls "class" has a
491 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
493 - For its stream's class,
494 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
496 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
497 the default clock snapshot of a packet end message must be greater
498 than or equal to any clock snapshot of any previous message.
500 Borrow a packet end message's default clock snapshot with
501 bt_message_packet_end_borrow_default_clock_snapshot_const().
505 <h2>\anchor api-msg-disc-ev Discarded events message</h2>
507 A <strong><em>discarded events message</em></strong> indicates that
508 events were discarded at <em>tracing time</em>. It does \em not indicate
509 that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
511 A discarded events message can only exist if its \bt_stream's
512 \ref api-tir-stream-cls "class"
513 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events".
515 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
516 events message can only occur after the \bt_sb_msg and before the
519 To create a discarded events message for a given stream, use:
523 If, for this stream's class,
524 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
526 <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
529 If, for this stream's class, discarded events do not have default
532 <dd>bt_message_discarded_events_create()</dd>
535 A discarded events message has the following properties:
538 <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
540 \bt_c_stream into which events were discarded.
542 You cannot change the stream once the message is created.
544 Borrow a discarded events message's stream with
545 bt_message_discarded_events_borrow_stream() and
546 bt_message_discarded_events_borrow_stream_const().
550 \anchor api-msg-disc-ev-prop-cs-beg
551 \bt_dt_opt Beginning default \bt_cs
554 Snapshot of the message's \bt_stream's default clock which indicates
555 the beginning of the discarded events time range.
557 A discarded events message has a beginning default clock snapshot
560 - Its stream's \ref api-tir-stream-cls "class" has a
561 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
563 - For its stream's class,
564 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
566 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
567 the beginning default clock snapshot of a discarded events message
568 must be greater than or equal to any clock snapshot of any previous
571 Borrow a discarded events message's beginning default clock snapshot
573 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
577 \anchor api-msg-disc-ev-prop-cs-end
578 \bt_dt_opt End default \bt_cs
581 Snapshot of the message's \bt_stream's default clock which indicates
582 the end of the discarded events time range.
584 A discarded events message has an end default clock snapshot if:
586 - Its stream's \ref api-tir-stream-cls "class" has a
587 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
589 - For its stream's class,
590 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
592 If a discarded events message has both a
593 \ref api-msg-disc-ev-prop-cs-beg "beginning" and an end default
594 clock snapshots, the end default clock snapshot must be greater than
595 or equal to the beginning default clock snapshot.
597 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
598 the end default clock snapshot of a discarded events message must be
599 greater than or equal to any clock snapshot of any previous message.
601 Borrow a discarded events message's end default clock snapshot with
602 bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
606 \anchor api-msg-disc-ev-prop-count
607 \bt_dt_opt Discarded event count
610 Exact number of discarded events.
612 If this property is missing, then the number of discarded events
615 Use bt_message_discarded_events_set_count() and
616 bt_message_discarded_events_get_count().
620 <h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
622 A <strong><em>discarded packets message</em></strong> indicates that
623 packets were discarded at <em>tracing time</em>. It does \em not
624 indicate that whole packets were dropped during a trace processing
627 A discarded packets message can only exist if its \bt_stream's
628 \ref api-tir-stream-cls "class"
629 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets".
631 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
632 packets message can only occur:
634 - After the \bt_sb_msg.
635 - Before the \bt_se_msg.
637 - Before any \bt_pb_msg.
638 - After any \bt_pe_msg.
639 - Between a packet end and a packet beginning message.
641 To create a discarded packets message for a given stream, use:
645 If, for this stream's class,
646 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
648 <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
651 If, for this stream's class, discarded packets do not have default
654 <dd>bt_message_discarded_packets_create()</dd>
657 A discarded packets message has the following properties:
660 <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
662 \bt_c_stream into which packets were discarded.
664 You cannot change the stream once the message is created.
666 Borrow a discarded packets message's stream with
667 bt_message_discarded_packets_borrow_stream() and
668 bt_message_discarded_packets_borrow_stream_const().
672 \anchor api-msg-disc-pkt-prop-cs-beg
673 \bt_dt_opt Beginning default \bt_cs
676 Snapshot of the message's \bt_stream's default clock which indicates
677 the beginning of the discarded packets time range.
679 A discarded packets message has a beginning default clock snapshot
682 - Its stream's \ref api-tir-stream-cls "class" has a
683 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
685 - For its stream's class,
686 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
688 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
689 the beginning default clock snapshot of a discarded packets message
690 must be greater than or equal to any clock snapshot of any previous
693 Borrow a discarded packets message's beginning default clock snapshot
695 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
699 \anchor api-msg-disc-pkt-prop-cs-end
700 \bt_dt_opt End default \bt_cs
703 Snapshot of the message's \bt_stream's default clock which indicates
704 the end of the discarded packets time range.
706 A discarded packets message has an end default clock snapshot if:
708 - Its stream's \ref api-tir-stream-cls "class" has a
709 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
711 - For its stream's class,
712 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
714 If a discarded packets message has both a
715 \ref api-msg-disc-pkt-prop-cs-beg "beginning" and an end default
716 clock snapshots, the end default clock snapshot must be greater than
717 or equal to the beginning default clock snapshot.
719 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
720 the end default clock snapshot of a discarded packets message must
721 be greater than or equal to any clock snapshot of any previous
724 Borrow a discarded packets message's end default clock snapshot with
725 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
729 \anchor api-msg-disc-pkt-prop-count
730 \bt_dt_opt Discarded packet count
733 Exact number of discarded packets.
735 If this property is missing, then the number of discarded packets
738 Use bt_message_discarded_packets_set_count() and
739 bt_message_discarded_packets_get_count().
743 <h2>\anchor api-msg-inac Message iterator inactivity</h2>
745 A <strong><em>message iterator inactivity message</em></strong>
746 indicates that, within the \ref api-msg-seq "message sequence" of a
747 given \bt_msg_iter, there's no messages since the last message (if any)
748 until a given point in time.
750 A message iterator inactivity message is the only type of message that's
751 not related to a \bt_stream: it targets the whole message sequence of a
752 message iterator, and can occur at any position within the sequence.
754 This message is mostly significant for real-time message iterators: if a
755 message iterator A indicates that there's no messages until a given
756 point in time T, then a downstream filter message iterator B which
757 relies on multiple upstream message iterators does not have to wait for
758 new messages from A until T.
760 In other words, a message iterator inactivity message can help
761 downstream message iterators or \bt_p_sink_comp <em>progress</em>.
763 Create a message iterator inactivity message with
764 bt_message_message_iterator_inactivity_create(). You must pass a
765 \bt_clock_cls and the value of a fictitious (clock) instance to this
766 function so that it creates a \bt_cs.
768 A message iterator inactivity message has the following property:
772 \anchor api-msg-inac-prop-cs
776 Snapshot of a fictitious instance of the message's \bt_clock_cls
777 which indicates the point in time until when there's no messages
778 in the message iterator's \ref api-msg-seq "message sequence".
780 Within its \bt_msg_iter's message sequence, the clock snapshot of a
781 message iterator inactivity message must be greater than or equal to
782 any clock snapshot of any previous message.
784 Borrow a message iterator inactivity message's clock snapshot
786 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
790 <h1>\anchor api-msg-mip Message Interchange Protocol</h1>
792 The <em>Message Interchange Protocol</em> (MIP) is the system of rules
793 used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
794 trace processing graph.
796 The MIP covers everything related to messages and what they contain, as
797 well as how they are ordered within the \ref api-msg-seq "sequence" that
798 a message iterator produces.
802 - A valid message sequence for a given \bt_stream starts with a
803 \bt_sb_msg and ends with a \bt_se_msg.
806 \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
807 is [0, 2<sup>64</sup> - 1].
809 - The available message types are stream beginning and end, event,
810 packet beginning and end, discarded events and packets, and message
813 The MIP has a version which is a single major number, independent from
814 the \bt_name project's version. As of \bt_name_version_min_maj, the only
815 available MIP version is 0.
817 If what the MIP covers changes in a breaking or semantical way in the
818 future, the MIP and \bt_name's minor versions will be bumped.
820 When you create a trace processing \bt_graph with bt_graph_create(), you
821 must pass the effective MIP version to use. Then, the components you
822 \ref api-graph-lc-add "add" to this graph can access this configured MIP
823 version with bt_self_component_get_graph_mip_version() and behave
824 accordingly. In other words, if the configured MIP version is 0, then a
825 component cannot use features introduced by MIP version 1. For
826 example, should the project introduce a new type of \bt_fc, the MIP
827 version would be bumped.
829 A component which cannot honor a given MIP can fail at
830 initialization time, making the corresponding
831 <code>bt_graph_add_*_component*()</code> call fail too. To avoid any
832 surprise, you can create a \bt_comp_descr_set with descriptors of the
833 components you intend to add to a trace processing graph and call
834 bt_get_greatest_operative_mip_version() to get the greatest (most
835 recent) MIP version you can use.
837 To get the library's latest MIP version, use
838 bt_get_maximal_mip_version().
840 The ultimate goal of the MIP version feature is for the \bt_name project
841 to be able to introduce new features or even major breaking changes
842 without breaking existing \bt_p_comp_cls. This is especially important
843 considering that \bt_name supports \bt_p_plugin written by different
844 authors. Of course one of the project's objectives is to bump the MIP
845 version as rarely as possible. When it is required, though, it's a
846 welcome tool to make the project evolve gracefully.
848 The Message Interchange Protocol has no dedicated documentation as this
849 very message module (and its submodules, like \ref api-tir)
850 documentation is enough. You can consider that all the
851 functions of the message and trace IR objects have an implicit MIP
852 version \ref api-fund-pre-post "precondition". When a given
853 function documentation does not explicitly document a MIP version
854 precondition, it means that the effective MIP version has no effect on
855 said function's behaviour.
857 <h2>\anchor api-msg-seq Message sequence rules</h2>
859 The purpose of a \bt_msg_iter is to iterate a sequence of messages.
861 Those messages can be related to different \bt_p_stream:
863 @image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
865 However, for such a message sequence, the current \bt_mip
866 (version \bt_max_mip_version) dictates that:
870 For a given \bt_stream:
872 - The sequence must begin with a \bt_sb_msg.
873 - The sequence must end with a \bt_se_msg.
874 - <strong>If the stream's \ref api-tir-stream-cls "class"
875 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"</strong>:
876 - Any \bt_pb_msg must be followed with a \bt_pe_msg.
877 - All \bt_p_ev_msg must be between a packet beginning and a
879 - A \bt_disc_pkt_msg must be (one of):
880 - Before the first packet beginning message.
881 - Between a packet end message and a packet beginning message.
882 - After the last packet end message.
884 The rules above can be summarized by the following regular
888 <dt>Without packets</dt>
895 <dt>With packets</dt>
898 SB ((PB (E | DE)* PE) | DE | DP)* SE
907 <dd>\bt_c_sb_msg</dd>
910 <dd>\bt_c_se_msg</dd>
913 <dd>\bt_c_ev_msg</dd>
916 <dd>\bt_c_pb_msg</dd>
919 <dd>\bt_c_pe_msg</dd>
922 <dd>\bt_c_disc_ev_msg</dd>
925 <dd>\bt_c_disc_pkt_msg</dd>
928 For a given message iterator, for any message with a \bt_cs, its
929 clock snapshot must be greater than or equal to any clock snapshot
930 of any previous message.
932 For the scope of this rule, the clock snapshot of a \bt_disc_ev_msg
933 or of a \bt_disc_pkt_msg is its beginning default clock snapshot.
935 For a given message iterator, the \bt_p_cs of all the messages of
936 the sequence with a clock snapshot must be correlatable
937 (see \ref api-tir-clock-cls-origin "Clock value vs. clock class origin").
947 @typedef struct bt_message bt_message;
962 Message type enumerators.
964 typedef enum bt_message_type
{
969 BT_MESSAGE_TYPE_STREAM_BEGINNING
= 1 << 0,
975 BT_MESSAGE_TYPE_STREAM_END
= 1 << 1,
981 BT_MESSAGE_TYPE_EVENT
= 1 << 2,
987 BT_MESSAGE_TYPE_PACKET_BEGINNING
= 1 << 3,
993 BT_MESSAGE_TYPE_PACKET_END
= 1 << 4,
999 BT_MESSAGE_TYPE_DISCARDED_EVENTS
= 1 << 5,
1005 BT_MESSAGE_TYPE_DISCARDED_PACKETS
= 1 << 6,
1011 BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
= 1 << 7,
1016 Returns the type enumerator of the message \bt_p{message}.
1019 Message of which to get the type enumerator
1022 Type enumerator of \bt_p{message}.
1024 @bt_pre_not_null{message}
1026 extern bt_message_type
bt_message_get_type(const bt_message
*message
);
1031 @name Common stream message
1038 bt_message_stream_beginning_borrow_default_clock_snapshot_const()
1040 bt_message_stream_end_borrow_default_clock_snapshot_const().
1042 typedef enum bt_message_stream_clock_snapshot_state
{
1047 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
= 1,
1051 Unknown (no) \bt_cs.
1053 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
= 0,
1054 } bt_message_stream_clock_snapshot_state
;
1059 @name Stream beginning message
1065 Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
1066 \bt_msg_iter \bt_p{self_message_iterator}.
1068 On success, the returned stream beginning message has the following
1076 <td>\ref api-msg-sb-prop-stream "Stream"
1079 <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
1083 @param[in] self_message_iterator
1084 Self message iterator from which to create the stream beginning
1087 Stream of which the message to create indicates the beginning.
1090 New stream beginning message reference, or \c NULL on memory error.
1092 @bt_pre_not_null{self_message_iterator}
1093 @bt_pre_not_null{stream}
1095 @bt_post_success_frozen{stream}
1098 bt_message
*bt_message_stream_beginning_create(
1099 bt_self_message_iterator
*self_message_iterator
,
1100 const bt_stream
*stream
);
1104 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
1106 See the \ref api-msg-sb-prop-stream "stream" property.
1109 Stream beginning message from which to borrow the stream.
1113 \em Borrowed reference of the stream of \bt_p{message}.
1115 The returned pointer remains valid as long as \bt_p{message} exists.
1118 @bt_pre_not_null{message}
1119 @bt_pre_is_sb_msg{message}
1121 @sa bt_message_stream_beginning_borrow_stream_const() —
1122 \c const version of this function.
1124 extern bt_stream
*bt_message_stream_beginning_borrow_stream(
1125 bt_message
*message
);
1129 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
1132 See bt_message_stream_beginning_borrow_stream().
1134 extern const bt_stream
*bt_message_stream_beginning_borrow_stream_const(
1135 const bt_message
*message
);
1139 Sets the value, in clock cycles, of the default \bt_cs of the
1140 \bt_sb_msg \bt_p{message} to \bt_p{value}.
1142 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1145 Stream beginning message of which to set the default clock snapshot
1146 value to \bt_p{value}.
1148 New value (clock cycles) of the default clock snapshot of
1151 @bt_pre_not_null{message}
1152 @bt_pre_hot{message}
1153 @bt_pre_is_sb_msg{message}
1155 The \bt_stream_cls of \bt_p{message} has a
1156 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1158 @sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() —
1159 Borrows the default clock snapshot of a stream beginning message.
1162 void bt_message_stream_beginning_set_default_clock_snapshot(
1163 bt_message
*message
, uint64_t value
);
1167 Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
1169 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1172 Stream beginning message from which to borrow the default clock
1174 @param[out] clock_snapshot
1175 <strong>If this function returns
1176 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1177 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1178 clock snapshot of \bt_p{message}.
1180 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1181 The default clock snapshot of \bt_p{message} is known and returned
1182 as \bt_p{*clock_snapshot}.
1183 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1184 \bt_p{message} has no default clock snapshot: its time is unknown.
1186 @bt_pre_not_null{message}
1187 @bt_pre_is_sb_msg{message}
1189 The \bt_stream_cls of \bt_p{message} has a
1190 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1191 @bt_pre_not_null{clock_snapshot}
1193 @sa bt_message_stream_beginning_set_default_clock_snapshot() —
1194 Sets the default clock snapshot of a stream beginning message.
1196 extern bt_message_stream_clock_snapshot_state
1197 bt_message_stream_beginning_borrow_default_clock_snapshot_const(
1198 const bt_message
*message
,
1199 const bt_clock_snapshot
**clock_snapshot
);
1203 Borrows the default \bt_clock_cls of the \bt_stream_cls
1204 of the \bt_sb_msg \bt_p{message}.
1206 See the stream class's
1207 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1210 This is a helper which is equivalent to
1213 bt_stream_class_borrow_default_clock_class_const(
1214 bt_stream_borrow_class_const(
1215 bt_message_stream_beginning_borrow_stream_const(message)))
1219 Stream beginning message from which to borrow its stream's class's
1220 default clock class.
1223 \em Borrowed reference of the default clock class of
1224 the stream class of \bt_p{message}, or \c NULL if none.
1226 @bt_pre_not_null{message}
1227 @bt_pre_is_sb_msg{message}
1229 extern const bt_clock_class
*
1230 bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
1231 const bt_message
*message
);
1236 @name Stream end message
1242 Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
1243 \bt_msg_iter \bt_p{self_message_iterator}.
1245 On success, the returned stream end message has the following
1253 <td>\ref api-msg-se-prop-stream "Stream"
1256 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1260 @param[in] self_message_iterator
1261 Self message iterator from which to create the stream end
1264 Stream of which the message to create indicates the end.
1267 New stream end message reference, or \c NULL on memory error.
1269 @bt_pre_not_null{self_message_iterator}
1270 @bt_pre_not_null{stream}
1272 @bt_post_success_frozen{stream}
1275 bt_message
*bt_message_stream_end_create(
1276 bt_self_message_iterator
*self_message_iterator
,
1277 const bt_stream
*stream
);
1281 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
1283 See the \ref api-msg-se-prop-stream "stream" property.
1286 Stream end message from which to borrow the stream.
1290 \em Borrowed reference of the stream of \bt_p{message}.
1292 The returned pointer remains valid as long as \bt_p{message} exists.
1295 @bt_pre_not_null{message}
1296 @bt_pre_is_se_msg{message}
1298 @sa bt_message_stream_end_borrow_stream_const() —
1299 \c const version of this function.
1301 extern bt_stream
*bt_message_stream_end_borrow_stream(
1302 bt_message
*message
);
1306 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
1309 See bt_message_stream_end_borrow_stream().
1311 extern const bt_stream
*bt_message_stream_end_borrow_stream_const(
1312 const bt_message
*message
);
1316 Sets the value, in clock cycles, of the default \bt_cs of the
1317 \bt_se_msg \bt_p{message} to \bt_p{value}.
1319 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1322 Stream end message of which to set the default clock snapshot
1323 value to \bt_p{value}.
1325 New value (clock cycles) of the default clock snapshot of
1328 @bt_pre_not_null{message}
1329 @bt_pre_hot{message}
1330 @bt_pre_is_se_msg{message}
1332 The \bt_stream_cls of \bt_p{message} has a
1333 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1335 @sa bt_message_stream_end_borrow_default_clock_snapshot_const() —
1336 Borrows the default clock snapshot of a stream end message.
1339 void bt_message_stream_end_set_default_clock_snapshot(
1340 bt_message
*message
, uint64_t value
);
1344 Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
1346 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1349 Stream end message from which to borrow the default clock
1351 @param[out] clock_snapshot
1352 <strong>If this function returns
1353 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1354 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1355 clock snapshot of \bt_p{message}.
1357 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1358 The default clock snapshot of \bt_p{message} is known and returned
1359 as \bt_p{*clock_snapshot}.
1360 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1361 \bt_p{message} has no default clock snapshot: its time is unknown.
1363 @bt_pre_not_null{message}
1364 @bt_pre_is_se_msg{message}
1366 The \bt_stream_cls of \bt_p{message} has a
1367 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1368 @bt_pre_not_null{clock_snapshot}
1370 @sa bt_message_stream_end_set_default_clock_snapshot() —
1371 Sets the default clock snapshot of a stream end message.
1373 extern bt_message_stream_clock_snapshot_state
1374 bt_message_stream_end_borrow_default_clock_snapshot_const(
1375 const bt_message
*message
,
1376 const bt_clock_snapshot
**clock_snapshot
);
1380 Borrows the default \bt_clock_cls of the \bt_stream_cls
1381 of the \bt_se_msg \bt_p{message}.
1383 See the stream class's
1384 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1387 This is a helper which is equivalent to
1390 bt_stream_class_borrow_default_clock_class_const(
1391 bt_stream_borrow_class_const(
1392 bt_message_stream_end_borrow_stream_const(message)))
1396 Stream end message from which to borrow its stream's class's
1397 default clock class.
1400 \em Borrowed reference of the default clock class of
1401 the stream class of \bt_p{message}, or \c NULL if none.
1403 @bt_pre_not_null{message}
1404 @bt_pre_is_se_msg{message}
1406 extern const bt_clock_class
*
1407 bt_message_stream_end_borrow_stream_class_default_clock_class_const(
1408 const bt_message
*message
);
1419 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1420 \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
1421 \bt_msg_iter \bt_p{self_message_iterator}.
1425 Only use this function if
1428 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1431 returns #BT_FALSE and
1434 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1440 bt_message_event_create_with_default_clock_snapshot(),
1441 bt_message_event_create_with_packet(), or
1442 bt_message_event_create_with_packet_and_default_clock_snapshot().
1445 On success, the returned event message has the following property
1453 <td>\ref api-msg-ev-prop-ev "Event"
1455 An instance (with \bt_p_field that are not set) of
1458 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1462 @param[in] self_message_iterator
1463 Self message iterator from which to create the event message.
1464 @param[in] event_class
1465 Class of the \bt_ev of the message to create.
1467 Stream conceptually containing the event of the message to create.
1470 New event message reference, or \c NULL on memory error.
1472 @bt_pre_not_null{self_message_iterator}
1474 The \bt_stream_cls of \bt_p{event_class} is also the class of
1475 \bt_p{stream}, that is,
1476 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1478 <code>bt_stream_borrow_class_const(stream)</code> have the
1480 @bt_pre_not_null{stream}
1482 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1485 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1488 @bt_post_success_frozen{event_class}
1489 @bt_post_success_frozen{stream}
1492 bt_message
*bt_message_event_create(
1493 bt_self_message_iterator
*self_message_iterator
,
1494 const bt_event_class
*event_class
,
1495 const bt_stream
*stream
);
1499 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1500 \bt_p{event_class} and a default \bt_cs with the value
1501 \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
1502 the \bt_msg_iter \bt_p{self_message_iterator}.
1506 Only use this function if
1509 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1512 returns #BT_FALSE and
1515 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1518 does \em not return \c NULL.
1521 bt_message_event_create(),
1522 bt_message_event_create_with_packet(), or
1523 bt_message_event_create_with_packet_and_default_clock_snapshot().
1526 On success, the returned event message has the following property
1534 <td>\ref api-msg-ev-prop-ev "Event"
1536 An instance (with \bt_p_field that are not set) of
1539 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1540 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1543 @param[in] self_message_iterator
1544 Self message iterator from which to create the event message.
1545 @param[in] event_class
1546 Class of the \bt_ev of the message to create.
1548 Stream conceptually containing the event of the message to create.
1549 @param[in] clock_snapshot_value
1550 Value (clock cycles) of the default clock snapshot of
1554 New event message reference, or \c NULL on memory error.
1556 @bt_pre_not_null{self_message_iterator}
1558 The \bt_stream_cls of \bt_p{event_class} is also the class of
1559 \bt_p{stream}, that is,
1560 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1562 <code>bt_stream_borrow_class_const(stream)</code> have the
1564 @bt_pre_not_null{stream}
1566 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1569 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1570 does \em not return \c NULL.
1572 @bt_post_success_frozen{event_class}
1573 @bt_post_success_frozen{stream}
1576 bt_message
*bt_message_event_create_with_default_clock_snapshot(
1577 bt_self_message_iterator
*self_message_iterator
,
1578 const bt_event_class
*event_class
,
1579 const bt_stream
*stream
, uint64_t clock_snapshot_value
);
1583 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1584 \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
1585 \bt_msg_iter \bt_p{self_message_iterator}.
1589 Only use this function if
1592 bt_stream_class_supports_packets(
1593 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1596 returns #BT_TRUE and
1599 bt_stream_class_borrow_default_clock_class_const(
1600 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1606 bt_message_event_create(),
1607 bt_message_event_create_with_default_clock_snapshot(), or
1608 bt_message_event_create_with_packet_and_default_clock_snapshot().
1611 On success, the returned event message has the following property
1619 <td>\ref api-msg-ev-prop-ev "Event"
1621 An instance (with \bt_p_field that are not set) of
1624 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1628 @param[in] self_message_iterator
1629 Self message iterator from which to create the event message.
1630 @param[in] event_class
1631 Class of the \bt_ev of the message to create.
1633 Packet conceptually containing the event of the message to create.
1636 New event message reference, or \c NULL on memory error.
1638 @bt_pre_not_null{self_message_iterator}
1640 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1641 \bt_p{packet}, that is,
1642 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1644 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1645 have the same value.
1646 @bt_pre_not_null{packet}
1648 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1651 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1654 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1655 any, and all its contained \bt_p_field, recursively, are set.
1657 @bt_post_success_frozen{event_class}
1658 @bt_post_success_frozen{packet}
1661 bt_message
*bt_message_event_create_with_packet(
1662 bt_self_message_iterator
*self_message_iterator
,
1663 const bt_event_class
*event_class
,
1664 const bt_packet
*packet
);
1668 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1669 \bt_p{event_class} and a default \bt_cs with the value
1670 \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
1671 the \bt_msg_iter \bt_p{self_message_iterator}.
1675 Only use this function if
1678 bt_stream_class_supports_packets(
1679 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1682 returns #BT_TRUE and
1685 bt_stream_class_borrow_default_clock_class_const(
1686 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1689 does \em not return \c NULL.
1692 bt_message_event_create(),
1693 bt_message_event_create_with_default_clock_snapshot(), or
1694 bt_message_event_create_with_packet().
1697 On success, the returned event message has the following property
1705 <td>\ref api-msg-ev-prop-ev "Event"
1707 An instance (with \bt_p_field that are not set) of
1710 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1711 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1714 @param[in] self_message_iterator
1715 Self message iterator from which to create the event message.
1716 @param[in] event_class
1717 Class of the \bt_ev of the message to create.
1719 Packet conceptually containing the event of the message to create.
1720 @param[in] clock_snapshot_value
1721 Value (clock cycles) of the default clock snapshot of
1725 New event message reference, or \c NULL on memory error.
1727 @bt_pre_not_null{self_message_iterator}
1729 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1730 \bt_p{packet}, that is,
1731 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1733 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1734 have the same value.
1735 @bt_pre_not_null{packet}
1737 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1740 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1741 does \em not return \c NULL.
1743 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1744 any, and all its contained \bt_p_field, recursively, are set.
1746 @bt_post_success_frozen{event_class}
1747 @bt_post_success_frozen{stream}
1750 bt_message
*bt_message_event_create_with_packet_and_default_clock_snapshot(
1751 bt_self_message_iterator
*self_message_iterator
,
1752 const bt_event_class
*event_class
,
1753 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1757 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
1759 See the \ref api-msg-ev-prop-ev "event" property.
1762 Event message from which to borrow the event.
1766 \em Borrowed reference of the event of \bt_p{message}.
1768 The returned pointer remains valid as long as \bt_p{message} exists.
1771 @bt_pre_not_null{message}
1772 @bt_pre_is_ev_msg{message}
1774 @sa bt_message_event_borrow_event_const() —
1775 \c const version of this function.
1777 extern bt_event
*bt_message_event_borrow_event(
1778 bt_message
*message
);
1782 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
1785 See bt_message_event_borrow_event().
1787 extern const bt_event
*bt_message_event_borrow_event_const(
1788 const bt_message
*message
);
1792 Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
1794 See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
1797 Event message from which to borrow the default clock snapshot.
1800 Default clock snapshot of \bt_p{message}.
1802 @bt_pre_not_null{message}
1803 @bt_pre_is_ev_msg{message}
1805 The \bt_stream_cls of \bt_p{message} has a
1806 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1808 extern const bt_clock_snapshot
*
1809 bt_message_event_borrow_default_clock_snapshot_const(const bt_message
*message
);
1813 Borrows the default \bt_clock_cls of the \bt_stream_cls
1814 of the \bt_ev_msg \bt_p{message}.
1816 See the stream class's
1817 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1820 This is a helper which is equivalent to
1823 bt_stream_class_borrow_default_clock_class_const(
1824 bt_stream_borrow_class_const(
1825 bt_event_borrow_stream_const(
1826 bt_message_event_borrow_event_const(message))))
1830 Event message from which to borrow its stream's class's
1831 default clock class.
1834 \em Borrowed reference of the default clock class of
1835 the stream class of \bt_p{message}, or \c NULL if none.
1837 @bt_pre_not_null{message}
1838 @bt_pre_is_ev_msg{message}
1840 extern const bt_clock_class
*
1841 bt_message_event_borrow_stream_class_default_clock_class_const(
1842 const bt_message
*message
);
1847 @name Packet beginning message
1853 Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
1854 \bt_msg_iter \bt_p{self_message_iterator}.
1858 Only use this function if
1861 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1862 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1868 bt_message_packet_beginning_create_with_default_clock_snapshot().
1871 On success, the returned packet beginning message has the following
1879 <td>\ref api-msg-pb-prop-pkt "Packet"
1882 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1886 @param[in] self_message_iterator
1887 Self message iterator from which to create the packet beginning
1890 Packet of which the message to create indicates the beginning.
1893 New packet beginning message reference, or \c NULL on memory error.
1895 @bt_pre_not_null{self_message_iterator}
1896 @bt_pre_not_null{packet}
1898 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1899 returns #BT_FALSE for
1900 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1902 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1903 any, and all its contained \bt_p_field, recursively, are set.
1905 @bt_post_success_frozen{packet}
1908 bt_message
*bt_message_packet_beginning_create(
1909 bt_self_message_iterator
*self_message_iterator
,
1910 const bt_packet
*packet
);
1914 Creates a \bt_pb_msg having a default \bt_cs with the value
1915 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
1916 \bt_msg_iter \bt_p{self_message_iterator}.
1920 Only use this function if
1923 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1924 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1930 bt_message_packet_beginning_create().
1933 On success, the returned packet beginning message has the following
1941 <td>\ref api-msg-pb-prop-pkt "Packet"
1944 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1945 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1948 @param[in] self_message_iterator
1949 Self message iterator from which to create the packet beginning
1952 Packet of which the message to create indicates the beginning.
1953 @param[in] clock_snapshot_value
1954 Value (clock cycles) of the default clock snapshot of
1958 New packet beginning message reference, or \c NULL on memory error.
1960 @bt_pre_not_null{self_message_iterator}
1961 @bt_pre_not_null{packet}
1963 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1964 returns #BT_TRUE for
1965 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1967 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1968 any, and all its contained \bt_p_field, recursively, are set.
1970 @bt_post_success_frozen{packet}
1973 bt_message
*bt_message_packet_beginning_create_with_default_clock_snapshot(
1974 bt_self_message_iterator
*self_message_iterator
,
1975 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1979 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
1981 See the \ref api-msg-pb-prop-pkt "packet" property.
1984 Packet beginning message from which to borrow the packet.
1988 \em Borrowed reference of the packet of \bt_p{message}.
1990 The returned pointer remains valid as long as \bt_p{message} exists.
1993 @bt_pre_not_null{message}
1994 @bt_pre_is_pb_msg{message}
1996 @sa bt_message_packet_beginning_borrow_packet_const() —
1997 \c const version of this function.
1999 extern bt_packet
*bt_message_packet_beginning_borrow_packet(
2000 bt_message
*message
);
2004 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
2007 See bt_message_packet_beginning_borrow_packet().
2009 extern const bt_packet
*bt_message_packet_beginning_borrow_packet_const(
2010 const bt_message
*message
);
2014 Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
2016 See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
2019 Packet beginning message from which to borrow the default clock
2023 Default clock snapshot of \bt_p{message}.
2025 @bt_pre_not_null{message}
2026 @bt_pre_is_pb_msg{message}
2028 The packets of the \bt_stream_cls of \bt_p{message}
2029 \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
2031 extern const bt_clock_snapshot
*
2032 bt_message_packet_beginning_borrow_default_clock_snapshot_const(
2033 const bt_message
*message
);
2037 Borrows the default \bt_clock_cls of the \bt_stream_cls
2038 of the \bt_pb_msg \bt_p{message}.
2040 See the stream class's
2041 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2044 This is a helper which is equivalent to
2047 bt_stream_class_borrow_default_clock_class_const(
2048 bt_stream_borrow_class_const(
2049 bt_packet_borrow_stream_const(
2050 bt_message_packet_beginning_borrow_packet_const(message))))
2054 Packet beginning message from which to borrow its stream's class's
2055 default clock class.
2058 \em Borrowed reference of the default clock class of
2059 the stream class of \bt_p{message}, or \c NULL if none.
2061 @bt_pre_not_null{message}
2062 @bt_pre_is_pb_msg{message}
2064 extern const bt_clock_class
*
2065 bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
2066 const bt_message
*message
);
2071 @name Packet end message
2077 Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
2078 \bt_msg_iter \bt_p{self_message_iterator}.
2082 Only use this function if
2085 bt_stream_class_packets_have_end_default_clock_snapshot(
2086 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2092 bt_message_packet_end_create_with_default_clock_snapshot().
2095 On success, the returned packet end message has the following
2103 <td>\ref api-msg-pe-prop-pkt "Packet"
2106 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2110 @param[in] self_message_iterator
2111 Self message iterator from which to create the packet end message.
2113 Packet of which the message to create indicates the end.
2116 New packet end message reference, or \c NULL on memory error.
2118 @bt_pre_not_null{self_message_iterator}
2119 @bt_pre_not_null{packet}
2121 bt_stream_class_packets_have_end_default_clock_snapshot()
2122 returns #BT_FALSE for
2123 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2125 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2126 any, and all its contained \bt_p_field, recursively, are set.
2128 @bt_post_success_frozen{packet}
2131 bt_message
*bt_message_packet_end_create(
2132 bt_self_message_iterator
*self_message_iterator
,
2133 const bt_packet
*packet
);
2137 Creates a \bt_pe_msg having a default \bt_cs with the value
2138 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
2139 \bt_msg_iter \bt_p{self_message_iterator}.
2143 Only use this function if
2146 bt_stream_class_packets_have_end_default_clock_snapshot(
2147 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2153 bt_message_packet_end_create().
2156 On success, the returned packet end message has the following
2164 <td>\ref api-msg-pe-prop-pkt "Packet"
2167 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2168 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
2171 @param[in] self_message_iterator
2172 Self message iterator from which to create the packet end
2175 Packet of which the message to create indicates the end.
2176 @param[in] clock_snapshot_value
2177 Value (clock cycles) of the default clock snapshot of
2181 New packet end message reference, or \c NULL on memory error.
2183 @bt_pre_not_null{self_message_iterator}
2184 @bt_pre_not_null{packet}
2186 bt_stream_class_packets_have_end_default_clock_snapshot()
2187 returns #BT_TRUE for
2188 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2190 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2191 any, and all its contained \bt_p_field, recursively, are set.
2193 @bt_post_success_frozen{packet}
2196 bt_message
*bt_message_packet_end_create_with_default_clock_snapshot(
2197 bt_self_message_iterator
*self_message_iterator
,
2198 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
2202 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
2204 See the \ref api-msg-pe-prop-pkt "packet" property.
2207 Packet end message from which to borrow the packet.
2211 \em Borrowed reference of the packet of \bt_p{message}.
2213 The returned pointer remains valid as long as \bt_p{message} exists.
2216 @bt_pre_not_null{message}
2217 @bt_pre_is_pe_msg{message}
2219 @sa bt_message_packet_end_borrow_packet_const() —
2220 \c const version of this function.
2222 extern bt_packet
*bt_message_packet_end_borrow_packet(
2223 bt_message
*message
);
2227 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
2230 See bt_message_packet_end_borrow_packet().
2232 extern const bt_packet
*bt_message_packet_end_borrow_packet_const(
2233 const bt_message
*message
);
2237 Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
2239 See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
2242 Packet end message from which to borrow the default clock
2246 Default clock snapshot of \bt_p{message}.
2248 @bt_pre_not_null{message}
2249 @bt_pre_is_pe_msg{message}
2251 The packets of the \bt_stream_cls of \bt_p{message}
2252 \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
2254 extern const bt_clock_snapshot
*
2255 bt_message_packet_end_borrow_default_clock_snapshot_const(
2256 const bt_message
*message
);
2260 Borrows the default \bt_clock_cls of the \bt_stream_cls
2261 of the \bt_pe_msg \bt_p{message}.
2263 See the stream class's
2264 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2267 This is a helper which is equivalent to
2270 bt_stream_class_borrow_default_clock_class_const(
2271 bt_stream_borrow_class_const(
2272 bt_packet_borrow_stream_const(
2273 bt_message_packet_end_borrow_packet_const(message))))
2277 Packet end message from which to borrow its stream's class's
2278 default clock class.
2281 \em Borrowed reference of the default clock class of
2282 the stream class of \bt_p{message}, or \c NULL if none.
2284 @bt_pre_not_null{message}
2285 @bt_pre_is_pe_msg{message}
2287 extern const bt_clock_class
*
2288 bt_message_packet_end_borrow_stream_class_default_clock_class_const(
2289 const bt_message
*message
);
2294 @name Discarded events message
2300 Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
2301 \bt_msg_iter \bt_p{self_message_iterator}.
2305 Only use this function if
2308 bt_stream_class_discarded_events_have_default_clock_snapshots(
2309 bt_stream_borrow_class_const(stream))
2315 bt_message_discarded_events_create_with_default_clock_snapshots().
2318 On success, the returned discarded events message has the following
2326 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2329 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2332 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2335 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2339 @param[in] self_message_iterator
2340 Self message iterator from which to create the discarded events
2343 Stream from which the events were discarded.
2346 New discarded events message reference, or \c NULL on memory error.
2348 @bt_pre_not_null{self_message_iterator}
2349 @bt_pre_not_null{stream}
2351 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2354 @bt_post_success_frozen{stream}
2356 extern bt_message
*bt_message_discarded_events_create(
2357 bt_self_message_iterator
*self_message_iterator
,
2358 const bt_stream
*stream
);
2362 Creates a \bt_disc_ev_msg having the beginning and end default
2363 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2364 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2365 from the \bt_msg_iter \bt_p{self_message_iterator}.
2369 Only use this function if
2372 bt_stream_class_discarded_events_have_default_clock_snapshots(
2373 bt_stream_borrow_class_const(stream))
2379 bt_message_discarded_events_create().
2382 On success, the returned discarded events message has the following
2390 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2393 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2394 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2396 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2397 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2399 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2403 @param[in] self_message_iterator
2404 Self message iterator from which to create the discarded events
2407 Stream from which the events were discarded.
2408 @param[in] beginning_clock_snapshot_value
2409 Value (clock cycles) of the beginning default clock snapshot of
2411 @param[in] end_clock_snapshot_value
2412 Value (clock cycles) of the end default clock snapshot of
2416 New discarded events message reference, or \c NULL on memory error.
2418 @bt_pre_not_null{self_message_iterator}
2419 @bt_pre_not_null{stream}
2421 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2423 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2425 @bt_post_success_frozen{stream}
2427 extern bt_message
*bt_message_discarded_events_create_with_default_clock_snapshots(
2428 bt_self_message_iterator
*self_message_iterator
,
2429 const bt_stream
*stream
,
2430 uint64_t beginning_clock_snapshot_value
,
2431 uint64_t end_clock_snapshot_value
);
2435 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2437 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2440 Discarded events message from which to borrow the stream.
2444 \em Borrowed reference of the stream of \bt_p{message}.
2446 The returned pointer remains valid as long as \bt_p{message} exists.
2449 @bt_pre_not_null{message}
2450 @bt_pre_is_disc_ev_msg{message}
2452 @sa bt_message_discarded_events_borrow_stream_const() —
2453 \c const version of this function.
2455 extern bt_stream
*bt_message_discarded_events_borrow_stream(
2456 bt_message
*message
);
2460 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2463 See bt_message_discarded_events_borrow_stream().
2465 extern const bt_stream
*
2466 bt_message_discarded_events_borrow_stream_const(const bt_message
*message
);
2470 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2474 \ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2478 Discarded events message from which to borrow the beginning default
2482 Beginning default clock snapshot of \bt_p{message}.
2484 @bt_pre_not_null{message}
2485 @bt_pre_is_disc_ev_msg{message}
2487 The discarded packets messages of the \bt_stream_cls of
2489 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2491 extern const bt_clock_snapshot
*
2492 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
2493 const bt_message
*message
);
2497 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2501 \ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2505 Discarded events message from which to borrow the end default clock
2509 End default clock snapshot of \bt_p{message}.
2511 @bt_pre_not_null{message}
2512 @bt_pre_is_disc_ev_msg{message}
2514 The discarded packets messages of the \bt_stream_cls of
2516 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2518 extern const bt_clock_snapshot
*
2519 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
2520 const bt_message
*message
);
2524 Borrows the default \bt_clock_cls of the \bt_stream_cls
2525 of the \bt_disc_ev_msg \bt_p{message}.
2527 See the stream class's
2528 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2531 This is a helper which is equivalent to
2534 bt_stream_class_borrow_default_clock_class_const(
2535 bt_stream_borrow_class_const(
2536 bt_message_discarded_events_borrow_stream_const(message)))
2540 Discarded events message from which to borrow its stream's class's
2541 default clock class.
2544 \em Borrowed reference of the default clock class of
2545 the stream class of \bt_p{message}, or \c NULL if none.
2547 @bt_pre_not_null{message}
2548 @bt_pre_is_disc_ev_msg{message}
2550 extern const bt_clock_class
*
2551 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
2552 const bt_message
*message
);
2556 Sets the number of discarded events of the \bt_disc_ev_msg
2557 \bt_p{message} to \bt_p{count}.
2559 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2563 Discarded events message of which to set the number of discarded
2564 events to \bt_p{count}.
2566 New number of discarded events of \bt_p{message}.
2568 @bt_pre_not_null{message}
2569 @bt_pre_hot{message}
2570 @bt_pre_is_disc_ev_msg{message}
2572 @sa bt_message_discarded_events_get_count() —
2573 Returns the number of discarded events of a discarded events
2576 extern void bt_message_discarded_events_set_count(bt_message
*message
,
2581 Returns the number of discarded events of the \bt_disc_ev_msg
2584 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2588 Discarded events message of which to get the number of discarded
2591 <strong>If this function returns
2592 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2593 the number of discarded events of \bt_p{message}.
2595 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2596 The number of discarded events of \bt_p{message} is available.
2597 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2598 The number of discarded events of \bt_p{message} is not available.
2600 @bt_pre_not_null{message}
2601 @bt_pre_is_disc_ev_msg{message}
2602 @bt_pre_not_null{count}
2604 @sa bt_message_discarded_events_set_count() —
2605 Sets the number of discarded events of a discarded events message.
2607 extern bt_property_availability
bt_message_discarded_events_get_count(
2608 const bt_message
*message
, uint64_t *count
);
2613 @name Discarded packets message
2619 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2620 \bt_msg_iter \bt_p{self_message_iterator}.
2624 Only use this function if
2627 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2628 bt_stream_borrow_class_const(stream))
2634 bt_message_discarded_packets_create_with_default_clock_snapshots().
2637 On success, the returned discarded packets message has the following
2645 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2648 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2651 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2654 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2658 @param[in] self_message_iterator
2659 Self message iterator from which to create the discarded packets
2662 Stream from which the packets were discarded.
2665 New discarded packets message reference, or \c NULL on memory error.
2667 @bt_pre_not_null{self_message_iterator}
2668 @bt_pre_not_null{stream}
2670 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2673 @bt_post_success_frozen{stream}
2675 extern bt_message
*bt_message_discarded_packets_create(
2676 bt_self_message_iterator
*self_message_iterator
,
2677 const bt_stream
*stream
);
2681 Creates a \bt_disc_pkt_msg having the beginning and end default
2682 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2683 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2684 from the \bt_msg_iter \bt_p{self_message_iterator}.
2688 Only use this function if
2691 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2692 bt_stream_borrow_class_const(stream))
2698 bt_message_discarded_packets_create().
2701 On success, the returned discarded packets message has the following
2709 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2712 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2713 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2715 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2716 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2718 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2722 @param[in] self_message_iterator
2723 Self message iterator from which to create the discarded packets
2726 Stream from which the packets were discarded.
2727 @param[in] beginning_clock_snapshot_value
2728 Value (clock cycles) of the beginning default clock snapshot of
2730 @param[in] end_clock_snapshot_value
2731 Value (clock cycles) of the end default clock snapshot of
2735 New discarded packets message reference, or \c NULL on memory error.
2737 @bt_pre_not_null{self_message_iterator}
2738 @bt_pre_not_null{stream}
2740 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2742 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2744 @bt_post_success_frozen{stream}
2746 extern bt_message
*bt_message_discarded_packets_create_with_default_clock_snapshots(
2747 bt_self_message_iterator
*self_message_iterator
,
2748 const bt_stream
*stream
, uint64_t beginning_clock_snapshot_value
,
2749 uint64_t end_clock_snapshot_value
);
2753 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2755 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2758 Discarded packets message from which to borrow the stream.
2762 \em Borrowed reference of the stream of \bt_p{message}.
2764 The returned pointer remains valid as long as \bt_p{message} exists.
2767 @bt_pre_not_null{message}
2768 @bt_pre_is_disc_pkt_msg{message}
2770 @sa bt_message_discarded_packets_borrow_stream_const() —
2771 \c const version of this function.
2773 extern bt_stream
*bt_message_discarded_packets_borrow_stream(
2774 bt_message
*message
);
2778 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2781 See bt_message_discarded_packets_borrow_stream().
2783 extern const bt_stream
*
2784 bt_message_discarded_packets_borrow_stream_const(const bt_message
*message
);
2788 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2792 \ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2796 Discarded packets message from which to borrow the beginning default
2800 Beginning default clock snapshot of \bt_p{message}.
2802 @bt_pre_not_null{message}
2803 @bt_pre_is_disc_pkt_msg{message}
2805 The discarded packets messages of the \bt_stream_cls of
2807 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2809 extern const bt_clock_snapshot
*
2810 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
2811 const bt_message
*message
);
2815 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2819 \ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2823 Discarded packets message from which to borrow the end default clock
2827 End default clock snapshot of \bt_p{message}.
2829 @bt_pre_not_null{message}
2830 @bt_pre_is_disc_pkt_msg{message}
2832 The discarded packets messages of the \bt_stream_cls of
2834 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2836 extern const bt_clock_snapshot
*
2837 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
2838 const bt_message
*message
);
2842 Borrows the default \bt_clock_cls of the \bt_stream_cls
2843 of the \bt_disc_pkt_msg \bt_p{message}.
2845 See the stream class's
2846 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2849 This is a helper which is equivalent to
2852 bt_stream_class_borrow_default_clock_class_const(
2853 bt_stream_borrow_class_const(
2854 bt_message_discarded_packets_borrow_stream_const(message)))
2858 Discarded packets message from which to borrow its stream's class's
2859 default clock class.
2862 \em Borrowed reference of the default clock class of
2863 the stream class of \bt_p{message}, or \c NULL if none.
2865 @bt_pre_not_null{message}
2866 @bt_pre_is_disc_pkt_msg{message}
2868 extern const bt_clock_class
*
2869 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
2870 const bt_message
*message
);
2874 Sets the number of discarded packets of the \bt_disc_pkt_msg
2875 \bt_p{message} to \bt_p{count}.
2877 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2881 Discarded packets message of which to set the number of discarded
2882 packets to \bt_p{count}.
2884 New number of discarded packets of \bt_p{message}.
2886 @bt_pre_not_null{message}
2887 @bt_pre_hot{message}
2888 @bt_pre_is_disc_pkt_msg{message}
2890 @sa bt_message_discarded_packets_get_count() —
2891 Returns the number of discarded packets of a discarded packets
2894 extern void bt_message_discarded_packets_set_count(bt_message
*message
,
2899 Returns the number of discarded packets of the \bt_disc_pkt_msg
2902 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2906 Discarded packets message of which to get the number of discarded
2909 <strong>If this function returns
2910 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2911 the number of discarded packets of \bt_p{message}.
2913 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2914 The number of discarded packets of \bt_p{message} is available.
2915 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2916 The number of discarded packets of \bt_p{message} is not available.
2918 @bt_pre_not_null{message}
2919 @bt_pre_is_disc_pkt_msg{message}
2920 @bt_pre_not_null{count}
2922 @sa bt_message_discarded_packets_set_count() —
2923 Sets the number of discarded packets of a discarded packets message.
2925 extern bt_property_availability
bt_message_discarded_packets_get_count(
2926 const bt_message
*message
, uint64_t *count
);
2931 @name Message iterator inactivity message
2937 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2938 the \bt_clock_cls \bt_p{clock_class} with the value
2939 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2940 \bt_p{self_message_iterator}.
2942 On success, the returned message iterator inactivity message has the
2943 following property values:
2950 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2952 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2953 with the value \bt_p{clock_snapshot_value}.
2956 @param[in] self_message_iterator
2957 Self message iterator from which to create the message iterator
2959 @param[in] clock_class
2960 Class of the fictitious instance of which
2961 \bt_p{clock_snapshot_value} is the value of its snapshot.
2962 @param[in] clock_snapshot_value
2963 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2966 New message iterator inactivity message reference, or \c NULL on
2969 @bt_pre_not_null{self_message_iterator}
2970 @bt_pre_not_null{clock_class}
2972 @bt_post_success_frozen{clock_class}
2975 bt_message
*bt_message_message_iterator_inactivity_create(
2976 bt_self_message_iterator
*self_message_iterator
,
2977 const bt_clock_class
*clock_class
,
2978 uint64_t clock_snapshot_value
);
2982 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2984 See the \ref api-msg-inac-prop-cs "clock snapshot" property.
2987 Message iterator inactivity message from which to borrow the clock
2991 Clock snapshot of \bt_p{message}.
2993 @bt_pre_not_null{message}
2994 @bt_pre_is_inac_msg{message}
2996 extern const bt_clock_snapshot
*
2997 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
2998 const bt_message
*message
);
3003 @name Message reference count
3009 Increments the \ref api-fund-shared-object "reference count" of
3010 the message \bt_p{message}.
3014 Message of which to increment the reference count.
3019 @sa bt_message_put_ref() —
3020 Decrements the reference count of a message.
3022 extern void bt_message_get_ref(const bt_message
*message
);
3026 Decrements the \ref api-fund-shared-object "reference count" of
3027 the message \bt_p{message}.
3031 Message of which to decrement the reference count.
3036 @sa bt_message_get_ref() —
3037 Increments the reference count of a message.
3039 extern void bt_message_put_ref(const bt_message
*message
);
3043 Decrements the reference count of the message \bt_p{_message}, and
3044 then sets \bt_p{_message} to \c NULL.
3048 Message of which to decrement the reference count.
3050 Can contain \c NULL.
3053 @bt_pre_assign_expr{_message}
3055 #define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3057 bt_message_put_ref(_message); \
3058 (_message) = NULL; \
3063 Decrements the reference count of the message \bt_p{_dst}, sets
3064 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3066 This macro effectively moves a message reference from the expression
3067 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3068 \bt_p{_dst} reference.
3072 Destination expression.
3074 Can contain \c NULL.
3080 Can contain \c NULL.
3083 @bt_pre_assign_expr{_dst}
3084 @bt_pre_assign_expr{_src}
3086 #define BT_MESSAGE_MOVE_REF(_dst, _src) \
3088 bt_message_put_ref(_dst); \
3096 @name Message Interchange Protocol version
3102 Status codes for bt_get_greatest_operative_mip_version().
3104 typedef enum bt_get_greatest_operative_mip_version_status
{
3109 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3115 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
= __BT_FUNC_STATUS_NO_MATCH
,
3121 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3127 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
3128 } bt_get_greatest_operative_mip_version_status
;
3132 Computes the greatest \bt_mip version which
3133 you can use to create a trace processing \bt_graph to which you
3134 intend to \ref api-graph-lc-add "add components" described by the
3135 component descriptors \bt_p{component_descriptors}, and sets
3136 \bt_p{*mip_version} to the result.
3138 This function calls the
3139 \link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3140 method for each component descriptor in \bt_p{component_descriptors},
3141 and then returns the greatest common (operative) MIP version, if any.
3142 The "get supported MIP versions" method receives \bt_p{logging_level} as
3143 its \bt_p{logging_level} parameter.
3145 If this function does not find an operative MIP version for the
3146 component descriptors of \bt_p{component_descriptors}, it returns
3147 #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3150 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
3151 returns 0, this function always sets \bt_p{*mip_version} to
3154 @param[in] component_descriptors
3155 Component descriptors for which to get the supported MIP versions
3156 to compute the greatest operative MIP version.
3157 @param[in] logging_level
3158 Logging level to use when calling the "get supported MIP versions"
3159 method for each component descriptor in
3160 \bt_p{component_descriptors}.
3161 @param[out] mip_version
3162 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3163 operative MIP version of all the component descriptors in
3164 \bt_p{component_descriptors}.
3166 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3168 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3169 No operative MIP version exists for the component descriptors of
3170 \bt_p{component_descriptors}.
3171 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3173 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3176 @bt_pre_not_null{component_descriptors}
3178 \bt_p{component_descriptors} contains one or more component
3180 @bt_pre_not_null{mip_version}
3182 extern bt_get_greatest_operative_mip_version_status
3183 bt_get_greatest_operative_mip_version(
3184 const bt_component_descriptor_set
*component_descriptors
,
3185 bt_logging_level logging_level
, uint64_t *mip_version
);
3189 Returns the maximal available \bt_mip version as of
3190 \bt_name_version_min_maj.
3192 As of \bt_name_version_min_maj, this function returns
3193 \bt_max_mip_version.
3196 Maximal available MIP version (\bt_max_mip_version).
3198 extern uint64_t bt_get_maximal_mip_version(void);
3208 #endif /* BABELTRACE2_GRAPH_MESSAGE_H */