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>
2424 @bt_post_success_frozen{stream}
2426 extern bt_message
*bt_message_discarded_events_create_with_default_clock_snapshots(
2427 bt_self_message_iterator
*self_message_iterator
,
2428 const bt_stream
*stream
,
2429 uint64_t beginning_clock_snapshot_value
,
2430 uint64_t end_clock_snapshot_value
);
2434 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2436 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2439 Discarded events message from which to borrow the stream.
2443 \em Borrowed reference of the stream of \bt_p{message}.
2445 The returned pointer remains valid as long as \bt_p{message} exists.
2448 @bt_pre_not_null{message}
2449 @bt_pre_is_disc_ev_msg{message}
2451 @sa bt_message_discarded_events_borrow_stream_const() —
2452 \c const version of this function.
2454 extern bt_stream
*bt_message_discarded_events_borrow_stream(
2455 bt_message
*message
);
2459 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2462 See bt_message_discarded_events_borrow_stream().
2464 extern const bt_stream
*
2465 bt_message_discarded_events_borrow_stream_const(const bt_message
*message
);
2469 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2473 \ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2477 Discarded events message from which to borrow the beginning default
2481 Beginning default clock snapshot of \bt_p{message}.
2483 @bt_pre_not_null{message}
2484 @bt_pre_is_disc_ev_msg{message}
2486 The discarded packets messages of the \bt_stream_cls of
2488 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2490 extern const bt_clock_snapshot
*
2491 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
2492 const bt_message
*message
);
2496 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2500 \ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2504 Discarded events message from which to borrow the end default clock
2508 End default clock snapshot of \bt_p{message}.
2510 @bt_pre_not_null{message}
2511 @bt_pre_is_disc_ev_msg{message}
2513 The discarded packets messages of the \bt_stream_cls of
2515 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2517 extern const bt_clock_snapshot
*
2518 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
2519 const bt_message
*message
);
2523 Borrows the default \bt_clock_cls of the \bt_stream_cls
2524 of the \bt_disc_ev_msg \bt_p{message}.
2526 See the stream class's
2527 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2530 This is a helper which is equivalent to
2533 bt_stream_class_borrow_default_clock_class_const(
2534 bt_stream_borrow_class_const(
2535 bt_message_discarded_events_borrow_stream_const(message)))
2539 Discarded events message from which to borrow its stream's class's
2540 default clock class.
2543 \em Borrowed reference of the default clock class of
2544 the stream class of \bt_p{message}, or \c NULL if none.
2546 @bt_pre_not_null{message}
2547 @bt_pre_is_disc_ev_msg{message}
2549 extern const bt_clock_class
*
2550 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
2551 const bt_message
*message
);
2555 Sets the number of discarded events of the \bt_disc_ev_msg
2556 \bt_p{message} to \bt_p{count}.
2558 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2562 Discarded events message of which to set the number of discarded
2563 events to \bt_p{count}.
2565 New number of discarded events of \bt_p{message}.
2567 @bt_pre_not_null{message}
2568 @bt_pre_hot{message}
2569 @bt_pre_is_disc_ev_msg{message}
2571 @sa bt_message_discarded_events_get_count() —
2572 Returns the number of discarded events of a discarded events
2575 extern void bt_message_discarded_events_set_count(bt_message
*message
,
2580 Returns the number of discarded events of the \bt_disc_ev_msg
2583 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2587 Discarded events message of which to get the number of discarded
2590 <strong>If this function returns
2591 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2592 the number of discarded events of \bt_p{message}.
2594 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2595 The number of discarded events of \bt_p{message} is available.
2596 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2597 The number of discarded events of \bt_p{message} is not available.
2599 @bt_pre_not_null{message}
2600 @bt_pre_is_disc_ev_msg{message}
2601 @bt_pre_not_null{count}
2603 @sa bt_message_discarded_events_set_count() —
2604 Sets the number of discarded events of a discarded events message.
2606 extern bt_property_availability
bt_message_discarded_events_get_count(
2607 const bt_message
*message
, uint64_t *count
);
2612 @name Discarded packets message
2618 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2619 \bt_msg_iter \bt_p{self_message_iterator}.
2623 Only use this function if
2626 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2627 bt_stream_borrow_class_const(stream))
2633 bt_message_discarded_packets_create_with_default_clock_snapshots().
2636 On success, the returned discarded packets message has the following
2644 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2647 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2650 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2653 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2657 @param[in] self_message_iterator
2658 Self message iterator from which to create the discarded packets
2661 Stream from which the packets were discarded.
2664 New discarded packets message reference, or \c NULL on memory error.
2666 @bt_pre_not_null{self_message_iterator}
2667 @bt_pre_not_null{stream}
2669 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2672 @bt_post_success_frozen{stream}
2674 extern bt_message
*bt_message_discarded_packets_create(
2675 bt_self_message_iterator
*self_message_iterator
,
2676 const bt_stream
*stream
);
2680 Creates a \bt_disc_pkt_msg having the beginning and end default
2681 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2682 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2683 from the \bt_msg_iter \bt_p{self_message_iterator}.
2687 Only use this function if
2690 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2691 bt_stream_borrow_class_const(stream))
2697 bt_message_discarded_packets_create().
2700 On success, the returned discarded packets message has the following
2708 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2711 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2712 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2714 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2715 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2717 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2721 @param[in] self_message_iterator
2722 Self message iterator from which to create the discarded packets
2725 Stream from which the packets were discarded.
2726 @param[in] beginning_clock_snapshot_value
2727 Value (clock cycles) of the beginning default clock snapshot of
2729 @param[in] end_clock_snapshot_value
2730 Value (clock cycles) of the end default clock snapshot of
2734 New discarded packets message reference, or \c NULL on memory error.
2736 @bt_pre_not_null{self_message_iterator}
2737 @bt_pre_not_null{stream}
2739 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2742 @bt_post_success_frozen{stream}
2744 extern bt_message
*bt_message_discarded_packets_create_with_default_clock_snapshots(
2745 bt_self_message_iterator
*self_message_iterator
,
2746 const bt_stream
*stream
, uint64_t beginning_clock_snapshot_value
,
2747 uint64_t end_clock_snapshot_value
);
2751 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2753 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2756 Discarded packets message from which to borrow the stream.
2760 \em Borrowed reference of the stream of \bt_p{message}.
2762 The returned pointer remains valid as long as \bt_p{message} exists.
2765 @bt_pre_not_null{message}
2766 @bt_pre_is_disc_pkt_msg{message}
2768 @sa bt_message_discarded_packets_borrow_stream_const() —
2769 \c const version of this function.
2771 extern bt_stream
*bt_message_discarded_packets_borrow_stream(
2772 bt_message
*message
);
2776 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2779 See bt_message_discarded_packets_borrow_stream().
2781 extern const bt_stream
*
2782 bt_message_discarded_packets_borrow_stream_const(const bt_message
*message
);
2786 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2790 \ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2794 Discarded packets message from which to borrow the beginning default
2798 Beginning default clock snapshot of \bt_p{message}.
2800 @bt_pre_not_null{message}
2801 @bt_pre_is_disc_pkt_msg{message}
2803 The discarded packets messages of the \bt_stream_cls of
2805 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2807 extern const bt_clock_snapshot
*
2808 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
2809 const bt_message
*message
);
2813 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2817 \ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2821 Discarded packets message from which to borrow the end default clock
2825 End default clock snapshot of \bt_p{message}.
2827 @bt_pre_not_null{message}
2828 @bt_pre_is_disc_pkt_msg{message}
2830 The discarded packets messages of the \bt_stream_cls of
2832 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2834 extern const bt_clock_snapshot
*
2835 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
2836 const bt_message
*message
);
2840 Borrows the default \bt_clock_cls of the \bt_stream_cls
2841 of the \bt_disc_pkt_msg \bt_p{message}.
2843 See the stream class's
2844 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2847 This is a helper which is equivalent to
2850 bt_stream_class_borrow_default_clock_class_const(
2851 bt_stream_borrow_class_const(
2852 bt_message_discarded_packets_borrow_stream_const(message)))
2856 Discarded packets message from which to borrow its stream's class's
2857 default clock class.
2860 \em Borrowed reference of the default clock class of
2861 the stream class of \bt_p{message}, or \c NULL if none.
2863 @bt_pre_not_null{message}
2864 @bt_pre_is_disc_pkt_msg{message}
2866 extern const bt_clock_class
*
2867 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
2868 const bt_message
*message
);
2872 Sets the number of discarded packets of the \bt_disc_pkt_msg
2873 \bt_p{message} to \bt_p{count}.
2875 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2879 Discarded packets message of which to set the number of discarded
2880 packets to \bt_p{count}.
2882 New number of discarded packets of \bt_p{message}.
2884 @bt_pre_not_null{message}
2885 @bt_pre_hot{message}
2886 @bt_pre_is_disc_pkt_msg{message}
2888 @sa bt_message_discarded_packets_get_count() —
2889 Returns the number of discarded packets of a discarded packets
2892 extern void bt_message_discarded_packets_set_count(bt_message
*message
,
2897 Returns the number of discarded packets of the \bt_disc_pkt_msg
2900 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2904 Discarded packets message of which to get the number of discarded
2907 <strong>If this function returns
2908 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2909 the number of discarded packets of \bt_p{message}.
2911 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2912 The number of discarded packets of \bt_p{message} is available.
2913 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2914 The number of discarded packets of \bt_p{message} is not available.
2916 @bt_pre_not_null{message}
2917 @bt_pre_is_disc_pkt_msg{message}
2918 @bt_pre_not_null{count}
2920 @sa bt_message_discarded_packets_set_count() —
2921 Sets the number of discarded packets of a discarded packets message.
2923 extern bt_property_availability
bt_message_discarded_packets_get_count(
2924 const bt_message
*message
, uint64_t *count
);
2929 @name Message iterator inactivity message
2935 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2936 the \bt_clock_cls \bt_p{clock_class} with the value
2937 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2938 \bt_p{self_message_iterator}.
2940 On success, the returned message iterator inactivity message has the
2941 following property values:
2948 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2950 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2951 with the value \bt_p{clock_snapshot_value}.
2954 @param[in] self_message_iterator
2955 Self message iterator from which to create the message iterator
2957 @param[in] clock_class
2958 Class of the fictitious instance of which
2959 \bt_p{clock_snapshot_value} is the value of its snapshot.
2960 @param[in] clock_snapshot_value
2961 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2964 New message iterator inactivity message reference, or \c NULL on
2967 @bt_pre_not_null{self_message_iterator}
2968 @bt_pre_not_null{clock_class}
2970 @bt_post_success_frozen{clock_class}
2973 bt_message
*bt_message_message_iterator_inactivity_create(
2974 bt_self_message_iterator
*self_message_iterator
,
2975 const bt_clock_class
*clock_class
,
2976 uint64_t clock_snapshot_value
);
2980 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2982 See the \ref api-msg-inac-prop-cs "clock snapshot" property.
2985 Message iterator inactivity message from which to borrow the clock
2989 Clock snapshot of \bt_p{message}.
2991 @bt_pre_not_null{message}
2992 @bt_pre_is_inac_msg{message}
2994 extern const bt_clock_snapshot
*
2995 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
2996 const bt_message
*message
);
3001 @name Message reference count
3007 Increments the \ref api-fund-shared-object "reference count" of
3008 the message \bt_p{message}.
3012 Message of which to increment the reference count.
3017 @sa bt_message_put_ref() —
3018 Decrements the reference count of a message.
3020 extern void bt_message_get_ref(const bt_message
*message
);
3024 Decrements the \ref api-fund-shared-object "reference count" of
3025 the message \bt_p{message}.
3029 Message of which to decrement the reference count.
3034 @sa bt_message_get_ref() —
3035 Increments the reference count of a message.
3037 extern void bt_message_put_ref(const bt_message
*message
);
3041 Decrements the reference count of the message \bt_p{_message}, and
3042 then sets \bt_p{_message} to \c NULL.
3046 Message of which to decrement the reference count.
3048 Can contain \c NULL.
3051 @bt_pre_assign_expr{_message}
3053 #define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3055 bt_message_put_ref(_message); \
3056 (_message) = NULL; \
3061 Decrements the reference count of the message \bt_p{_dst}, sets
3062 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3064 This macro effectively moves a message reference from the expression
3065 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3066 \bt_p{_dst} reference.
3070 Destination expression.
3072 Can contain \c NULL.
3078 Can contain \c NULL.
3081 @bt_pre_assign_expr{_dst}
3082 @bt_pre_assign_expr{_src}
3084 #define BT_MESSAGE_MOVE_REF(_dst, _src) \
3086 bt_message_put_ref(_dst); \
3094 @name Message Interchange Protocol version
3100 Status codes for bt_get_greatest_operative_mip_version().
3102 typedef enum bt_get_greatest_operative_mip_version_status
{
3107 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3113 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
= __BT_FUNC_STATUS_NO_MATCH
,
3119 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3125 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
3126 } bt_get_greatest_operative_mip_version_status
;
3130 Computes the greatest \bt_mip version which
3131 you can use to create a trace processing \bt_graph to which you
3132 intend to \ref api-graph-lc-add "add components" described by the
3133 component descriptors \bt_p{component_descriptors}, and sets
3134 \bt_p{*mip_version} to the result.
3136 This function calls the
3137 \link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3138 method for each component descriptor in \bt_p{component_descriptors},
3139 and then returns the greatest common (operative) MIP version, if any.
3140 The "get supported MIP versions" method receives \bt_p{logging_level} as
3141 its \bt_p{logging_level} parameter.
3143 If this function does not find an operative MIP version for the
3144 component descriptors of \bt_p{component_descriptors}, it returns
3145 #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3148 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
3149 returns 0, this function always sets \bt_p{*mip_version} to
3152 @param[in] component_descriptors
3153 Component descriptors for which to get the supported MIP versions
3154 to compute the greatest operative MIP version.
3155 @param[in] logging_level
3156 Logging level to use when calling the "get supported MIP versions"
3157 method for each component descriptor in
3158 \bt_p{component_descriptors}.
3159 @param[out] mip_version
3160 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3161 operative MIP version of all the component descriptors in
3162 \bt_p{component_descriptors}.
3164 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3166 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3167 No operative MIP version exists for the component descriptors of
3168 \bt_p{component_descriptors}.
3169 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3171 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3174 @bt_pre_not_null{component_descriptors}
3176 \bt_p{component_descriptors} contains one or more component
3178 @bt_pre_not_null{mip_version}
3180 extern bt_get_greatest_operative_mip_version_status
3181 bt_get_greatest_operative_mip_version(
3182 const bt_component_descriptor_set
*component_descriptors
,
3183 bt_logging_level logging_level
, uint64_t *mip_version
);
3187 Returns the maximal available \bt_mip version as of
3188 \bt_name_version_min_maj.
3190 As of \bt_name_version_min_maj, this function returns
3191 \bt_max_mip_version.
3194 Maximal available MIP version (\bt_max_mip_version).
3196 extern uint64_t bt_get_maximal_mip_version(void);
3206 #endif /* BABELTRACE2_GRAPH_MESSAGE_H */