2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_MESSAGE_H
8 #define BABELTRACE2_GRAPH_MESSAGE_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-msg Messages
24 @ingroup api-comp-cls-dev
27 Elements exchanged between \bt_p_comp.
29 <strong><em>Messages</em></strong> are the objects which are exchanged
30 between \bt_p_comp in a trace processing \bt_graph to accomplish a
33 \bt_cp_msg_iter create messages while message iterators \em and
34 \bt_p_sink_comp consume messages.
36 There are eight types of messages:
47 The type of a message is #bt_message.
49 Get the type enumerator of a message with bt_message_get_type().
51 A message is a \ref api-fund-shared-object "shared object": get a
52 new reference with bt_message_get_ref() and put an existing
53 reference with bt_message_put_ref().
55 Some library functions \ref api-fund-freezing "freeze" messages on
56 success. The documentation of those functions indicate this
59 Messages transport objects of the \ref api-tir API, which is an
60 intermediate representation of the tracing domain concepts.
62 All types of messages, except the \bt_inac_msg type, are related to a
63 specific <em>\bt_stream</em>, which represents a conceptual
64 \ref api-msg-seq "sequence of messages".
66 Some types of messages can have a default \bt_cs, depending on whether
67 or not their stream has a conceptual default clock, that is, whether or
68 not the stream's \ref api-tir-stream-cls "class" has a
69 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
70 The creation functions for those types of messages contain
71 <code>_with_default_clock_snapshot</code> (for example,
72 bt_message_event_create_with_default_clock_snapshot()).
74 For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
75 is optional, therefore they have dedicated
76 bt_message_stream_beginning_set_default_clock_snapshot() and
77 bt_message_stream_end_set_default_clock_snapshot() functions.
79 All the message creation functions take a \bt_self_msg_iter as their
80 first parameter. This is because a message iterator method is the only
81 valid context to create a message.
83 <h1>Message types</h1>
85 This section details each type of message.
87 The following table shows the creation functions and types for each type
94 <th>Creation functions
96 <td>\ref api-msg-sb "Stream beginning"
97 <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
98 <td>bt_message_stream_beginning_create()
100 <td>\ref api-msg-se "Stream end"
101 <td>#BT_MESSAGE_TYPE_STREAM_END
102 <td>bt_message_stream_end_create()
104 <td>\ref api-msg-ev "Event"
105 <td>#BT_MESSAGE_TYPE_EVENT
107 bt_message_event_create()<br>
108 bt_message_event_create_with_default_clock_snapshot()<br>
109 bt_message_event_create_with_packet()<br>
110 bt_message_event_create_with_packet_and_default_clock_snapshot()
112 <td>\ref api-msg-pb "Packet beginning"
113 <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
115 bt_message_packet_beginning_create()<br>
116 bt_message_packet_beginning_create_with_default_clock_snapshot()
118 <td>\ref api-msg-pe "Packet end"
119 <td>#BT_MESSAGE_TYPE_PACKET_END
121 bt_message_packet_end_create()<br>
122 bt_message_packet_end_create_with_default_clock_snapshot()
124 <td>\ref api-msg-disc-ev "Discarded events"
125 <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
127 bt_message_discarded_events_create()<br>
128 bt_message_discarded_events_create_with_default_clock_snapshots()
130 <td>\ref api-msg-disc-pkt "Discarded packets"
131 <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
133 bt_message_discarded_packets_create()<br>
134 bt_message_discarded_packets_create_with_default_clock_snapshots()
136 <td>\ref api-msg-inac "Message iterator inactivity"
137 <td>#BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
138 <td>bt_message_message_iterator_inactivity_create()
141 <h2>\anchor api-msg-sb Stream beginning message</h2>
143 A <strong><em>stream beginning message</em></strong> indicates the
144 beginning of a \bt_stream.
148 - A stream beginning message is always the first one in the
149 \ref api-msg-seq "message sequence".
151 - There can be only one stream beginning message.
153 Create a stream beginning message with
154 bt_message_stream_beginning_create().
156 A stream beginning message has the following properties:
159 <dt>\anchor api-msg-sb-prop-stream Stream</dt>
161 \bt_c_stream of which the message indicates the beginning.
163 You cannot change the stream once the message is created.
165 Borrow a stream beginning message's stream with
166 bt_message_stream_beginning_borrow_stream() and
167 bt_message_stream_beginning_borrow_stream_const().
171 \anchor api-msg-sb-prop-cs
172 \bt_dt_opt Default \bt_cs
175 Snapshot of the message's \bt_stream's default clock when the
178 A stream beginning message can only have a default clock snapshot
179 if its stream's \ref api-tir-stream-cls "class" has a
180 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
182 When a stream beginning message has no default clock snapshot,
183 then its time is <em>unknown</em>.
185 Set a stream beginning message's default clock snapshot with
186 bt_message_stream_beginning_set_default_clock_snapshot().
188 Borrow a stream beginning message's default clock snapshot with
189 bt_message_stream_beginning_borrow_default_clock_snapshot_const().
193 <h2>\anchor api-msg-se Stream end message</h2>
195 A <strong><em>stream end message</em></strong> indicates the
200 - A stream end message is always the last one in the
201 \ref api-msg-seq "message sequence".
203 - There can be only one stream end message.
205 Create a stream end message with bt_message_stream_end_create().
207 A stream end message has the following properties:
210 <dt>\anchor api-msg-se-prop-stream Stream</dt>
212 \bt_c_stream of which the message indicates the end.
214 You cannot change the stream once the message is created.
216 Borrow a stream end message's stream with
217 bt_message_stream_end_borrow_stream() and
218 bt_message_stream_end_borrow_stream_const().
222 \anchor api-msg-se-prop-cs
223 \bt_dt_opt Default \bt_cs
226 Snapshot of the message's \bt_stream's default clock when the
229 A stream end message can only have a default clock snapshot
230 if its stream's \ref api-tir-stream-cls "class" has a
231 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
233 When a stream end message has no default clock snapshot, then its
234 time is <em>unknown</em>.
236 Set a stream end message's default clock snapshot with
237 bt_message_stream_end_set_default_clock_snapshot().
239 Borrow a stream end message's default clock snapshot with
240 bt_message_stream_end_borrow_default_clock_snapshot_const().
244 <h2>\anchor api-msg-ev Event message</h2>
246 An <strong><em>event message</em></strong> transports an \bt_ev and has,
247 possibly, a default \bt_cs.
249 Within its \bt_stream's \ref api-msg-seq "message sequence", an event
250 message can only occur:
254 If the stream's \ref api-tir-stream-cls "class"
255 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
257 <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
260 If the stream's class does not support packets
262 <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
265 To create an event message for a given stream, use:
269 If the stream's \ref api-tir-stream-cls "class"
270 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
275 If the stream's class has a
276 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
278 <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
281 If the stream's class does not have a
282 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
284 <dd>bt_message_event_create_with_packet()</dd>
287 Those two creation functions accept a \bt_pkt parameter which is
288 the packet logically containing the message's event. A packet is
293 If the stream's class does not supports packets
298 If the stream's class has a default clock class
300 <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
303 If the stream's class does not have a
304 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
306 <dd>bt_message_event_create()</dd>
311 The four creation functions above accept an \bt_ev_cls parameter. When
312 you create the message, the library instantiates this event class as an
313 \bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
314 This event class must be part of the class of the event message's
317 An event message's event is initially <em>not set</em>: before you emit
318 the event message from a \bt_msg_iter's
319 \link api-msg-iter-cls-meth-next "next" method\endlink, you need to
320 borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
321 bt_event_borrow_specific_context_field(), and
322 bt_event_borrow_common_context_field()) and, recursively, set the values
323 of the all their inner fields.
325 An event message has the following properties:
328 <dt>\anchor api-msg-ev-prop-ev Event</dt>
330 \bt_c_ev which the message transports.
332 This is an instance of the \bt_ev_cls which was passed to the
333 message's creation function.
335 With this event, you can access its \bt_pkt (if any) with
336 bt_event_borrow_packet_const() and its
337 \bt_stream with bt_event_borrow_stream_const().
339 Borrow an event message's event with bt_message_event_borrow_event()
340 and bt_message_event_borrow_event_const().
344 \anchor api-msg-ev-prop-cs
345 \bt_dt_opt Default \bt_cs
348 Snapshot of the message's \bt_stream's default clock when the
351 An event message has a default clock snapshot
352 if its stream's \ref api-tir-stream-cls "class" has a
353 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class",
354 and has none otherwise.
356 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
357 the default clock snapshot of an event message must be greater than
358 or equal to any default clock snapshot of any previous message.
360 Borrow an event message's default clock snapshot with
361 bt_message_event_borrow_default_clock_snapshot_const().
365 <h2>\anchor api-msg-pb Packet beginning message</h2>
367 A <strong><em>packet beginning message</em></strong> indicates the
368 beginning of a \bt_pkt.
370 A packet beginning message can only exist if its \bt_stream's
371 \ref api-tir-stream-cls "class"
372 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
374 For a given packet, there can be only one packet beginning message.
376 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
377 beginning message can only occur after the \bt_sb_msg and before the
380 To create a packet beginning message for a given stream, use:
384 If, for this stream's class,
385 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
387 <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
390 If, for this stream's class, packets do not have a beginning default
393 <dd>bt_message_packet_beginning_create()</dd>
396 A packet beginning message has the following properties:
399 <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
401 \bt_c_pkt of which the message indicates the beginning.
403 You cannot change the packet once the message is created.
405 Borrow a packet beginning message's packet with
406 bt_message_packet_beginning_borrow_packet() and
407 bt_message_packet_beginning_borrow_packet_const().
411 \anchor api-msg-pb-prop-cs
412 \bt_dt_opt Default \bt_cs
415 Snapshot of the message's \bt_stream's default clock when the
418 A packet beginning message has a default clock snapshot if:
420 - Its stream's \ref api-tir-stream-cls "class" has a
421 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
423 - For its stream's class,
424 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
426 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
427 the default clock snapshot of a packet beginning message must be
428 greater than or equal to any clock snapshot of any previous message.
430 Borrow a packet beginning message's default clock snapshot with
431 bt_message_packet_beginning_borrow_default_clock_snapshot_const().
435 <h2>\anchor api-msg-pe Packet end message</h2>
437 A <strong><em>packet end message</em></strong> indicates the
440 A packet end message can only exist if its \bt_stream's
441 \ref api-tir-stream-cls "class"
442 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
444 For a given packet, there can be only one packet end message.
446 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
447 end message can only occur:
449 - After the \bt_sb_msg and before the \bt_se_msg.
450 - After a \bt_pb_msg for the same packet.
452 To create a packet end message for a given stream, use:
456 If, for this stream's class,
457 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
459 <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
462 If, for this stream's class, packets do not have an end default
465 <dd>bt_message_packet_end_create()</dd>
468 A packet end message has the following properties:
471 <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
473 \bt_c_pkt of which the message indicates the end.
475 You cannot change the packet once the message is created.
477 Borrow a packet end message's packet with
478 bt_message_packet_end_borrow_packet() and
479 bt_message_packet_end_borrow_packet_const().
483 \anchor api-msg-pe-prop-cs
484 \bt_dt_opt Default \bt_cs
487 Snapshot of the message's \bt_stream's default clock when the
490 A packet end message has a default clock snapshot if:
492 - Its stream's \ref api-tir-stream-cls "class" has a
493 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
495 - For its stream's class,
496 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
498 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
499 the default clock snapshot of a packet end message must be greater
500 than or equal to any clock snapshot of any previous message.
502 Borrow a packet end message's default clock snapshot with
503 bt_message_packet_end_borrow_default_clock_snapshot_const().
507 <h2>\anchor api-msg-disc-ev Discarded events message</h2>
509 A <strong><em>discarded events message</em></strong> indicates that
510 events were discarded at <em>tracing time</em>. It does \em not indicate
511 that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
513 A discarded events message can only exist if its \bt_stream's
514 \ref api-tir-stream-cls "class"
515 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events".
517 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
518 events message can only occur after the \bt_sb_msg and before the
521 To create a discarded events message for a given stream, use:
525 If, for this stream's class,
526 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
528 <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
531 If, for this stream's class, discarded events do not have default
534 <dd>bt_message_discarded_events_create()</dd>
537 A discarded events message has the following properties:
540 <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
542 \bt_c_stream into which events were discarded.
544 You cannot change the stream once the message is created.
546 Borrow a discarded events message's stream with
547 bt_message_discarded_events_borrow_stream() and
548 bt_message_discarded_events_borrow_stream_const().
552 \anchor api-msg-disc-ev-prop-cs-beg
553 \bt_dt_opt Beginning default \bt_cs
556 Snapshot of the message's \bt_stream's default clock which indicates
557 the beginning of the discarded events time range.
559 A discarded events message has a beginning default clock snapshot
562 - Its stream's \ref api-tir-stream-cls "class" has a
563 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
565 - For its stream's class,
566 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
568 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
569 the beginning default clock snapshot of a discarded events message
570 must be greater than or equal to any clock snapshot of any previous
573 Borrow a discarded events message's beginning default clock snapshot
575 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
579 \anchor api-msg-disc-ev-prop-cs-end
580 \bt_dt_opt End default \bt_cs
583 Snapshot of the message's \bt_stream's default clock which indicates
584 the end of the discarded events time range.
586 A discarded events message has an end default clock snapshot if:
588 - Its stream's \ref api-tir-stream-cls "class" has a
589 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
591 - For its stream's class,
592 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
594 If a discarded events message has both a
595 \ref api-msg-disc-ev-prop-cs-beg "beginning" and an end default
596 clock snapshots, the end default clock snapshot must be greater than
597 or equal to the beginning default clock snapshot.
599 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
600 the end default clock snapshot of a discarded events message must be
601 greater than or equal to any clock snapshot of any previous message.
603 Borrow a discarded events message's end default clock snapshot with
604 bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
608 \anchor api-msg-disc-ev-prop-count
609 \bt_dt_opt Discarded event count
612 Exact number of discarded events.
614 If this property is missing, then the number of discarded events
617 Use bt_message_discarded_events_set_count() and
618 bt_message_discarded_events_get_count().
622 <h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
624 A <strong><em>discarded packets message</em></strong> indicates that
625 packets were discarded at <em>tracing time</em>. It does \em not
626 indicate that whole packets were dropped during a trace processing
629 A discarded packets message can only exist if its \bt_stream's
630 \ref api-tir-stream-cls "class"
631 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets".
633 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
634 packets message can only occur:
636 - After the \bt_sb_msg.
637 - Before the \bt_se_msg.
639 - Before any \bt_pb_msg.
640 - After any \bt_pe_msg.
641 - Between a packet end and a packet beginning message.
643 To create a discarded packets message for a given stream, use:
647 If, for this stream's class,
648 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
650 <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
653 If, for this stream's class, discarded packets do not have default
656 <dd>bt_message_discarded_packets_create()</dd>
659 A discarded packets message has the following properties:
662 <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
664 \bt_c_stream into which packets were discarded.
666 You cannot change the stream once the message is created.
668 Borrow a discarded packets message's stream with
669 bt_message_discarded_packets_borrow_stream() and
670 bt_message_discarded_packets_borrow_stream_const().
674 \anchor api-msg-disc-pkt-prop-cs-beg
675 \bt_dt_opt Beginning default \bt_cs
678 Snapshot of the message's \bt_stream's default clock which indicates
679 the beginning of the discarded packets time range.
681 A discarded packets message has a beginning default clock snapshot
684 - Its stream's \ref api-tir-stream-cls "class" has a
685 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
687 - For its stream's class,
688 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
690 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
691 the beginning default clock snapshot of a discarded packets message
692 must be greater than or equal to any clock snapshot of any previous
695 Borrow a discarded packets message's beginning default clock snapshot
697 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
701 \anchor api-msg-disc-pkt-prop-cs-end
702 \bt_dt_opt End default \bt_cs
705 Snapshot of the message's \bt_stream's default clock which indicates
706 the end of the discarded packets time range.
708 A discarded packets message has an end default clock snapshot if:
710 - Its stream's \ref api-tir-stream-cls "class" has a
711 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
713 - For its stream's class,
714 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
716 If a discarded packets message has both a
717 \ref api-msg-disc-pkt-prop-cs-beg "beginning" and an end default
718 clock snapshots, the end default clock snapshot must be greater than
719 or equal to the beginning default clock snapshot.
721 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
722 the end default clock snapshot of a discarded packets message must
723 be greater than or equal to any clock snapshot of any previous
726 Borrow a discarded packets message's end default clock snapshot with
727 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
731 \anchor api-msg-disc-pkt-prop-count
732 \bt_dt_opt Discarded packet count
735 Exact number of discarded packets.
737 If this property is missing, then the number of discarded packets
740 Use bt_message_discarded_packets_set_count() and
741 bt_message_discarded_packets_get_count().
745 <h2>\anchor api-msg-inac Message iterator inactivity</h2>
747 A <strong><em>message iterator inactivity message</em></strong>
748 indicates that, within the \ref api-msg-seq "message sequence" of a
749 given \bt_msg_iter, there's no messages since the last message (if any)
750 until a given point in time.
752 A message iterator inactivity message is the only type of message that's
753 not related to a \bt_stream: it targets the whole message sequence of a
754 message iterator, and can occur at any position within the sequence.
756 This message is mostly significant for real-time message iterators: if a
757 message iterator A indicates that there's no messages until a given
758 point in time T, then a downstream filter message iterator B which
759 relies on multiple upstream message iterators does not have to wait for
760 new messages from A until T.
762 In other words, a message iterator inactivity message can help
763 downstream message iterators or \bt_p_sink_comp <em>progress</em>.
765 Create a message iterator inactivity message with
766 bt_message_message_iterator_inactivity_create(). You must pass a
767 \bt_clock_cls and the value of a fictitious (clock) instance to this
768 function so that it creates a \bt_cs.
770 A message iterator inactivity message has the following property:
774 \anchor api-msg-inac-prop-cs
778 Snapshot of a fictitious instance of the message's \bt_clock_cls
779 which indicates the point in time until when there's no messages
780 in the message iterator's \ref api-msg-seq "message sequence".
782 Within its \bt_msg_iter's message sequence, the clock snapshot of a
783 message iterator inactivity message must be greater than or equal to
784 any clock snapshot of any previous message.
786 Borrow a message iterator inactivity message's clock snapshot
788 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
792 <h1>\anchor api-msg-mip Message Interchange Protocol</h1>
794 The <em>Message Interchange Protocol</em> (MIP) is the system of rules
795 used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
796 trace processing graph.
798 The MIP covers everything related to messages and what they contain, as
799 well as how they are ordered within the \ref api-msg-seq "sequence" that
800 a message iterator produces.
804 - A valid message sequence for a given \bt_stream starts with a
805 \bt_sb_msg and ends with a \bt_se_msg.
808 \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
809 is [0, 2<sup>64</sup> − 1].
811 - The available message types are stream beginning and end, event,
812 packet beginning and end, discarded events and packets, and message
815 The MIP has a version which is a single major number, independent from
816 the \bt_name project's version. As of \bt_name_version_min_maj, the only
817 available MIP version is 0.
819 If what the MIP covers changes in a breaking or semantical way in the
820 future, the MIP and \bt_name's minor versions will be bumped.
822 When you create a trace processing \bt_graph with bt_graph_create(), you
823 must pass the effective MIP version to use. Then, the components you
824 \ref api-graph-lc-add "add" to this graph can access this configured MIP
825 version with bt_self_component_get_graph_mip_version() and behave
826 accordingly. In other words, if the configured MIP version is 0, then a
827 component cannot use features introduced by MIP version 1. For
828 example, should the project introduce a new type of \bt_fc, the MIP
829 version would be bumped.
831 A component which cannot honor a given MIP can fail at
832 initialization time, making the corresponding
833 <code>bt_graph_add_*_component*()</code> call fail too. To avoid any
834 surprise, you can create a \bt_comp_descr_set with descriptors of the
835 components you intend to add to a trace processing graph and call
836 bt_get_greatest_operative_mip_version() to get the greatest (most
837 recent) MIP version you can use.
839 To get the library's latest MIP version, use
840 bt_get_maximal_mip_version().
842 The ultimate goal of the MIP version feature is for the \bt_name project
843 to be able to introduce new features or even major breaking changes
844 without breaking existing \bt_p_comp_cls. This is especially important
845 considering that \bt_name supports \bt_p_plugin written by different
846 authors. Of course one of the project's objectives is to bump the MIP
847 version as rarely as possible. When it is required, though, it's a
848 welcome tool to make the project evolve gracefully.
850 The Message Interchange Protocol has no dedicated documentation as this
851 very message module (and its submodules, like \ref api-tir)
852 documentation is enough. You can consider that all the
853 functions of the message and trace IR objects have an implicit MIP
854 version \ref api-fund-pre-post "precondition". When a given
855 function documentation does not explicitly document a MIP version
856 precondition, it means that the effective MIP version has no effect on
857 said function's behaviour.
859 <h2>\anchor api-msg-seq Message sequence rules</h2>
861 The purpose of a \bt_msg_iter is to iterate a sequence of messages.
863 Those messages can be related to different \bt_p_stream:
865 @image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
867 However, for such a message sequence, the current \bt_mip
868 (version \bt_max_mip_version) dictates that:
872 For a given \bt_stream:
874 - The sequence must begin with a \bt_sb_msg.
875 - The sequence must end with a \bt_se_msg.
876 - <strong>If the stream's \ref api-tir-stream-cls "class"
877 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"</strong>:
878 - Any \bt_pb_msg must be followed with a \bt_pe_msg.
879 - All \bt_p_ev_msg must be between a packet beginning and a
881 - A \bt_disc_pkt_msg must be (one of):
882 - Before the first packet beginning message.
883 - Between a packet end message and a packet beginning message.
884 - After the last packet end message.
886 The rules above can be summarized by the following regular
890 <dt>Without packets</dt>
897 <dt>With packets</dt>
900 SB ((PB (E | DE)* PE) | DE | DP)* SE
909 <dd>\bt_c_sb_msg</dd>
912 <dd>\bt_c_se_msg</dd>
915 <dd>\bt_c_ev_msg</dd>
918 <dd>\bt_c_pb_msg</dd>
921 <dd>\bt_c_pe_msg</dd>
924 <dd>\bt_c_disc_ev_msg</dd>
927 <dd>\bt_c_disc_pkt_msg</dd>
930 For a given message iterator, for any message with a \bt_cs, its
931 clock snapshot must be greater than or equal to any clock snapshot
932 of any previous message.
934 For the scope of this rule, the clock snapshot of a \bt_disc_ev_msg
935 or of a \bt_disc_pkt_msg is its beginning default clock snapshot.
937 For a given message iterator, the \bt_p_cs of all the messages of
938 the sequence with a clock snapshot must be correlatable
939 (see \ref api-tir-clock-cls-origin "Clock value vs. clock class origin").
949 @typedef struct bt_message bt_message;
964 Message type enumerators.
966 typedef enum bt_message_type
{
971 BT_MESSAGE_TYPE_STREAM_BEGINNING
= 1 << 0,
977 BT_MESSAGE_TYPE_STREAM_END
= 1 << 1,
983 BT_MESSAGE_TYPE_EVENT
= 1 << 2,
989 BT_MESSAGE_TYPE_PACKET_BEGINNING
= 1 << 3,
995 BT_MESSAGE_TYPE_PACKET_END
= 1 << 4,
1001 BT_MESSAGE_TYPE_DISCARDED_EVENTS
= 1 << 5,
1007 BT_MESSAGE_TYPE_DISCARDED_PACKETS
= 1 << 6,
1013 BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
= 1 << 7,
1018 Returns the type enumerator of the message \bt_p{message}.
1021 Message of which to get the type enumerator
1024 Type enumerator of \bt_p{message}.
1026 @bt_pre_not_null{message}
1028 extern bt_message_type
bt_message_get_type(const bt_message
*message
);
1033 @name Common stream message
1040 bt_message_stream_beginning_borrow_default_clock_snapshot_const()
1042 bt_message_stream_end_borrow_default_clock_snapshot_const().
1044 typedef enum bt_message_stream_clock_snapshot_state
{
1049 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
= 1,
1053 Unknown (no) \bt_cs.
1055 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
= 0,
1056 } bt_message_stream_clock_snapshot_state
;
1061 @name Stream beginning message
1067 Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
1068 \bt_msg_iter \bt_p{self_message_iterator}.
1070 On success, the returned stream beginning message has the following
1078 <td>\ref api-msg-sb-prop-stream "Stream"
1081 <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
1085 @param[in] self_message_iterator
1086 Self message iterator from which to create the stream beginning
1089 Stream of which the message to create indicates the beginning.
1092 New stream beginning message reference, or \c NULL on memory error.
1094 @bt_pre_not_null{self_message_iterator}
1095 @bt_pre_not_null{stream}
1097 @bt_post_success_frozen{stream}
1100 bt_message
*bt_message_stream_beginning_create(
1101 bt_self_message_iterator
*self_message_iterator
,
1102 const bt_stream
*stream
);
1106 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
1108 See the \ref api-msg-sb-prop-stream "stream" property.
1111 Stream beginning message from which to borrow the stream.
1115 \em Borrowed reference of the stream of \bt_p{message}.
1117 The returned pointer remains valid as long as \bt_p{message} exists.
1120 @bt_pre_not_null{message}
1121 @bt_pre_is_sb_msg{message}
1123 @sa bt_message_stream_beginning_borrow_stream_const() —
1124 \c const version of this function.
1126 extern bt_stream
*bt_message_stream_beginning_borrow_stream(
1127 bt_message
*message
);
1131 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
1134 See bt_message_stream_beginning_borrow_stream().
1136 extern const bt_stream
*bt_message_stream_beginning_borrow_stream_const(
1137 const bt_message
*message
);
1141 Sets the value, in clock cycles, of the default \bt_cs of the
1142 \bt_sb_msg \bt_p{message} to \bt_p{value}.
1144 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1147 Stream beginning message of which to set the default clock snapshot
1148 value to \bt_p{value}.
1150 New value (clock cycles) of the default clock snapshot of
1153 @bt_pre_not_null{message}
1154 @bt_pre_hot{message}
1155 @bt_pre_is_sb_msg{message}
1157 The \bt_stream_cls of \bt_p{message} has a
1158 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1160 @sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() —
1161 Borrows the default clock snapshot of a stream beginning message.
1164 void bt_message_stream_beginning_set_default_clock_snapshot(
1165 bt_message
*message
, uint64_t value
);
1169 Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
1171 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1174 Stream beginning message from which to borrow the default clock
1176 @param[out] clock_snapshot
1177 <strong>If this function returns
1178 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1179 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1180 clock snapshot of \bt_p{message}.
1182 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1183 The default clock snapshot of \bt_p{message} is known and returned
1184 as \bt_p{*clock_snapshot}.
1185 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1186 \bt_p{message} has no default clock snapshot: its time is unknown.
1188 @bt_pre_not_null{message}
1189 @bt_pre_is_sb_msg{message}
1191 The \bt_stream_cls of \bt_p{message} has a
1192 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1193 @bt_pre_not_null{clock_snapshot}
1195 @sa bt_message_stream_beginning_set_default_clock_snapshot() —
1196 Sets the default clock snapshot of a stream beginning message.
1198 extern bt_message_stream_clock_snapshot_state
1199 bt_message_stream_beginning_borrow_default_clock_snapshot_const(
1200 const bt_message
*message
,
1201 const bt_clock_snapshot
**clock_snapshot
);
1205 Borrows the default \bt_clock_cls of the \bt_stream_cls
1206 of the \bt_sb_msg \bt_p{message}.
1208 See the stream class's
1209 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1212 This is a helper which is equivalent to
1215 bt_stream_class_borrow_default_clock_class_const(
1216 bt_stream_borrow_class_const(
1217 bt_message_stream_beginning_borrow_stream_const(message)))
1221 Stream beginning message from which to borrow its stream's class's
1222 default clock class.
1225 \em Borrowed reference of the default clock class of
1226 the stream class of \bt_p{message}, or \c NULL if none.
1228 @bt_pre_not_null{message}
1229 @bt_pre_is_sb_msg{message}
1231 extern const bt_clock_class
*
1232 bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
1233 const bt_message
*message
);
1238 @name Stream end message
1244 Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
1245 \bt_msg_iter \bt_p{self_message_iterator}.
1247 On success, the returned stream end message has the following
1255 <td>\ref api-msg-se-prop-stream "Stream"
1258 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1262 @param[in] self_message_iterator
1263 Self message iterator from which to create the stream end
1266 Stream of which the message to create indicates the end.
1269 New stream end message reference, or \c NULL on memory error.
1271 @bt_pre_not_null{self_message_iterator}
1272 @bt_pre_not_null{stream}
1274 @bt_post_success_frozen{stream}
1277 bt_message
*bt_message_stream_end_create(
1278 bt_self_message_iterator
*self_message_iterator
,
1279 const bt_stream
*stream
);
1283 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
1285 See the \ref api-msg-se-prop-stream "stream" property.
1288 Stream end message from which to borrow the stream.
1292 \em Borrowed reference of the stream of \bt_p{message}.
1294 The returned pointer remains valid as long as \bt_p{message} exists.
1297 @bt_pre_not_null{message}
1298 @bt_pre_is_se_msg{message}
1300 @sa bt_message_stream_end_borrow_stream_const() —
1301 \c const version of this function.
1303 extern bt_stream
*bt_message_stream_end_borrow_stream(
1304 bt_message
*message
);
1308 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
1311 See bt_message_stream_end_borrow_stream().
1313 extern const bt_stream
*bt_message_stream_end_borrow_stream_const(
1314 const bt_message
*message
);
1318 Sets the value, in clock cycles, of the default \bt_cs of the
1319 \bt_se_msg \bt_p{message} to \bt_p{value}.
1321 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1324 Stream end message of which to set the default clock snapshot
1325 value to \bt_p{value}.
1327 New value (clock cycles) of the default clock snapshot of
1330 @bt_pre_not_null{message}
1331 @bt_pre_hot{message}
1332 @bt_pre_is_se_msg{message}
1334 The \bt_stream_cls of \bt_p{message} has a
1335 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1337 @sa bt_message_stream_end_borrow_default_clock_snapshot_const() —
1338 Borrows the default clock snapshot of a stream end message.
1341 void bt_message_stream_end_set_default_clock_snapshot(
1342 bt_message
*message
, uint64_t value
);
1346 Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
1348 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1351 Stream end message from which to borrow the default clock
1353 @param[out] clock_snapshot
1354 <strong>If this function returns
1355 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1356 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1357 clock snapshot of \bt_p{message}.
1359 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1360 The default clock snapshot of \bt_p{message} is known and returned
1361 as \bt_p{*clock_snapshot}.
1362 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1363 \bt_p{message} has no default clock snapshot: its time is unknown.
1365 @bt_pre_not_null{message}
1366 @bt_pre_is_se_msg{message}
1368 The \bt_stream_cls of \bt_p{message} has a
1369 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1370 @bt_pre_not_null{clock_snapshot}
1372 @sa bt_message_stream_end_set_default_clock_snapshot() —
1373 Sets the default clock snapshot of a stream end message.
1375 extern bt_message_stream_clock_snapshot_state
1376 bt_message_stream_end_borrow_default_clock_snapshot_const(
1377 const bt_message
*message
,
1378 const bt_clock_snapshot
**clock_snapshot
);
1382 Borrows the default \bt_clock_cls of the \bt_stream_cls
1383 of the \bt_se_msg \bt_p{message}.
1385 See the stream class's
1386 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1389 This is a helper which is equivalent to
1392 bt_stream_class_borrow_default_clock_class_const(
1393 bt_stream_borrow_class_const(
1394 bt_message_stream_end_borrow_stream_const(message)))
1398 Stream end message from which to borrow its stream's class's
1399 default clock class.
1402 \em Borrowed reference of the default clock class of
1403 the stream class of \bt_p{message}, or \c NULL if none.
1405 @bt_pre_not_null{message}
1406 @bt_pre_is_se_msg{message}
1408 extern const bt_clock_class
*
1409 bt_message_stream_end_borrow_stream_class_default_clock_class_const(
1410 const bt_message
*message
);
1421 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1422 \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
1423 \bt_msg_iter \bt_p{self_message_iterator}.
1427 Only use this function if
1430 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1433 returns #BT_FALSE and
1436 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1442 bt_message_event_create_with_default_clock_snapshot(),
1443 bt_message_event_create_with_packet(), or
1444 bt_message_event_create_with_packet_and_default_clock_snapshot().
1447 On success, the returned event message has the following property
1455 <td>\ref api-msg-ev-prop-ev "Event"
1457 An instance (with \bt_p_field that are not set) of
1460 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1464 @param[in] self_message_iterator
1465 Self message iterator from which to create the event message.
1466 @param[in] event_class
1467 Class of the \bt_ev of the message to create.
1469 Stream conceptually containing the event of the message to create.
1472 New event message reference, or \c NULL on memory error.
1474 @bt_pre_not_null{self_message_iterator}
1476 The \bt_stream_cls of \bt_p{event_class} is also the class of
1477 \bt_p{stream}, that is,
1478 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1480 <code>bt_stream_borrow_class_const(stream)</code> have the
1482 @bt_pre_not_null{stream}
1484 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1487 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1490 @bt_post_success_frozen{event_class}
1491 @bt_post_success_frozen{stream}
1494 bt_message
*bt_message_event_create(
1495 bt_self_message_iterator
*self_message_iterator
,
1496 const bt_event_class
*event_class
,
1497 const bt_stream
*stream
);
1501 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1502 \bt_p{event_class} and a default \bt_cs with the value
1503 \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
1504 the \bt_msg_iter \bt_p{self_message_iterator}.
1508 Only use this function if
1511 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1514 returns #BT_FALSE and
1517 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1520 does \em not return \c NULL.
1523 bt_message_event_create(),
1524 bt_message_event_create_with_packet(), or
1525 bt_message_event_create_with_packet_and_default_clock_snapshot().
1528 On success, the returned event message has the following property
1536 <td>\ref api-msg-ev-prop-ev "Event"
1538 An instance (with \bt_p_field that are not set) of
1541 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1542 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1545 @param[in] self_message_iterator
1546 Self message iterator from which to create the event message.
1547 @param[in] event_class
1548 Class of the \bt_ev of the message to create.
1550 Stream conceptually containing the event of the message to create.
1551 @param[in] clock_snapshot_value
1552 Value (clock cycles) of the default clock snapshot of
1556 New event message reference, or \c NULL on memory error.
1558 @bt_pre_not_null{self_message_iterator}
1560 The \bt_stream_cls of \bt_p{event_class} is also the class of
1561 \bt_p{stream}, that is,
1562 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1564 <code>bt_stream_borrow_class_const(stream)</code> have the
1566 @bt_pre_not_null{stream}
1568 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1571 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1572 does \em not return \c NULL.
1574 @bt_post_success_frozen{event_class}
1575 @bt_post_success_frozen{stream}
1578 bt_message
*bt_message_event_create_with_default_clock_snapshot(
1579 bt_self_message_iterator
*self_message_iterator
,
1580 const bt_event_class
*event_class
,
1581 const bt_stream
*stream
, uint64_t clock_snapshot_value
);
1585 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1586 \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
1587 \bt_msg_iter \bt_p{self_message_iterator}.
1591 Only use this function if
1594 bt_stream_class_supports_packets(
1595 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1598 returns #BT_TRUE and
1601 bt_stream_class_borrow_default_clock_class_const(
1602 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1608 bt_message_event_create(),
1609 bt_message_event_create_with_default_clock_snapshot(), or
1610 bt_message_event_create_with_packet_and_default_clock_snapshot().
1613 On success, the returned event message has the following property
1621 <td>\ref api-msg-ev-prop-ev "Event"
1623 An instance (with \bt_p_field that are not set) of
1626 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1630 @param[in] self_message_iterator
1631 Self message iterator from which to create the event message.
1632 @param[in] event_class
1633 Class of the \bt_ev of the message to create.
1635 Packet conceptually containing the event of the message to create.
1638 New event message reference, or \c NULL on memory error.
1640 @bt_pre_not_null{self_message_iterator}
1642 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1643 \bt_p{packet}, that is,
1644 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1646 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1647 have the same value.
1648 @bt_pre_not_null{packet}
1650 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1653 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1656 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1657 any, and all its contained \bt_p_field, recursively, are set.
1659 @bt_post_success_frozen{event_class}
1660 @bt_post_success_frozen{packet}
1663 bt_message
*bt_message_event_create_with_packet(
1664 bt_self_message_iterator
*self_message_iterator
,
1665 const bt_event_class
*event_class
,
1666 const bt_packet
*packet
);
1670 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1671 \bt_p{event_class} and a default \bt_cs with the value
1672 \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
1673 the \bt_msg_iter \bt_p{self_message_iterator}.
1677 Only use this function if
1680 bt_stream_class_supports_packets(
1681 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1684 returns #BT_TRUE and
1687 bt_stream_class_borrow_default_clock_class_const(
1688 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1691 does \em not return \c NULL.
1694 bt_message_event_create(),
1695 bt_message_event_create_with_default_clock_snapshot(), or
1696 bt_message_event_create_with_packet().
1699 On success, the returned event message has the following property
1707 <td>\ref api-msg-ev-prop-ev "Event"
1709 An instance (with \bt_p_field that are not set) of
1712 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1713 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1716 @param[in] self_message_iterator
1717 Self message iterator from which to create the event message.
1718 @param[in] event_class
1719 Class of the \bt_ev of the message to create.
1721 Packet conceptually containing the event of the message to create.
1722 @param[in] clock_snapshot_value
1723 Value (clock cycles) of the default clock snapshot of
1727 New event message reference, or \c NULL on memory error.
1729 @bt_pre_not_null{self_message_iterator}
1731 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1732 \bt_p{packet}, that is,
1733 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1735 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1736 have the same value.
1737 @bt_pre_not_null{packet}
1739 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1742 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1743 does \em not return \c NULL.
1745 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1746 any, and all its contained \bt_p_field, recursively, are set.
1748 @bt_post_success_frozen{event_class}
1749 @bt_post_success_frozen{stream}
1752 bt_message
*bt_message_event_create_with_packet_and_default_clock_snapshot(
1753 bt_self_message_iterator
*self_message_iterator
,
1754 const bt_event_class
*event_class
,
1755 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1759 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
1761 See the \ref api-msg-ev-prop-ev "event" property.
1764 Event message from which to borrow the event.
1768 \em Borrowed reference of the event of \bt_p{message}.
1770 The returned pointer remains valid as long as \bt_p{message} exists.
1773 @bt_pre_not_null{message}
1774 @bt_pre_is_ev_msg{message}
1776 @sa bt_message_event_borrow_event_const() —
1777 \c const version of this function.
1779 extern bt_event
*bt_message_event_borrow_event(
1780 bt_message
*message
);
1784 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
1787 See bt_message_event_borrow_event().
1789 extern const bt_event
*bt_message_event_borrow_event_const(
1790 const bt_message
*message
);
1794 Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
1796 See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
1799 Event message from which to borrow the default clock snapshot.
1802 Default clock snapshot of \bt_p{message}.
1804 @bt_pre_not_null{message}
1805 @bt_pre_is_ev_msg{message}
1807 The \bt_stream_cls of \bt_p{message} has a
1808 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1810 extern const bt_clock_snapshot
*
1811 bt_message_event_borrow_default_clock_snapshot_const(const bt_message
*message
);
1815 Borrows the default \bt_clock_cls of the \bt_stream_cls
1816 of the \bt_ev_msg \bt_p{message}.
1818 See the stream class's
1819 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1822 This is a helper which is equivalent to
1825 bt_stream_class_borrow_default_clock_class_const(
1826 bt_stream_borrow_class_const(
1827 bt_event_borrow_stream_const(
1828 bt_message_event_borrow_event_const(message))))
1832 Event message from which to borrow its stream's class's
1833 default clock class.
1836 \em Borrowed reference of the default clock class of
1837 the stream class of \bt_p{message}, or \c NULL if none.
1839 @bt_pre_not_null{message}
1840 @bt_pre_is_ev_msg{message}
1842 extern const bt_clock_class
*
1843 bt_message_event_borrow_stream_class_default_clock_class_const(
1844 const bt_message
*message
);
1849 @name Packet beginning message
1855 Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
1856 \bt_msg_iter \bt_p{self_message_iterator}.
1860 Only use this function if
1863 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1864 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1870 bt_message_packet_beginning_create_with_default_clock_snapshot().
1873 On success, the returned packet beginning message has the following
1881 <td>\ref api-msg-pb-prop-pkt "Packet"
1884 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1888 @param[in] self_message_iterator
1889 Self message iterator from which to create the packet beginning
1892 Packet of which the message to create indicates the beginning.
1895 New packet beginning message reference, or \c NULL on memory error.
1897 @bt_pre_not_null{self_message_iterator}
1898 @bt_pre_not_null{packet}
1900 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1901 returns #BT_FALSE for
1902 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1904 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1905 any, and all its contained \bt_p_field, recursively, are set.
1907 @bt_post_success_frozen{packet}
1910 bt_message
*bt_message_packet_beginning_create(
1911 bt_self_message_iterator
*self_message_iterator
,
1912 const bt_packet
*packet
);
1916 Creates a \bt_pb_msg having a default \bt_cs with the value
1917 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
1918 \bt_msg_iter \bt_p{self_message_iterator}.
1922 Only use this function if
1925 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1926 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1932 bt_message_packet_beginning_create().
1935 On success, the returned packet beginning message has the following
1943 <td>\ref api-msg-pb-prop-pkt "Packet"
1946 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1947 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1950 @param[in] self_message_iterator
1951 Self message iterator from which to create the packet beginning
1954 Packet of which the message to create indicates the beginning.
1955 @param[in] clock_snapshot_value
1956 Value (clock cycles) of the default clock snapshot of
1960 New packet beginning message reference, or \c NULL on memory error.
1962 @bt_pre_not_null{self_message_iterator}
1963 @bt_pre_not_null{packet}
1965 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1966 returns #BT_TRUE for
1967 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1969 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1970 any, and all its contained \bt_p_field, recursively, are set.
1972 @bt_post_success_frozen{packet}
1975 bt_message
*bt_message_packet_beginning_create_with_default_clock_snapshot(
1976 bt_self_message_iterator
*self_message_iterator
,
1977 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1981 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
1983 See the \ref api-msg-pb-prop-pkt "packet" property.
1986 Packet beginning message from which to borrow the packet.
1990 \em Borrowed reference of the packet of \bt_p{message}.
1992 The returned pointer remains valid as long as \bt_p{message} exists.
1995 @bt_pre_not_null{message}
1996 @bt_pre_is_pb_msg{message}
1998 @sa bt_message_packet_beginning_borrow_packet_const() —
1999 \c const version of this function.
2001 extern bt_packet
*bt_message_packet_beginning_borrow_packet(
2002 bt_message
*message
);
2006 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
2009 See bt_message_packet_beginning_borrow_packet().
2011 extern const bt_packet
*bt_message_packet_beginning_borrow_packet_const(
2012 const bt_message
*message
);
2016 Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
2018 See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
2021 Packet beginning message from which to borrow the default clock
2025 Default clock snapshot of \bt_p{message}.
2027 @bt_pre_not_null{message}
2028 @bt_pre_is_pb_msg{message}
2030 The packets of the \bt_stream_cls of \bt_p{message}
2031 \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
2033 extern const bt_clock_snapshot
*
2034 bt_message_packet_beginning_borrow_default_clock_snapshot_const(
2035 const bt_message
*message
);
2039 Borrows the default \bt_clock_cls of the \bt_stream_cls
2040 of the \bt_pb_msg \bt_p{message}.
2042 See the stream class's
2043 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2046 This is a helper which is equivalent to
2049 bt_stream_class_borrow_default_clock_class_const(
2050 bt_stream_borrow_class_const(
2051 bt_packet_borrow_stream_const(
2052 bt_message_packet_beginning_borrow_packet_const(message))))
2056 Packet beginning message from which to borrow its stream's class's
2057 default clock class.
2060 \em Borrowed reference of the default clock class of
2061 the stream class of \bt_p{message}, or \c NULL if none.
2063 @bt_pre_not_null{message}
2064 @bt_pre_is_pb_msg{message}
2066 extern const bt_clock_class
*
2067 bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
2068 const bt_message
*message
);
2073 @name Packet end message
2079 Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
2080 \bt_msg_iter \bt_p{self_message_iterator}.
2084 Only use this function if
2087 bt_stream_class_packets_have_end_default_clock_snapshot(
2088 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2094 bt_message_packet_end_create_with_default_clock_snapshot().
2097 On success, the returned packet end message has the following
2105 <td>\ref api-msg-pe-prop-pkt "Packet"
2108 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2112 @param[in] self_message_iterator
2113 Self message iterator from which to create the packet end message.
2115 Packet of which the message to create indicates the end.
2118 New packet end message reference, or \c NULL on memory error.
2120 @bt_pre_not_null{self_message_iterator}
2121 @bt_pre_not_null{packet}
2123 bt_stream_class_packets_have_end_default_clock_snapshot()
2124 returns #BT_FALSE for
2125 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2127 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2128 any, and all its contained \bt_p_field, recursively, are set.
2130 @bt_post_success_frozen{packet}
2133 bt_message
*bt_message_packet_end_create(
2134 bt_self_message_iterator
*self_message_iterator
,
2135 const bt_packet
*packet
);
2139 Creates a \bt_pe_msg having a default \bt_cs with the value
2140 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
2141 \bt_msg_iter \bt_p{self_message_iterator}.
2145 Only use this function if
2148 bt_stream_class_packets_have_end_default_clock_snapshot(
2149 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2155 bt_message_packet_end_create().
2158 On success, the returned packet end message has the following
2166 <td>\ref api-msg-pe-prop-pkt "Packet"
2169 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2170 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
2173 @param[in] self_message_iterator
2174 Self message iterator from which to create the packet end
2177 Packet of which the message to create indicates the end.
2178 @param[in] clock_snapshot_value
2179 Value (clock cycles) of the default clock snapshot of
2183 New packet end message reference, or \c NULL on memory error.
2185 @bt_pre_not_null{self_message_iterator}
2186 @bt_pre_not_null{packet}
2188 bt_stream_class_packets_have_end_default_clock_snapshot()
2189 returns #BT_TRUE for
2190 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2192 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2193 any, and all its contained \bt_p_field, recursively, are set.
2195 @bt_post_success_frozen{packet}
2198 bt_message
*bt_message_packet_end_create_with_default_clock_snapshot(
2199 bt_self_message_iterator
*self_message_iterator
,
2200 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
2204 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
2206 See the \ref api-msg-pe-prop-pkt "packet" property.
2209 Packet end message from which to borrow the packet.
2213 \em Borrowed reference of the packet of \bt_p{message}.
2215 The returned pointer remains valid as long as \bt_p{message} exists.
2218 @bt_pre_not_null{message}
2219 @bt_pre_is_pe_msg{message}
2221 @sa bt_message_packet_end_borrow_packet_const() —
2222 \c const version of this function.
2224 extern bt_packet
*bt_message_packet_end_borrow_packet(
2225 bt_message
*message
);
2229 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
2232 See bt_message_packet_end_borrow_packet().
2234 extern const bt_packet
*bt_message_packet_end_borrow_packet_const(
2235 const bt_message
*message
);
2239 Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
2241 See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
2244 Packet end message from which to borrow the default clock
2248 Default clock snapshot of \bt_p{message}.
2250 @bt_pre_not_null{message}
2251 @bt_pre_is_pe_msg{message}
2253 The packets of the \bt_stream_cls of \bt_p{message}
2254 \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
2256 extern const bt_clock_snapshot
*
2257 bt_message_packet_end_borrow_default_clock_snapshot_const(
2258 const bt_message
*message
);
2262 Borrows the default \bt_clock_cls of the \bt_stream_cls
2263 of the \bt_pe_msg \bt_p{message}.
2265 See the stream class's
2266 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2269 This is a helper which is equivalent to
2272 bt_stream_class_borrow_default_clock_class_const(
2273 bt_stream_borrow_class_const(
2274 bt_packet_borrow_stream_const(
2275 bt_message_packet_end_borrow_packet_const(message))))
2279 Packet end message from which to borrow its stream's class's
2280 default clock class.
2283 \em Borrowed reference of the default clock class of
2284 the stream class of \bt_p{message}, or \c NULL if none.
2286 @bt_pre_not_null{message}
2287 @bt_pre_is_pe_msg{message}
2289 extern const bt_clock_class
*
2290 bt_message_packet_end_borrow_stream_class_default_clock_class_const(
2291 const bt_message
*message
);
2296 @name Discarded events message
2302 Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
2303 \bt_msg_iter \bt_p{self_message_iterator}.
2307 Only use this function if
2310 bt_stream_class_discarded_events_have_default_clock_snapshots(
2311 bt_stream_borrow_class_const(stream))
2317 bt_message_discarded_events_create_with_default_clock_snapshots().
2320 On success, the returned discarded events message has the following
2328 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2331 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2334 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2337 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2341 @param[in] self_message_iterator
2342 Self message iterator from which to create the discarded events
2345 Stream from which the events were discarded.
2348 New discarded events message reference, or \c NULL on memory error.
2350 @bt_pre_not_null{self_message_iterator}
2351 @bt_pre_not_null{stream}
2353 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2356 @bt_post_success_frozen{stream}
2358 extern bt_message
*bt_message_discarded_events_create(
2359 bt_self_message_iterator
*self_message_iterator
,
2360 const bt_stream
*stream
);
2364 Creates a \bt_disc_ev_msg having the beginning and end default
2365 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2366 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2367 from the \bt_msg_iter \bt_p{self_message_iterator}.
2371 Only use this function if
2374 bt_stream_class_discarded_events_have_default_clock_snapshots(
2375 bt_stream_borrow_class_const(stream))
2381 bt_message_discarded_events_create().
2384 On success, the returned discarded events message has the following
2392 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2395 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2396 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2398 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2399 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2401 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2405 @param[in] self_message_iterator
2406 Self message iterator from which to create the discarded events
2409 Stream from which the events were discarded.
2410 @param[in] beginning_clock_snapshot_value
2411 Value (clock cycles) of the beginning default clock snapshot of
2413 @param[in] end_clock_snapshot_value
2414 Value (clock cycles) of the end default clock snapshot of
2418 New discarded events message reference, or \c NULL on memory error.
2420 @bt_pre_not_null{self_message_iterator}
2421 @bt_pre_not_null{stream}
2423 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2425 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2427 @bt_post_success_frozen{stream}
2429 extern bt_message
*bt_message_discarded_events_create_with_default_clock_snapshots(
2430 bt_self_message_iterator
*self_message_iterator
,
2431 const bt_stream
*stream
,
2432 uint64_t beginning_clock_snapshot_value
,
2433 uint64_t end_clock_snapshot_value
);
2437 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2439 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2442 Discarded events message from which to borrow the stream.
2446 \em Borrowed reference of the stream of \bt_p{message}.
2448 The returned pointer remains valid as long as \bt_p{message} exists.
2451 @bt_pre_not_null{message}
2452 @bt_pre_is_disc_ev_msg{message}
2454 @sa bt_message_discarded_events_borrow_stream_const() —
2455 \c const version of this function.
2457 extern bt_stream
*bt_message_discarded_events_borrow_stream(
2458 bt_message
*message
);
2462 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2465 See bt_message_discarded_events_borrow_stream().
2467 extern const bt_stream
*
2468 bt_message_discarded_events_borrow_stream_const(const bt_message
*message
);
2472 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2476 \ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2480 Discarded events message from which to borrow the beginning default
2484 Beginning default clock snapshot of \bt_p{message}.
2486 @bt_pre_not_null{message}
2487 @bt_pre_is_disc_ev_msg{message}
2489 The discarded packets messages of the \bt_stream_cls of
2491 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2493 extern const bt_clock_snapshot
*
2494 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
2495 const bt_message
*message
);
2499 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2503 \ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2507 Discarded events message from which to borrow the end default clock
2511 End default clock snapshot of \bt_p{message}.
2513 @bt_pre_not_null{message}
2514 @bt_pre_is_disc_ev_msg{message}
2516 The discarded packets messages of the \bt_stream_cls of
2518 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2520 extern const bt_clock_snapshot
*
2521 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
2522 const bt_message
*message
);
2526 Borrows the default \bt_clock_cls of the \bt_stream_cls
2527 of the \bt_disc_ev_msg \bt_p{message}.
2529 See the stream class's
2530 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2533 This is a helper which is equivalent to
2536 bt_stream_class_borrow_default_clock_class_const(
2537 bt_stream_borrow_class_const(
2538 bt_message_discarded_events_borrow_stream_const(message)))
2542 Discarded events message from which to borrow its stream's class's
2543 default clock class.
2546 \em Borrowed reference of the default clock class of
2547 the stream class of \bt_p{message}, or \c NULL if none.
2549 @bt_pre_not_null{message}
2550 @bt_pre_is_disc_ev_msg{message}
2552 extern const bt_clock_class
*
2553 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
2554 const bt_message
*message
);
2558 Sets the number of discarded events of the \bt_disc_ev_msg
2559 \bt_p{message} to \bt_p{count}.
2561 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2565 Discarded events message of which to set the number of discarded
2566 events to \bt_p{count}.
2568 New number of discarded events of \bt_p{message}.
2570 @bt_pre_not_null{message}
2571 @bt_pre_hot{message}
2572 @bt_pre_is_disc_ev_msg{message}
2576 @sa bt_message_discarded_events_get_count() —
2577 Returns the number of discarded events of a discarded events
2580 extern void bt_message_discarded_events_set_count(bt_message
*message
,
2585 Returns the number of discarded events of the \bt_disc_ev_msg
2588 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2592 Discarded events message of which to get the number of discarded
2595 <strong>If this function returns
2596 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2597 the number of discarded events of \bt_p{message}.
2599 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2600 The number of discarded events of \bt_p{message} is available.
2601 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2602 The number of discarded events of \bt_p{message} is not available.
2604 @bt_pre_not_null{message}
2605 @bt_pre_is_disc_ev_msg{message}
2606 @bt_pre_not_null{count}
2608 @sa bt_message_discarded_events_set_count() —
2609 Sets the number of discarded events of a discarded events message.
2611 extern bt_property_availability
bt_message_discarded_events_get_count(
2612 const bt_message
*message
, uint64_t *count
);
2617 @name Discarded packets message
2623 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2624 \bt_msg_iter \bt_p{self_message_iterator}.
2628 Only use this function if
2631 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2632 bt_stream_borrow_class_const(stream))
2638 bt_message_discarded_packets_create_with_default_clock_snapshots().
2641 On success, the returned discarded packets message has the following
2649 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2652 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2655 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2658 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2662 @param[in] self_message_iterator
2663 Self message iterator from which to create the discarded packets
2666 Stream from which the packets were discarded.
2669 New discarded packets message reference, or \c NULL on memory error.
2671 @bt_pre_not_null{self_message_iterator}
2672 @bt_pre_not_null{stream}
2674 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2677 @bt_post_success_frozen{stream}
2679 extern bt_message
*bt_message_discarded_packets_create(
2680 bt_self_message_iterator
*self_message_iterator
,
2681 const bt_stream
*stream
);
2685 Creates a \bt_disc_pkt_msg having the beginning and end default
2686 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2687 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2688 from the \bt_msg_iter \bt_p{self_message_iterator}.
2692 Only use this function if
2695 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2696 bt_stream_borrow_class_const(stream))
2702 bt_message_discarded_packets_create().
2705 On success, the returned discarded packets message has the following
2713 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2716 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2717 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2719 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2720 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2722 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2726 @param[in] self_message_iterator
2727 Self message iterator from which to create the discarded packets
2730 Stream from which the packets were discarded.
2731 @param[in] beginning_clock_snapshot_value
2732 Value (clock cycles) of the beginning default clock snapshot of
2734 @param[in] end_clock_snapshot_value
2735 Value (clock cycles) of the end default clock snapshot of
2739 New discarded packets message reference, or \c NULL on memory error.
2741 @bt_pre_not_null{self_message_iterator}
2742 @bt_pre_not_null{stream}
2744 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2746 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
2748 @bt_post_success_frozen{stream}
2750 extern bt_message
*bt_message_discarded_packets_create_with_default_clock_snapshots(
2751 bt_self_message_iterator
*self_message_iterator
,
2752 const bt_stream
*stream
, uint64_t beginning_clock_snapshot_value
,
2753 uint64_t end_clock_snapshot_value
);
2757 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2759 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2762 Discarded packets message from which to borrow the stream.
2766 \em Borrowed reference of the stream of \bt_p{message}.
2768 The returned pointer remains valid as long as \bt_p{message} exists.
2771 @bt_pre_not_null{message}
2772 @bt_pre_is_disc_pkt_msg{message}
2774 @sa bt_message_discarded_packets_borrow_stream_const() —
2775 \c const version of this function.
2777 extern bt_stream
*bt_message_discarded_packets_borrow_stream(
2778 bt_message
*message
);
2782 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2785 See bt_message_discarded_packets_borrow_stream().
2787 extern const bt_stream
*
2788 bt_message_discarded_packets_borrow_stream_const(const bt_message
*message
);
2792 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2796 \ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2800 Discarded packets message from which to borrow the beginning default
2804 Beginning default clock snapshot of \bt_p{message}.
2806 @bt_pre_not_null{message}
2807 @bt_pre_is_disc_pkt_msg{message}
2809 The discarded packets messages of the \bt_stream_cls of
2811 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2813 extern const bt_clock_snapshot
*
2814 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
2815 const bt_message
*message
);
2819 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2823 \ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2827 Discarded packets message from which to borrow the end default clock
2831 End default clock snapshot of \bt_p{message}.
2833 @bt_pre_not_null{message}
2834 @bt_pre_is_disc_pkt_msg{message}
2836 The discarded packets messages of the \bt_stream_cls of
2838 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2840 extern const bt_clock_snapshot
*
2841 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
2842 const bt_message
*message
);
2846 Borrows the default \bt_clock_cls of the \bt_stream_cls
2847 of the \bt_disc_pkt_msg \bt_p{message}.
2849 See the stream class's
2850 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2853 This is a helper which is equivalent to
2856 bt_stream_class_borrow_default_clock_class_const(
2857 bt_stream_borrow_class_const(
2858 bt_message_discarded_packets_borrow_stream_const(message)))
2862 Discarded packets message from which to borrow its stream's class's
2863 default clock class.
2866 \em Borrowed reference of the default clock class of
2867 the stream class of \bt_p{message}, or \c NULL if none.
2869 @bt_pre_not_null{message}
2870 @bt_pre_is_disc_pkt_msg{message}
2872 extern const bt_clock_class
*
2873 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
2874 const bt_message
*message
);
2878 Sets the number of discarded packets of the \bt_disc_pkt_msg
2879 \bt_p{message} to \bt_p{count}.
2881 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2885 Discarded packets message of which to set the number of discarded
2886 packets to \bt_p{count}.
2888 New number of discarded packets of \bt_p{message}.
2890 @bt_pre_not_null{message}
2891 @bt_pre_hot{message}
2892 @bt_pre_is_disc_pkt_msg{message}
2896 @sa bt_message_discarded_packets_get_count() —
2897 Returns the number of discarded packets of a discarded packets
2900 extern void bt_message_discarded_packets_set_count(bt_message
*message
,
2905 Returns the number of discarded packets of the \bt_disc_pkt_msg
2908 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2912 Discarded packets message of which to get the number of discarded
2915 <strong>If this function returns
2916 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2917 the number of discarded packets of \bt_p{message}.
2919 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2920 The number of discarded packets of \bt_p{message} is available.
2921 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2922 The number of discarded packets of \bt_p{message} is not available.
2924 @bt_pre_not_null{message}
2925 @bt_pre_is_disc_pkt_msg{message}
2926 @bt_pre_not_null{count}
2928 @sa bt_message_discarded_packets_set_count() —
2929 Sets the number of discarded packets of a discarded packets message.
2931 extern bt_property_availability
bt_message_discarded_packets_get_count(
2932 const bt_message
*message
, uint64_t *count
);
2937 @name Message iterator inactivity message
2943 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2944 the \bt_clock_cls \bt_p{clock_class} with the value
2945 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2946 \bt_p{self_message_iterator}.
2948 On success, the returned message iterator inactivity message has the
2949 following property values:
2956 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2958 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2959 with the value \bt_p{clock_snapshot_value}.
2962 @param[in] self_message_iterator
2963 Self message iterator from which to create the message iterator
2965 @param[in] clock_class
2966 Class of the fictitious instance of which
2967 \bt_p{clock_snapshot_value} is the value of its snapshot.
2968 @param[in] clock_snapshot_value
2969 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2972 New message iterator inactivity message reference, or \c NULL on
2975 @bt_pre_not_null{self_message_iterator}
2976 @bt_pre_not_null{clock_class}
2978 @bt_post_success_frozen{clock_class}
2981 bt_message
*bt_message_message_iterator_inactivity_create(
2982 bt_self_message_iterator
*self_message_iterator
,
2983 const bt_clock_class
*clock_class
,
2984 uint64_t clock_snapshot_value
);
2988 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2990 See the \ref api-msg-inac-prop-cs "clock snapshot" property.
2993 Message iterator inactivity message from which to borrow the clock
2997 Clock snapshot of \bt_p{message}.
2999 @bt_pre_not_null{message}
3000 @bt_pre_is_inac_msg{message}
3002 extern const bt_clock_snapshot
*
3003 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
3004 const bt_message
*message
);
3009 @name Message reference count
3015 Increments the \ref api-fund-shared-object "reference count" of
3016 the message \bt_p{message}.
3020 Message of which to increment the reference count.
3025 @sa bt_message_put_ref() —
3026 Decrements the reference count of a message.
3028 extern void bt_message_get_ref(const bt_message
*message
);
3032 Decrements the \ref api-fund-shared-object "reference count" of
3033 the message \bt_p{message}.
3037 Message of which to decrement the reference count.
3042 @sa bt_message_get_ref() —
3043 Increments the reference count of a message.
3045 extern void bt_message_put_ref(const bt_message
*message
);
3049 Decrements the reference count of the message \bt_p{_message}, and
3050 then sets \bt_p{_message} to \c NULL.
3054 Message of which to decrement the reference count.
3056 Can contain \c NULL.
3059 @bt_pre_assign_expr{_message}
3061 #define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3063 bt_message_put_ref(_message); \
3064 (_message) = NULL; \
3069 Decrements the reference count of the message \bt_p{_dst}, sets
3070 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3072 This macro effectively moves a message reference from the expression
3073 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3074 \bt_p{_dst} reference.
3078 Destination expression.
3080 Can contain \c NULL.
3086 Can contain \c NULL.
3089 @bt_pre_assign_expr{_dst}
3090 @bt_pre_assign_expr{_src}
3092 #define BT_MESSAGE_MOVE_REF(_dst, _src) \
3094 bt_message_put_ref(_dst); \
3102 @name Message Interchange Protocol version
3108 Status codes for bt_get_greatest_operative_mip_version().
3110 typedef enum bt_get_greatest_operative_mip_version_status
{
3115 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3121 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
= __BT_FUNC_STATUS_NO_MATCH
,
3127 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3133 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
3134 } bt_get_greatest_operative_mip_version_status
;
3138 Computes the greatest \bt_mip version which
3139 you can use to create a trace processing \bt_graph to which you
3140 intend to \ref api-graph-lc-add "add components" described by the
3141 component descriptors \bt_p{component_descriptors}, and sets
3142 \bt_p{*mip_version} to the result.
3144 This function calls the
3145 \link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3146 method for each component descriptor in \bt_p{component_descriptors},
3147 and then returns the greatest common (operative) MIP version, if any.
3148 The "get supported MIP versions" method receives \bt_p{logging_level} as
3149 its \bt_p{logging_level} parameter.
3151 If this function does not find an operative MIP version for the
3152 component descriptors of \bt_p{component_descriptors}, it returns
3153 #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3156 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
3157 returns 0, this function always sets \bt_p{*mip_version} to
3160 @param[in] component_descriptors
3161 Component descriptors for which to get the supported MIP versions
3162 to compute the greatest operative MIP version.
3163 @param[in] logging_level
3164 Logging level to use when calling the "get supported MIP versions"
3165 method for each component descriptor in
3166 \bt_p{component_descriptors}.
3167 @param[out] mip_version
3168 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3169 operative MIP version of all the component descriptors in
3170 \bt_p{component_descriptors}.
3172 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3174 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3175 No operative MIP version exists for the component descriptors of
3176 \bt_p{component_descriptors}.
3177 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3179 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3182 @bt_pre_not_null{component_descriptors}
3184 \bt_p{component_descriptors} contains one or more component
3186 @bt_pre_not_null{mip_version}
3188 extern bt_get_greatest_operative_mip_version_status
3189 bt_get_greatest_operative_mip_version(
3190 const bt_component_descriptor_set
*component_descriptors
,
3191 bt_logging_level logging_level
, uint64_t *mip_version
);
3195 Returns the maximal available \bt_mip version as of
3196 \bt_name_version_min_maj.
3198 As of \bt_name_version_min_maj, this function returns
3199 \bt_max_mip_version.
3202 Maximal available MIP version (\bt_max_mip_version).
3204 extern uint64_t bt_get_maximal_mip_version(void);
3214 #endif /* BABELTRACE2_GRAPH_MESSAGE_H */