1 #ifndef BABELTRACE2_GRAPH_MESSAGE_H
2 #define BABELTRACE2_GRAPH_MESSAGE_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
37 @defgroup api-msg Messages
38 @ingroup api-comp-cls-dev
41 Elements exchanged between \bt_p_comp.
43 <strong><em>Messages</em></strong> are the objects which are exchanged
44 between \bt_p_comp in a trace processing \bt_graph to accomplish a
47 \bt_cp_msg_iter create messages while message iterators \em and
48 \bt_p_sink_comp consume messages.
50 There are eight types of messages:
61 The type of a message is #bt_message.
63 Get the type enumerator of a message with bt_message_get_type().
65 A message is a \ref api-fund-shared-object "shared object": get a
66 new reference with bt_message_get_ref() and put an existing
67 reference with bt_message_put_ref().
69 Some library functions \ref api-fund-freezing "freeze" messages on
70 success. The documentation of those functions indicate this
73 Messages transport objects of the \ref api-tir API, which is an
74 intermediate representation of the tracing domain concepts.
76 All types of messages, except the \bt_inac_msg type, are related to a
77 specific <em>\bt_stream</em>, which represents a conceptual
78 \ref api-msg-seq "sequence of messages".
80 Some types of messages can have a default \bt_cs, depending on whether
81 or not their stream has a conceptual default clock, that is, whether or
82 not the stream's \ref api-tir-stream-cls "class" has a
83 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
84 The creation functions for those types of messages contain
85 <code>_with_default_clock_snapshot</code> (for example,
86 bt_message_event_create_with_default_clock_snapshot()).
88 For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
89 is optional, therefore they have dedicated
90 bt_message_stream_beginning_set_default_clock_snapshot() and
91 bt_message_stream_end_set_default_clock_snapshot() functions.
93 All the message creation functions take a \bt_self_msg_iter as their
94 first parameter. This is because a message iterator method is the only
95 valid context to create a message.
97 <h1>Message types</h1>
99 This section details each type of message.
101 The following table shows the creation functions and types for each type
108 <th>Creation functions
110 <td>\ref api-msg-sb "Stream beginning"
111 <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
112 <td>bt_message_stream_beginning_create()
114 <td>\ref api-msg-se "Stream end"
115 <td>#BT_MESSAGE_TYPE_STREAM_END
116 <td>bt_message_stream_end_create()
118 <td>\ref api-msg-ev "Event"
119 <td>#BT_MESSAGE_TYPE_EVENT
121 bt_message_event_create()<br>
122 bt_message_event_create_with_default_clock_snapshot()<br>
123 bt_message_event_create_with_packet()<br>
124 bt_message_event_create_with_packet_and_default_clock_snapshot()
126 <td>\ref api-msg-pb "Packet beginning"
127 <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
129 bt_message_packet_beginning_create()<br>
130 bt_message_packet_beginning_create_with_default_clock_snapshot()
132 <td>\ref api-msg-pe "Packet end"
133 <td>#BT_MESSAGE_TYPE_PACKET_END
135 bt_message_packet_end_create()<br>
136 bt_message_packet_end_create_with_default_clock_snapshot()
138 <td>\ref api-msg-disc-ev "Discarded events"
139 <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
141 bt_message_discarded_events_create()<br>
142 bt_message_discarded_events_create_with_default_clock_snapshots()
144 <td>\ref api-msg-disc-pkt "Discarded packets"
145 <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
147 bt_message_discarded_packets_create()<br>
148 bt_message_discarded_packets_create_with_default_clock_snapshots()
150 <td>\ref api-msg-inac "Message iterator inactivity"
151 <td>#BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
152 <td>bt_message_message_iterator_inactivity_create()
155 <h2>\anchor api-msg-sb Stream beginning message</h2>
157 A <strong><em>stream beginning message</em></strong> indicates the
158 beginning of a \bt_stream.
162 - A stream beginning message is always the first one in the
163 \ref api-msg-seq "message sequence".
165 - There can be only one stream beginning message.
167 Create a stream beginning message with
168 bt_message_stream_beginning_create().
170 A stream beginning message has the following properties:
173 <dt>\anchor api-msg-sb-prop-stream Stream</dt>
175 \bt_c_stream of which the message indicates the beginning.
177 You cannot change the stream once the message is created.
179 Borrow a stream beginning message's stream with
180 bt_message_stream_beginning_borrow_stream() and
181 bt_message_stream_beginning_borrow_stream_const().
185 \anchor api-msg-sb-prop-cs
186 \bt_dt_opt Default \bt_cs
189 Snapshot of the message's \bt_stream's default clock when the
192 A stream beginning message can only have a default clock snapshot
193 if its stream's \ref api-tir-stream-cls "class" has a
194 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
196 When a stream beginning message has no default clock snapshot,
197 then its time is <em>unknown</em>.
199 Set a stream beginning message's default clock snapshot with
200 bt_message_stream_beginning_set_default_clock_snapshot().
202 Borrow a stream beginning message's default clock snapshot with
203 bt_message_stream_beginning_borrow_default_clock_snapshot_const().
207 <h2>\anchor api-msg-se Stream end message</h2>
209 A <strong><em>stream end message</em></strong> indicates the
214 - A stream end message is always the last one in the
215 \ref api-msg-seq "message sequence".
217 - There can be only one stream end message.
219 Create a stream end message with bt_message_stream_end_create().
221 A stream end message has the following properties:
224 <dt>\anchor api-msg-se-prop-stream Stream</dt>
226 \bt_c_stream of which the message indicates the end.
228 You cannot change the stream once the message is created.
230 Borrow a stream end message's stream with
231 bt_message_stream_end_borrow_stream() and
232 bt_message_stream_end_borrow_stream_const().
236 \anchor api-msg-se-prop-cs
237 \bt_dt_opt Default \bt_cs
240 Snapshot of the message's \bt_stream's default clock when the
243 A stream end message can only have a default clock snapshot
244 if its stream's \ref api-tir-stream-cls "class" has a
245 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
247 When a stream end message has no default clock snapshot, then its
248 time is <em>unknown</em>.
250 Set a stream end message's default clock snapshot with
251 bt_message_stream_end_set_default_clock_snapshot().
253 Borrow a stream end message's default clock snapshot with
254 bt_message_stream_end_borrow_default_clock_snapshot_const().
258 <h2>\anchor api-msg-ev Event message</h2>
260 An <strong><em>event message</em></strong> transports an \bt_ev and has,
261 possibly, a default \bt_cs.
263 Within its \bt_stream's \ref api-msg-seq "message sequence", an event
264 message can only occur:
268 If the stream's \ref api-tir-stream-cls "class"
269 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
271 <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
274 If the stream's class does not support packets
276 <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
279 To create an event message for a given stream, use:
283 If the stream's \ref api-tir-stream-cls "class"
284 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
289 If the stream's class has a
290 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
292 <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
295 If the stream's class does not have a
296 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
298 <dd>bt_message_event_create_with_packet()</dd>
301 Those two creation functions accept a \bt_pkt parameter which is
302 the packet logically containing the message's event. A packet is
307 If the stream's class does not supports packets
312 If the stream's class has a default clock class
314 <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
317 If the stream's class does not have a
318 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
320 <dd>bt_message_event_create()</dd>
325 The four creation functions above accept an \bt_ev_cls parameter. When
326 you create the message, the library instantiates this event class as an
327 \bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
328 This event class must be part of the class of the event message's
331 An event message's event is initially <em>not set</em>: before you emit
332 the event message from a \bt_msg_iter's
333 \link api-msg-iter-cls-meth-next "next" method\endlink, you need to
334 borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
335 bt_event_borrow_specific_context_field(), and
336 bt_event_borrow_common_context_field()) and, recursively, set the values
337 of the all their inner fields.
339 An event message has the following properties:
342 <dt>\anchor api-msg-ev-prop-ev Event</dt>
344 \bt_c_ev which the message transports.
346 This is an instance of the \bt_ev_cls which was passed to the
347 message's creation function.
349 With this event, you can access its \bt_pkt (if any) with
350 bt_event_borrow_packet_const() and its
351 \bt_stream with bt_event_borrow_stream_const().
353 Borrow an event message's event with bt_message_event_borrow_event()
354 and bt_message_event_borrow_event_const().
358 \anchor api-msg-ev-prop-cs
359 \bt_dt_opt Default \bt_cs
362 Snapshot of the message's \bt_stream's default clock when the
365 An event message has a default clock snapshot
366 if its stream's \ref api-tir-stream-cls "class" has a
367 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class",
368 and has none otherwise.
370 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
371 the default clock snapshot of an event message must be greater than
372 or equal to any default clock snapshot of any previous message.
374 Borrow an event message's default clock snapshot with
375 bt_message_event_borrow_default_clock_snapshot_const().
379 <h2>\anchor api-msg-pb Packet beginning message</h2>
381 A <strong><em>packet beginning message</em></strong> indicates the
382 beginning of a \bt_pkt.
384 A packet beginning message can only exist if its \bt_stream's
385 \ref api-tir-stream-cls "class"
386 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
388 For a given packet, there can be only one packet beginning message.
390 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
391 beginning message can only occur after the \bt_sb_msg and before the
394 To create a packet beginning message for a given stream, use:
398 If, for this stream's class,
399 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
401 <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
404 If, for this stream's class, packets do not have a beginning default
407 <dd>bt_message_packet_beginning_create()</dd>
410 A packet beginning message has the following properties:
413 <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
415 \bt_c_pkt of which the message indicates the beginning.
417 You cannot change the packet once the message is created.
419 Borrow a packet beginning message's packet with
420 bt_message_packet_beginning_borrow_packet() and
421 bt_message_packet_beginning_borrow_packet_const().
425 \anchor api-msg-pb-prop-cs
426 \bt_dt_opt Default \bt_cs
429 Snapshot of the message's \bt_stream's default clock when the
432 A packet beginning message has a default clock snapshot if:
434 - Its stream's \ref api-tir-stream-cls "class" has a
435 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
437 - For its stream's class,
438 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
440 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
441 the default clock snapshot of a packet beginning message must be
442 greater than or equal to any clock snapshot of any previous message.
444 Borrow a packet beginning message's default clock snapshot with
445 bt_message_packet_beginning_borrow_default_clock_snapshot_const().
449 <h2>\anchor api-msg-pe Packet end message</h2>
451 A <strong><em>packet end message</em></strong> indicates the
454 A packet end message can only exist if its \bt_stream's
455 \ref api-tir-stream-cls "class"
456 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
458 For a given packet, there can be only one packet end message.
460 Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
461 end message can only occur:
463 - After the \bt_sb_msg and before the \bt_se_msg.
464 - After a \bt_pb_msg for the same packet.
466 To create a packet end message for a given stream, use:
470 If, for this stream's class,
471 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
473 <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
476 If, for this stream's class, packets do not have an end default
479 <dd>bt_message_packet_end_create()</dd>
482 A packet end message has the following properties:
485 <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
487 \bt_c_pkt of which the message indicates the end.
489 You cannot change the packet once the message is created.
491 Borrow a packet end message's packet with
492 bt_message_packet_end_borrow_packet() and
493 bt_message_packet_end_borrow_packet_const().
497 \anchor api-msg-pe-prop-cs
498 \bt_dt_opt Default \bt_cs
501 Snapshot of the message's \bt_stream's default clock when the
504 A packet end message has a default clock snapshot if:
506 - Its stream's \ref api-tir-stream-cls "class" has a
507 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
509 - For its stream's class,
510 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
512 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
513 the default clock snapshot of a packet end message must be greater
514 than or equal to any clock snapshot of any previous message.
516 Borrow a packet end message's default clock snapshot with
517 bt_message_packet_end_borrow_default_clock_snapshot_const().
521 <h2>\anchor api-msg-disc-ev Discarded events message</h2>
523 A <strong><em>discarded events message</em></strong> indicates that
524 events were discarded at <em>tracing time</em>. It does \em not indicate
525 that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
527 A discarded events message can only exist if its \bt_stream's
528 \ref api-tir-stream-cls "class"
529 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events".
531 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
532 events message can only occur after the \bt_sb_msg and before the
535 To create a discarded events message for a given stream, use:
539 If, for this stream's class,
540 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
542 <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
545 If, for this stream's class, discarded events do not have default
548 <dd>bt_message_discarded_events_create()</dd>
551 A discarded events message has the following properties:
554 <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
556 \bt_c_stream into which events were discarded.
558 You cannot change the stream once the message is created.
560 Borrow a discarded events message's stream with
561 bt_message_discarded_events_borrow_stream() and
562 bt_message_discarded_events_borrow_stream_const().
566 \anchor api-msg-disc-ev-prop-cs-beg
567 \bt_dt_opt Beginning default \bt_cs
570 Snapshot of the message's \bt_stream's default clock which indicates
571 the beginning of the discarded events time range.
573 A discarded events message has a beginning default clock snapshot
576 - Its stream's \ref api-tir-stream-cls "class" has a
577 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
579 - For its stream's class,
580 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
582 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
583 the beginning default clock snapshot of a discarded events message
584 must be greater than or equal to any clock snapshot of any previous
587 Borrow a discarded events message's beginning default clock snapshot
589 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
593 \anchor api-msg-disc-ev-prop-cs-end
594 \bt_dt_opt End default \bt_cs
597 Snapshot of the message's \bt_stream's default clock which indicates
598 the end of the discarded events time range.
600 A discarded events message has an end default clock snapshot if:
602 - Its stream's \ref api-tir-stream-cls "class" has a
603 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
605 - For its stream's class,
606 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
608 If a discarded events message has both a
609 \ref api-msg-disc-ev-prop-cs-beg "beginning" and an end default
610 clock snapshots, the end default clock snapshot must be greater than
611 or equal to the beginning default clock snapshot.
613 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
614 the end default clock snapshot of a discarded events message must be
615 greater than or equal to any clock snapshot of any previous message.
617 Borrow a discarded events message's end default clock snapshot with
618 bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
622 \anchor api-msg-disc-ev-prop-count
623 \bt_dt_opt Discarded event count
626 Exact number of discarded events.
628 If this property is missing, then the number of discarded events
631 Use bt_message_discarded_events_set_count() and
632 bt_message_discarded_events_get_count().
636 <h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
638 A <strong><em>discarded packets message</em></strong> indicates that
639 packets were discarded at <em>tracing time</em>. It does \em not
640 indicate that whole packets were dropped during a trace processing
643 A discarded packets message can only exist if its \bt_stream's
644 \ref api-tir-stream-cls "class"
645 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets".
647 Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
648 packets message can only occur:
650 - After the \bt_sb_msg.
651 - Before the \bt_se_msg.
653 - Before any \bt_pb_msg.
654 - After any \bt_pe_msg.
655 - Between a packet end and a packet beginning message.
657 To create a discarded packets message for a given stream, use:
661 If, for this stream's class,
662 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
664 <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
667 If, for this stream's class, discarded packets do not have default
670 <dd>bt_message_discarded_packets_create()</dd>
673 A discarded packets message has the following properties:
676 <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
678 \bt_c_stream into which packets were discarded.
680 You cannot change the stream once the message is created.
682 Borrow a discarded packets message's stream with
683 bt_message_discarded_packets_borrow_stream() and
684 bt_message_discarded_packets_borrow_stream_const().
688 \anchor api-msg-disc-pkt-prop-cs-beg
689 \bt_dt_opt Beginning default \bt_cs
692 Snapshot of the message's \bt_stream's default clock which indicates
693 the beginning of the discarded packets time range.
695 A discarded packets message has a beginning default clock snapshot
698 - Its stream's \ref api-tir-stream-cls "class" has a
699 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
701 - For its stream's class,
702 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
704 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
705 the beginning default clock snapshot of a discarded packets message
706 must be greater than or equal to any clock snapshot of any previous
709 Borrow a discarded packets message's beginning default clock snapshot
711 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
715 \anchor api-msg-disc-pkt-prop-cs-end
716 \bt_dt_opt End default \bt_cs
719 Snapshot of the message's \bt_stream's default clock which indicates
720 the end of the discarded packets time range.
722 A discarded packets message has an end default clock snapshot if:
724 - Its stream's \ref api-tir-stream-cls "class" has a
725 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
727 - For its stream's class,
728 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
730 If a discarded packets message has both a
731 \ref api-msg-disc-pkt-prop-cs-beg "beginning" and an end default
732 clock snapshots, the end default clock snapshot must be greater than
733 or equal to the beginning default clock snapshot.
735 Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
736 the end default clock snapshot of a discarded packets message must
737 be greater than or equal to any clock snapshot of any previous
740 Borrow a discarded packets message's end default clock snapshot with
741 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
745 \anchor api-msg-disc-pkt-prop-count
746 \bt_dt_opt Discarded packet count
749 Exact number of discarded packets.
751 If this property is missing, then the number of discarded packets
754 Use bt_message_discarded_packets_set_count() and
755 bt_message_discarded_packets_get_count().
759 <h2>\anchor api-msg-inac Message iterator inactivity</h2>
761 A <strong><em>message iterator inactivity message</em></strong>
762 indicates that, within the \ref api-msg-seq "message sequence" of a
763 given \bt_msg_iter, there's no messages since the last message (if any)
764 until a given point in time.
766 A message iterator inactivity message is the only type of message that's
767 not related to a \bt_stream: it targets the whole message sequence of a
768 message iterator, and can occur at any position within the sequence.
770 This message is mostly significant for real-time message iterators: if a
771 message iterator A indicates that there's no messages until a given
772 point in time T, then a downstream filter message iterator B which
773 relies on multiple upstream message iterators does not have to wait for
774 new messages from A until T.
776 In other words, a message iterator inactivity message can help
777 downstream message iterators or \bt_p_sink_comp <em>progress</em>.
779 Create a message iterator inactivity message with
780 bt_message_message_iterator_inactivity_create(). You must pass a
781 \bt_clock_cls and the value of a fictitious (clock) instance to this
782 function so that it creates a \bt_cs.
784 A message iterator inactivity message has the following property:
788 \anchor api-msg-inac-prop-cs
792 Snapshot of a fictitious instance of the message's \bt_clock_cls
793 which indicates the point in time until when there's no messages
794 in the message iterator's \ref api-msg-seq "message sequence".
796 Within its \bt_msg_iter's message sequence, the clock snapshot of a
797 message iterator inactivity message must be greater than or equal to
798 any clock snapshot of any previous message.
800 Borrow a message iterator inactivity message's clock snapshot
802 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
806 <h1>\anchor api-msg-mip Message Interchange Protocol</h1>
808 The <em>Message Interchange Protocol</em> (MIP) is the system of rules
809 used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
810 trace processing graph.
812 The MIP covers everything related to messages and what they contain, as
813 well as how they are ordered within the \ref api-msg-seq "sequence" that
814 a message iterator produces.
818 - A valid message sequence for a given \bt_stream starts with a
819 \bt_sb_msg and ends with a \bt_se_msg.
822 \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
823 is [0, 2<sup>64</sup> - 1].
825 - The available message types are stream beginning and end, event,
826 packet beginning and end, discarded events and packets, and message
829 The MIP has a version which is a single major number, independent from
830 the \bt_name project's version. As of \bt_name_version_min_maj, the only
831 available MIP version is 0.
833 If what the MIP covers changes in a breaking or semantical way in the
834 future, the MIP and \bt_name's minor versions will be bumped.
836 When you create a trace processing \bt_graph with bt_graph_create(), you
837 must pass the effective MIP version to use. Then, the components you
838 \ref api-graph-lc-add "add" to this graph can access this configured MIP
839 version with bt_self_component_get_graph_mip_version() and behave
840 accordingly. In other words, if the configured MIP version is 0, then a
841 component cannot use features introduced by MIP version 1. For
842 example, should the project introduce a new type of \bt_fc, the MIP
843 version would be bumped.
845 A component which cannot honor a given MIP can fail at
846 initialization time, making the corresponding
847 <code>bt_graph_add_*_component*()</code> call fail too. To avoid any
848 surprise, you can create a \bt_comp_descr_set with descriptors of the
849 components you intend to add to a trace processing graph and call
850 bt_get_greatest_operative_mip_version() to get the greatest (most
851 recent) MIP version you can use.
853 To get the library's latest MIP version, use
854 bt_get_maximal_mip_version().
856 The ultimate goal of the MIP version feature is for the \bt_name project
857 to be able to introduce new features or even major breaking changes
858 without breaking existing \bt_p_comp_cls. This is especially important
859 considering that \bt_name supports \bt_p_plugin written by different
860 authors. Of course one of the project's objectives is to bump the MIP
861 version as rarely as possible. When it is required, though, it's a
862 welcome tool to make the project evolve gracefully.
864 The Message Interchange Protocol has no dedicated documentation as this
865 very message module (and its submodules, like \ref api-tir)
866 documentation is enough. You can consider that all the
867 functions of the message and trace IR objects have an implicit MIP
868 version \ref api-fund-pre-post "precondition". When a given
869 function documentation does not explicitly document a MIP version
870 precondition, it means that the effective MIP version has no effect on
871 said function's behaviour.
873 <h2>\anchor api-msg-seq Message sequence rules</h2>
875 The purpose of a \bt_msg_iter is to iterate a sequence of messages.
877 Those messages can be related to different \bt_p_stream:
879 @image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
881 However, for such a message sequence, the current \bt_mip
882 (version \bt_max_mip_version) dictates that:
886 For a given \bt_stream:
888 - The sequence must begin with a \bt_sb_msg.
889 - The sequence must end with a \bt_se_msg.
890 - <strong>If the stream's \ref api-tir-stream-cls "class"
891 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"</strong>:
892 - Any \bt_pb_msg must be followed with a \bt_pe_msg.
893 - All \bt_p_ev_msg must be between a packet beginning and a
895 - A \bt_disc_pkt_msg must be (one of):
896 - Before the first packet beginning message.
897 - Between a packet end message and a packet beginning message.
898 - After the last packet end message.
900 The rules above can be summarized by the following regular
904 <dt>Without packets</dt>
911 <dt>With packets</dt>
914 SB ((PB (E | DE)* PE) | DE | DP)* SE
923 <dd>\bt_c_sb_msg</dd>
926 <dd>\bt_c_se_msg</dd>
929 <dd>\bt_c_ev_msg</dd>
932 <dd>\bt_c_pb_msg</dd>
935 <dd>\bt_c_pe_msg</dd>
938 <dd>\bt_c_disc_ev_msg</dd>
941 <dd>\bt_c_disc_pkt_msg</dd>
944 For a given message iterator, for any message with a \bt_cs, its
945 clock snapshot must be greater than or equal to any clock snapshot
946 of any previous message.
948 For the scope of this rule, the clock snapshot of a \bt_disc_ev_msg
949 or of a \bt_disc_pkt_msg is its beginning default clock snapshot.
951 For a given message iterator, the \bt_p_cs of all the messages of
952 the sequence with a clock snapshot must be correlatable
953 (see \ref api-tir-clock-cls-origin "Clock value vs. clock class origin").
963 @typedef struct bt_message bt_message;
978 Message type enumerators.
980 typedef enum bt_message_type
{
985 BT_MESSAGE_TYPE_STREAM_BEGINNING
= 1 << 0,
991 BT_MESSAGE_TYPE_STREAM_END
= 1 << 1,
997 BT_MESSAGE_TYPE_EVENT
= 1 << 2,
1003 BT_MESSAGE_TYPE_PACKET_BEGINNING
= 1 << 3,
1009 BT_MESSAGE_TYPE_PACKET_END
= 1 << 4,
1015 BT_MESSAGE_TYPE_DISCARDED_EVENTS
= 1 << 5,
1021 BT_MESSAGE_TYPE_DISCARDED_PACKETS
= 1 << 6,
1027 BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
= 1 << 7,
1032 Returns the type enumerator of the message \bt_p{message}.
1035 Message of which to get the type enumerator
1038 Type enumerator of \bt_p{message}.
1040 @bt_pre_not_null{message}
1042 extern bt_message_type
bt_message_get_type(const bt_message
*message
);
1047 @name Common stream message
1054 bt_message_stream_beginning_borrow_default_clock_snapshot_const()
1056 bt_message_stream_end_borrow_default_clock_snapshot_const().
1058 typedef enum bt_message_stream_clock_snapshot_state
{
1063 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
= 1,
1067 Unknown (no) \bt_cs.
1069 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
= 0,
1070 } bt_message_stream_clock_snapshot_state
;
1075 @name Stream beginning message
1081 Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
1082 \bt_msg_iter \bt_p{self_message_iterator}.
1084 On success, the returned stream beginning message has the following
1092 <td>\ref api-msg-sb-prop-stream "Stream"
1095 <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
1099 @param[in] self_message_iterator
1100 Self message iterator from which to create the stream beginning
1103 Stream of which the message to create indicates the beginning.
1106 New stream beginning message reference, or \c NULL on memory error.
1108 @bt_pre_not_null{self_message_iterator}
1109 @bt_pre_not_null{stream}
1111 @bt_post_success_frozen{stream}
1114 bt_message
*bt_message_stream_beginning_create(
1115 bt_self_message_iterator
*self_message_iterator
,
1116 const bt_stream
*stream
);
1120 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
1122 See the \ref api-msg-sb-prop-stream "stream" property.
1125 Stream beginning message from which to borrow the stream.
1129 \em Borrowed reference of the stream of \bt_p{message}.
1131 The returned pointer remains valid as long as \bt_p{message} exists.
1134 @bt_pre_not_null{message}
1135 @bt_pre_is_sb_msg{message}
1137 @sa bt_message_stream_beginning_borrow_stream_const() —
1138 \c const version of this function.
1140 extern bt_stream
*bt_message_stream_beginning_borrow_stream(
1141 bt_message
*message
);
1145 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
1148 See bt_message_stream_beginning_borrow_stream().
1150 extern const bt_stream
*bt_message_stream_beginning_borrow_stream_const(
1151 const bt_message
*message
);
1155 Sets the value, in clock cycles, of the default \bt_cs of the
1156 \bt_sb_msg \bt_p{message} to \bt_p{value}.
1158 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1161 Stream beginning message of which to set the default clock snapshot
1162 value to \bt_p{value}.
1164 New value (clock cycles) of the default clock snapshot of
1167 @bt_pre_not_null{message}
1168 @bt_pre_hot{message}
1169 @bt_pre_is_sb_msg{message}
1171 The \bt_stream_cls of \bt_p{message} has a
1172 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1174 @sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() —
1175 Borrows the default clock snapshot of a stream beginning message.
1178 void bt_message_stream_beginning_set_default_clock_snapshot(
1179 bt_message
*message
, uint64_t value
);
1183 Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
1185 See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1188 Stream beginning message from which to borrow the default clock
1190 @param[out] clock_snapshot
1191 <strong>If this function returns
1192 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1193 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1194 clock snapshot of \bt_p{message}.
1196 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1197 The default clock snapshot of \bt_p{message} is known and returned
1198 as \bt_p{*clock_snapshot}.
1199 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1200 \bt_p{message} has no default clock snapshot: its time is unknown.
1202 @bt_pre_not_null{message}
1203 @bt_pre_is_sb_msg{message}
1205 The \bt_stream_cls of \bt_p{message} has a
1206 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1207 @bt_pre_not_null{clock_snapshot}
1209 @sa bt_message_stream_beginning_set_default_clock_snapshot() —
1210 Sets the default clock snapshot of a stream beginning message.
1212 extern bt_message_stream_clock_snapshot_state
1213 bt_message_stream_beginning_borrow_default_clock_snapshot_const(
1214 const bt_message
*message
,
1215 const bt_clock_snapshot
**clock_snapshot
);
1219 Borrows the default \bt_clock_cls of the \bt_stream_cls
1220 of the \bt_sb_msg \bt_p{message}.
1222 See the stream class's
1223 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1226 This is a helper which is equivalent to
1229 bt_stream_class_borrow_default_clock_class_const(
1230 bt_stream_borrow_class_const(
1231 bt_message_stream_beginning_borrow_stream_const(message)))
1235 Stream beginning message from which to borrow its stream's class's
1236 default clock class.
1239 \em Borrowed reference of the default clock class of
1240 the stream class of \bt_p{message}, or \c NULL if none.
1242 @bt_pre_not_null{message}
1243 @bt_pre_is_sb_msg{message}
1245 extern const bt_clock_class
*
1246 bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
1247 const bt_message
*message
);
1252 @name Stream end message
1258 Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
1259 \bt_msg_iter \bt_p{self_message_iterator}.
1261 On success, the returned stream end message has the following
1269 <td>\ref api-msg-se-prop-stream "Stream"
1272 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1276 @param[in] self_message_iterator
1277 Self message iterator from which to create the stream end
1280 Stream of which the message to create indicates the end.
1283 New stream end message reference, or \c NULL on memory error.
1285 @bt_pre_not_null{self_message_iterator}
1286 @bt_pre_not_null{stream}
1288 @bt_post_success_frozen{stream}
1291 bt_message
*bt_message_stream_end_create(
1292 bt_self_message_iterator
*self_message_iterator
,
1293 const bt_stream
*stream
);
1297 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
1299 See the \ref api-msg-se-prop-stream "stream" property.
1302 Stream end message from which to borrow the stream.
1306 \em Borrowed reference of the stream of \bt_p{message}.
1308 The returned pointer remains valid as long as \bt_p{message} exists.
1311 @bt_pre_not_null{message}
1312 @bt_pre_is_se_msg{message}
1314 @sa bt_message_stream_end_borrow_stream_const() —
1315 \c const version of this function.
1317 extern bt_stream
*bt_message_stream_end_borrow_stream(
1318 bt_message
*message
);
1322 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
1325 See bt_message_stream_end_borrow_stream().
1327 extern const bt_stream
*bt_message_stream_end_borrow_stream_const(
1328 const bt_message
*message
);
1332 Sets the value, in clock cycles, of the default \bt_cs of the
1333 \bt_se_msg \bt_p{message} to \bt_p{value}.
1335 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1338 Stream end message of which to set the default clock snapshot
1339 value to \bt_p{value}.
1341 New value (clock cycles) of the default clock snapshot of
1344 @bt_pre_not_null{message}
1345 @bt_pre_hot{message}
1346 @bt_pre_is_se_msg{message}
1348 The \bt_stream_cls of \bt_p{message} has a
1349 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1351 @sa bt_message_stream_end_borrow_default_clock_snapshot_const() —
1352 Borrows the default clock snapshot of a stream end message.
1355 void bt_message_stream_end_set_default_clock_snapshot(
1356 bt_message
*message
, uint64_t value
);
1360 Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
1362 See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1365 Stream end message from which to borrow the default clock
1367 @param[out] clock_snapshot
1368 <strong>If this function returns
1369 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1370 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1371 clock snapshot of \bt_p{message}.
1373 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1374 The default clock snapshot of \bt_p{message} is known and returned
1375 as \bt_p{*clock_snapshot}.
1376 @retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1377 \bt_p{message} has no default clock snapshot: its time is unknown.
1379 @bt_pre_not_null{message}
1380 @bt_pre_is_se_msg{message}
1382 The \bt_stream_cls of \bt_p{message} has a
1383 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1384 @bt_pre_not_null{clock_snapshot}
1386 @sa bt_message_stream_end_set_default_clock_snapshot() —
1387 Sets the default clock snapshot of a stream end message.
1389 extern bt_message_stream_clock_snapshot_state
1390 bt_message_stream_end_borrow_default_clock_snapshot_const(
1391 const bt_message
*message
,
1392 const bt_clock_snapshot
**clock_snapshot
);
1396 Borrows the default \bt_clock_cls of the \bt_stream_cls
1397 of the \bt_se_msg \bt_p{message}.
1399 See the stream class's
1400 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1403 This is a helper which is equivalent to
1406 bt_stream_class_borrow_default_clock_class_const(
1407 bt_stream_borrow_class_const(
1408 bt_message_stream_end_borrow_stream_const(message)))
1412 Stream end message from which to borrow its stream's class's
1413 default clock class.
1416 \em Borrowed reference of the default clock class of
1417 the stream class of \bt_p{message}, or \c NULL if none.
1419 @bt_pre_not_null{message}
1420 @bt_pre_is_se_msg{message}
1422 extern const bt_clock_class
*
1423 bt_message_stream_end_borrow_stream_class_default_clock_class_const(
1424 const bt_message
*message
);
1435 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1436 \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
1437 \bt_msg_iter \bt_p{self_message_iterator}.
1441 Only use this function if
1444 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1447 returns #BT_FALSE and
1450 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1456 bt_message_event_create_with_default_clock_snapshot(),
1457 bt_message_event_create_with_packet(), or
1458 bt_message_event_create_with_packet_and_default_clock_snapshot().
1461 On success, the returned event message has the following property
1469 <td>\ref api-msg-ev-prop-ev "Event"
1471 An instance (with \bt_p_field that are not set) of
1474 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1478 @param[in] self_message_iterator
1479 Self message iterator from which to create the event message.
1480 @param[in] event_class
1481 Class of the \bt_ev of the message to create.
1483 Stream conceptually containing the event of the message to create.
1486 New event message reference, or \c NULL on memory error.
1488 @bt_pre_not_null{self_message_iterator}
1490 The \bt_stream_cls of \bt_p{event_class} is also the class of
1491 \bt_p{stream}, that is,
1492 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1494 <code>bt_stream_borrow_class_const(stream)</code> have the
1496 @bt_pre_not_null{stream}
1498 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1501 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1504 @bt_post_success_frozen{event_class}
1505 @bt_post_success_frozen{stream}
1508 bt_message
*bt_message_event_create(
1509 bt_self_message_iterator
*self_message_iterator
,
1510 const bt_event_class
*event_class
,
1511 const bt_stream
*stream
);
1515 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1516 \bt_p{event_class} and a default \bt_cs with the value
1517 \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
1518 the \bt_msg_iter \bt_p{self_message_iterator}.
1522 Only use this function if
1525 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1528 returns #BT_FALSE and
1531 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1534 does \em not return \c NULL.
1537 bt_message_event_create(),
1538 bt_message_event_create_with_packet(), or
1539 bt_message_event_create_with_packet_and_default_clock_snapshot().
1542 On success, the returned event message has the following property
1550 <td>\ref api-msg-ev-prop-ev "Event"
1552 An instance (with \bt_p_field that are not set) of
1555 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1556 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1559 @param[in] self_message_iterator
1560 Self message iterator from which to create the event message.
1561 @param[in] event_class
1562 Class of the \bt_ev of the message to create.
1564 Stream conceptually containing the event of the message to create.
1565 @param[in] clock_snapshot_value
1566 Value (clock cycles) of the default clock snapshot of
1570 New event message reference, or \c NULL on memory error.
1572 @bt_pre_not_null{self_message_iterator}
1574 The \bt_stream_cls of \bt_p{event_class} is also the class of
1575 \bt_p{stream}, that is,
1576 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1578 <code>bt_stream_borrow_class_const(stream)</code> have the
1580 @bt_pre_not_null{stream}
1582 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1585 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1586 does \em not return \c NULL.
1588 @bt_post_success_frozen{event_class}
1589 @bt_post_success_frozen{stream}
1592 bt_message
*bt_message_event_create_with_default_clock_snapshot(
1593 bt_self_message_iterator
*self_message_iterator
,
1594 const bt_event_class
*event_class
,
1595 const bt_stream
*stream
, uint64_t clock_snapshot_value
);
1599 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1600 \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
1601 \bt_msg_iter \bt_p{self_message_iterator}.
1605 Only use this function if
1608 bt_stream_class_supports_packets(
1609 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1612 returns #BT_TRUE and
1615 bt_stream_class_borrow_default_clock_class_const(
1616 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1622 bt_message_event_create(),
1623 bt_message_event_create_with_default_clock_snapshot(), or
1624 bt_message_event_create_with_packet_and_default_clock_snapshot().
1627 On success, the returned event message has the following property
1635 <td>\ref api-msg-ev-prop-ev "Event"
1637 An instance (with \bt_p_field that are not set) of
1640 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1644 @param[in] self_message_iterator
1645 Self message iterator from which to create the event message.
1646 @param[in] event_class
1647 Class of the \bt_ev of the message to create.
1649 Packet conceptually containing the event of the message to create.
1652 New event message reference, or \c NULL on memory error.
1654 @bt_pre_not_null{self_message_iterator}
1656 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1657 \bt_p{packet}, that is,
1658 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1660 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1661 have the same value.
1662 @bt_pre_not_null{packet}
1664 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1667 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1670 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1671 any, and all its contained \bt_p_field, recursively, are set.
1673 @bt_post_success_frozen{event_class}
1674 @bt_post_success_frozen{packet}
1677 bt_message
*bt_message_event_create_with_packet(
1678 bt_self_message_iterator
*self_message_iterator
,
1679 const bt_event_class
*event_class
,
1680 const bt_packet
*packet
);
1684 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1685 \bt_p{event_class} and a default \bt_cs with the value
1686 \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
1687 the \bt_msg_iter \bt_p{self_message_iterator}.
1691 Only use this function if
1694 bt_stream_class_supports_packets(
1695 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1698 returns #BT_TRUE and
1701 bt_stream_class_borrow_default_clock_class_const(
1702 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1705 does \em not return \c NULL.
1708 bt_message_event_create(),
1709 bt_message_event_create_with_default_clock_snapshot(), or
1710 bt_message_event_create_with_packet().
1713 On success, the returned event message has the following property
1721 <td>\ref api-msg-ev-prop-ev "Event"
1723 An instance (with \bt_p_field that are not set) of
1726 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1727 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1730 @param[in] self_message_iterator
1731 Self message iterator from which to create the event message.
1732 @param[in] event_class
1733 Class of the \bt_ev of the message to create.
1735 Packet conceptually containing the event of the message to create.
1736 @param[in] clock_snapshot_value
1737 Value (clock cycles) of the default clock snapshot of
1741 New event message reference, or \c NULL on memory error.
1743 @bt_pre_not_null{self_message_iterator}
1745 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1746 \bt_p{packet}, that is,
1747 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1749 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1750 have the same value.
1751 @bt_pre_not_null{packet}
1753 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1756 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1757 does \em not return \c NULL.
1759 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1760 any, and all its contained \bt_p_field, recursively, are set.
1762 @bt_post_success_frozen{event_class}
1763 @bt_post_success_frozen{stream}
1766 bt_message
*bt_message_event_create_with_packet_and_default_clock_snapshot(
1767 bt_self_message_iterator
*self_message_iterator
,
1768 const bt_event_class
*event_class
,
1769 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1773 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
1775 See the \ref api-msg-ev-prop-ev "event" property.
1778 Event message from which to borrow the event.
1782 \em Borrowed reference of the event of \bt_p{message}.
1784 The returned pointer remains valid as long as \bt_p{message} exists.
1787 @bt_pre_not_null{message}
1788 @bt_pre_is_ev_msg{message}
1790 @sa bt_message_event_borrow_event_const() —
1791 \c const version of this function.
1793 extern bt_event
*bt_message_event_borrow_event(
1794 bt_message
*message
);
1798 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
1801 See bt_message_event_borrow_event().
1803 extern const bt_event
*bt_message_event_borrow_event_const(
1804 const bt_message
*message
);
1808 Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
1810 See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
1813 Event message from which to borrow the default clock snapshot.
1816 Default clock snapshot of \bt_p{message}.
1818 @bt_pre_not_null{message}
1819 @bt_pre_is_ev_msg{message}
1821 The \bt_stream_cls of \bt_p{message} has a
1822 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1824 extern const bt_clock_snapshot
*
1825 bt_message_event_borrow_default_clock_snapshot_const(const bt_message
*message
);
1829 Borrows the default \bt_clock_cls of the \bt_stream_cls
1830 of the \bt_ev_msg \bt_p{message}.
1832 See the stream class's
1833 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1836 This is a helper which is equivalent to
1839 bt_stream_class_borrow_default_clock_class_const(
1840 bt_stream_borrow_class_const(
1841 bt_event_borrow_stream_const(
1842 bt_message_event_borrow_event_const(message))))
1846 Event message from which to borrow its stream's class's
1847 default clock class.
1850 \em Borrowed reference of the default clock class of
1851 the stream class of \bt_p{message}, or \c NULL if none.
1853 @bt_pre_not_null{message}
1854 @bt_pre_is_ev_msg{message}
1856 extern const bt_clock_class
*
1857 bt_message_event_borrow_stream_class_default_clock_class_const(
1858 const bt_message
*message
);
1863 @name Packet beginning message
1869 Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
1870 \bt_msg_iter \bt_p{self_message_iterator}.
1874 Only use this function if
1877 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1878 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1884 bt_message_packet_beginning_create_with_default_clock_snapshot().
1887 On success, the returned packet beginning message has the following
1895 <td>\ref api-msg-pb-prop-pkt "Packet"
1898 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1902 @param[in] self_message_iterator
1903 Self message iterator from which to create the packet beginning
1906 Packet of which the message to create indicates the beginning.
1909 New packet beginning message reference, or \c NULL on memory error.
1911 @bt_pre_not_null{self_message_iterator}
1912 @bt_pre_not_null{packet}
1914 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1915 returns #BT_FALSE for
1916 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1918 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1919 any, and all its contained \bt_p_field, recursively, are set.
1921 @bt_post_success_frozen{packet}
1924 bt_message
*bt_message_packet_beginning_create(
1925 bt_self_message_iterator
*self_message_iterator
,
1926 const bt_packet
*packet
);
1930 Creates a \bt_pb_msg having a default \bt_cs with the value
1931 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
1932 \bt_msg_iter \bt_p{self_message_iterator}.
1936 Only use this function if
1939 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1940 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1946 bt_message_packet_beginning_create().
1949 On success, the returned packet beginning message has the following
1957 <td>\ref api-msg-pb-prop-pkt "Packet"
1960 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1961 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1964 @param[in] self_message_iterator
1965 Self message iterator from which to create the packet beginning
1968 Packet of which the message to create indicates the beginning.
1969 @param[in] clock_snapshot_value
1970 Value (clock cycles) of the default clock snapshot of
1974 New packet beginning message reference, or \c NULL on memory error.
1976 @bt_pre_not_null{self_message_iterator}
1977 @bt_pre_not_null{packet}
1979 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1980 returns #BT_TRUE for
1981 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1983 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1984 any, and all its contained \bt_p_field, recursively, are set.
1986 @bt_post_success_frozen{packet}
1989 bt_message
*bt_message_packet_beginning_create_with_default_clock_snapshot(
1990 bt_self_message_iterator
*self_message_iterator
,
1991 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
1995 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
1997 See the \ref api-msg-pb-prop-pkt "packet" property.
2000 Packet beginning message from which to borrow the packet.
2004 \em Borrowed reference of the packet of \bt_p{message}.
2006 The returned pointer remains valid as long as \bt_p{message} exists.
2009 @bt_pre_not_null{message}
2010 @bt_pre_is_pb_msg{message}
2012 @sa bt_message_packet_beginning_borrow_packet_const() —
2013 \c const version of this function.
2015 extern bt_packet
*bt_message_packet_beginning_borrow_packet(
2016 bt_message
*message
);
2020 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
2023 See bt_message_packet_beginning_borrow_packet().
2025 extern const bt_packet
*bt_message_packet_beginning_borrow_packet_const(
2026 const bt_message
*message
);
2030 Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
2032 See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
2035 Packet beginning message from which to borrow the default clock
2039 Default clock snapshot of \bt_p{message}.
2041 @bt_pre_not_null{message}
2042 @bt_pre_is_pb_msg{message}
2044 The packets of the \bt_stream_cls of \bt_p{message}
2045 \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
2047 extern const bt_clock_snapshot
*
2048 bt_message_packet_beginning_borrow_default_clock_snapshot_const(
2049 const bt_message
*message
);
2053 Borrows the default \bt_clock_cls of the \bt_stream_cls
2054 of the \bt_pb_msg \bt_p{message}.
2056 See the stream class's
2057 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2060 This is a helper which is equivalent to
2063 bt_stream_class_borrow_default_clock_class_const(
2064 bt_stream_borrow_class_const(
2065 bt_packet_borrow_stream_const(
2066 bt_message_packet_beginning_borrow_packet_const(message))))
2070 Packet beginning message from which to borrow its stream's class's
2071 default clock class.
2074 \em Borrowed reference of the default clock class of
2075 the stream class of \bt_p{message}, or \c NULL if none.
2077 @bt_pre_not_null{message}
2078 @bt_pre_is_pb_msg{message}
2080 extern const bt_clock_class
*
2081 bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
2082 const bt_message
*message
);
2087 @name Packet end message
2093 Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
2094 \bt_msg_iter \bt_p{self_message_iterator}.
2098 Only use this function if
2101 bt_stream_class_packets_have_end_default_clock_snapshot(
2102 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2108 bt_message_packet_end_create_with_default_clock_snapshot().
2111 On success, the returned packet end message has the following
2119 <td>\ref api-msg-pe-prop-pkt "Packet"
2122 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2126 @param[in] self_message_iterator
2127 Self message iterator from which to create the packet end message.
2129 Packet of which the message to create indicates the end.
2132 New packet end message reference, or \c NULL on memory error.
2134 @bt_pre_not_null{self_message_iterator}
2135 @bt_pre_not_null{packet}
2137 bt_stream_class_packets_have_end_default_clock_snapshot()
2138 returns #BT_FALSE for
2139 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2141 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2142 any, and all its contained \bt_p_field, recursively, are set.
2144 @bt_post_success_frozen{packet}
2147 bt_message
*bt_message_packet_end_create(
2148 bt_self_message_iterator
*self_message_iterator
,
2149 const bt_packet
*packet
);
2153 Creates a \bt_pe_msg having a default \bt_cs with the value
2154 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
2155 \bt_msg_iter \bt_p{self_message_iterator}.
2159 Only use this function if
2162 bt_stream_class_packets_have_end_default_clock_snapshot(
2163 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2169 bt_message_packet_end_create().
2172 On success, the returned packet end message has the following
2180 <td>\ref api-msg-pe-prop-pkt "Packet"
2183 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2184 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
2187 @param[in] self_message_iterator
2188 Self message iterator from which to create the packet end
2191 Packet of which the message to create indicates the end.
2192 @param[in] clock_snapshot_value
2193 Value (clock cycles) of the default clock snapshot of
2197 New packet end message reference, or \c NULL on memory error.
2199 @bt_pre_not_null{self_message_iterator}
2200 @bt_pre_not_null{packet}
2202 bt_stream_class_packets_have_end_default_clock_snapshot()
2203 returns #BT_TRUE for
2204 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2206 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2207 any, and all its contained \bt_p_field, recursively, are set.
2209 @bt_post_success_frozen{packet}
2212 bt_message
*bt_message_packet_end_create_with_default_clock_snapshot(
2213 bt_self_message_iterator
*self_message_iterator
,
2214 const bt_packet
*packet
, uint64_t clock_snapshot_value
);
2218 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
2220 See the \ref api-msg-pe-prop-pkt "packet" property.
2223 Packet end message from which to borrow the packet.
2227 \em Borrowed reference of the packet of \bt_p{message}.
2229 The returned pointer remains valid as long as \bt_p{message} exists.
2232 @bt_pre_not_null{message}
2233 @bt_pre_is_pe_msg{message}
2235 @sa bt_message_packet_end_borrow_packet_const() —
2236 \c const version of this function.
2238 extern bt_packet
*bt_message_packet_end_borrow_packet(
2239 bt_message
*message
);
2243 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
2246 See bt_message_packet_end_borrow_packet().
2248 extern const bt_packet
*bt_message_packet_end_borrow_packet_const(
2249 const bt_message
*message
);
2253 Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
2255 See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
2258 Packet end message from which to borrow the default clock
2262 Default clock snapshot of \bt_p{message}.
2264 @bt_pre_not_null{message}
2265 @bt_pre_is_pe_msg{message}
2267 The packets of the \bt_stream_cls of \bt_p{message}
2268 \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
2270 extern const bt_clock_snapshot
*
2271 bt_message_packet_end_borrow_default_clock_snapshot_const(
2272 const bt_message
*message
);
2276 Borrows the default \bt_clock_cls of the \bt_stream_cls
2277 of the \bt_pe_msg \bt_p{message}.
2279 See the stream class's
2280 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2283 This is a helper which is equivalent to
2286 bt_stream_class_borrow_default_clock_class_const(
2287 bt_stream_borrow_class_const(
2288 bt_packet_borrow_stream_const(
2289 bt_message_packet_end_borrow_packet_const(message))))
2293 Packet end message from which to borrow its stream's class's
2294 default clock class.
2297 \em Borrowed reference of the default clock class of
2298 the stream class of \bt_p{message}, or \c NULL if none.
2300 @bt_pre_not_null{message}
2301 @bt_pre_is_pe_msg{message}
2303 extern const bt_clock_class
*
2304 bt_message_packet_end_borrow_stream_class_default_clock_class_const(
2305 const bt_message
*message
);
2310 @name Discarded events message
2316 Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
2317 \bt_msg_iter \bt_p{self_message_iterator}.
2321 Only use this function if
2324 bt_stream_class_discarded_events_have_default_clock_snapshots(
2325 bt_stream_borrow_class_const(stream))
2331 bt_message_discarded_events_create_with_default_clock_snapshots().
2334 On success, the returned discarded events message has the following
2342 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2345 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2348 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2351 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2355 @param[in] self_message_iterator
2356 Self message iterator from which to create the discarded events
2359 Stream from which the events were discarded.
2362 New discarded events message reference, or \c NULL on memory error.
2364 @bt_pre_not_null{self_message_iterator}
2365 @bt_pre_not_null{stream}
2367 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2370 @bt_post_success_frozen{stream}
2372 extern bt_message
*bt_message_discarded_events_create(
2373 bt_self_message_iterator
*self_message_iterator
,
2374 const bt_stream
*stream
);
2378 Creates a \bt_disc_ev_msg having the beginning and end default
2379 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2380 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2381 from the \bt_msg_iter \bt_p{self_message_iterator}.
2385 Only use this function if
2388 bt_stream_class_discarded_events_have_default_clock_snapshots(
2389 bt_stream_borrow_class_const(stream))
2395 bt_message_discarded_events_create().
2398 On success, the returned discarded events message has the following
2406 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2409 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2410 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2412 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2413 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2415 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2419 @param[in] self_message_iterator
2420 Self message iterator from which to create the discarded events
2423 Stream from which the events were discarded.
2424 @param[in] beginning_clock_snapshot_value
2425 Value (clock cycles) of the beginning default clock snapshot of
2427 @param[in] end_clock_snapshot_value
2428 Value (clock cycles) of the end default clock snapshot of
2432 New discarded events message reference, or \c NULL on memory error.
2434 @bt_pre_not_null{self_message_iterator}
2435 @bt_pre_not_null{stream}
2437 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2440 @bt_post_success_frozen{stream}
2442 extern bt_message
*bt_message_discarded_events_create_with_default_clock_snapshots(
2443 bt_self_message_iterator
*self_message_iterator
,
2444 const bt_stream
*stream
,
2445 uint64_t beginning_clock_snapshot_value
,
2446 uint64_t end_clock_snapshot_value
);
2450 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2452 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2455 Discarded events message from which to borrow the stream.
2459 \em Borrowed reference of the stream of \bt_p{message}.
2461 The returned pointer remains valid as long as \bt_p{message} exists.
2464 @bt_pre_not_null{message}
2465 @bt_pre_is_disc_ev_msg{message}
2467 @sa bt_message_discarded_events_borrow_stream_const() —
2468 \c const version of this function.
2470 extern bt_stream
*bt_message_discarded_events_borrow_stream(
2471 bt_message
*message
);
2475 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2478 See bt_message_discarded_events_borrow_stream().
2480 extern const bt_stream
*
2481 bt_message_discarded_events_borrow_stream_const(const bt_message
*message
);
2485 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2489 \ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2493 Discarded events message from which to borrow the beginning default
2497 Beginning default clock snapshot of \bt_p{message}.
2499 @bt_pre_not_null{message}
2500 @bt_pre_is_disc_ev_msg{message}
2502 The discarded packets messages of the \bt_stream_cls of
2504 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2506 extern const bt_clock_snapshot
*
2507 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
2508 const bt_message
*message
);
2512 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2516 \ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2520 Discarded events message from which to borrow the end default clock
2524 End default clock snapshot of \bt_p{message}.
2526 @bt_pre_not_null{message}
2527 @bt_pre_is_disc_ev_msg{message}
2529 The discarded packets messages of the \bt_stream_cls of
2531 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2533 extern const bt_clock_snapshot
*
2534 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
2535 const bt_message
*message
);
2539 Borrows the default \bt_clock_cls of the \bt_stream_cls
2540 of the \bt_disc_ev_msg \bt_p{message}.
2542 See the stream class's
2543 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2546 This is a helper which is equivalent to
2549 bt_stream_class_borrow_default_clock_class_const(
2550 bt_stream_borrow_class_const(
2551 bt_message_discarded_events_borrow_stream_const(message)))
2555 Discarded events message from which to borrow its stream's class's
2556 default clock class.
2559 \em Borrowed reference of the default clock class of
2560 the stream class of \bt_p{message}, or \c NULL if none.
2562 @bt_pre_not_null{message}
2563 @bt_pre_is_disc_ev_msg{message}
2565 extern const bt_clock_class
*
2566 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
2567 const bt_message
*message
);
2571 Sets the number of discarded events of the \bt_disc_ev_msg
2572 \bt_p{message} to \bt_p{count}.
2574 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2578 Discarded events message of which to set the number of discarded
2579 events to \bt_p{count}.
2581 New number of discarded events of \bt_p{message}.
2583 @bt_pre_not_null{message}
2584 @bt_pre_hot{message}
2585 @bt_pre_is_disc_ev_msg{message}
2587 @sa bt_message_discarded_events_get_count() —
2588 Returns the number of discarded events of a discarded events
2591 extern void bt_message_discarded_events_set_count(bt_message
*message
,
2596 Returns the number of discarded events of the \bt_disc_ev_msg
2599 See the \ref api-msg-disc-ev-prop-count "discarded event count"
2603 Discarded events message of which to get the number of discarded
2606 <strong>If this function returns
2607 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2608 the number of discarded events of \bt_p{message}.
2610 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2611 The number of discarded events of \bt_p{message} is available.
2612 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2613 The number of discarded events of \bt_p{message} is not available.
2615 @bt_pre_not_null{message}
2616 @bt_pre_is_disc_ev_msg{message}
2617 @bt_pre_not_null{count}
2619 @sa bt_message_discarded_events_set_count() —
2620 Sets the number of discarded events of a discarded events message.
2622 extern bt_property_availability
bt_message_discarded_events_get_count(
2623 const bt_message
*message
, uint64_t *count
);
2628 @name Discarded packets message
2634 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2635 \bt_msg_iter \bt_p{self_message_iterator}.
2639 Only use this function if
2642 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2643 bt_stream_borrow_class_const(stream))
2649 bt_message_discarded_packets_create_with_default_clock_snapshots().
2652 On success, the returned discarded packets message has the following
2660 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2663 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2666 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2669 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2673 @param[in] self_message_iterator
2674 Self message iterator from which to create the discarded packets
2677 Stream from which the packets were discarded.
2680 New discarded packets message reference, or \c NULL on memory error.
2682 @bt_pre_not_null{self_message_iterator}
2683 @bt_pre_not_null{stream}
2685 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2688 @bt_post_success_frozen{stream}
2690 extern bt_message
*bt_message_discarded_packets_create(
2691 bt_self_message_iterator
*self_message_iterator
,
2692 const bt_stream
*stream
);
2696 Creates a \bt_disc_pkt_msg having the beginning and end default
2697 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2698 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2699 from the \bt_msg_iter \bt_p{self_message_iterator}.
2703 Only use this function if
2706 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2707 bt_stream_borrow_class_const(stream))
2713 bt_message_discarded_packets_create().
2716 On success, the returned discarded packets message has the following
2724 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2727 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2728 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2730 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2731 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2733 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2737 @param[in] self_message_iterator
2738 Self message iterator from which to create the discarded packets
2741 Stream from which the packets were discarded.
2742 @param[in] beginning_clock_snapshot_value
2743 Value (clock cycles) of the beginning default clock snapshot of
2745 @param[in] end_clock_snapshot_value
2746 Value (clock cycles) of the end default clock snapshot of
2750 New discarded packets message reference, or \c NULL on memory error.
2752 @bt_pre_not_null{self_message_iterator}
2753 @bt_pre_not_null{stream}
2755 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2758 @bt_post_success_frozen{stream}
2760 extern bt_message
*bt_message_discarded_packets_create_with_default_clock_snapshots(
2761 bt_self_message_iterator
*self_message_iterator
,
2762 const bt_stream
*stream
, uint64_t beginning_clock_snapshot_value
,
2763 uint64_t end_clock_snapshot_value
);
2767 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2769 See the \ref api-msg-disc-ev-prop-stream "stream" property.
2772 Discarded packets message from which to borrow the stream.
2776 \em Borrowed reference of the stream of \bt_p{message}.
2778 The returned pointer remains valid as long as \bt_p{message} exists.
2781 @bt_pre_not_null{message}
2782 @bt_pre_is_disc_pkt_msg{message}
2784 @sa bt_message_discarded_packets_borrow_stream_const() —
2785 \c const version of this function.
2787 extern bt_stream
*bt_message_discarded_packets_borrow_stream(
2788 bt_message
*message
);
2792 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2795 See bt_message_discarded_packets_borrow_stream().
2797 extern const bt_stream
*
2798 bt_message_discarded_packets_borrow_stream_const(const bt_message
*message
);
2802 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2806 \ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2810 Discarded packets message from which to borrow the beginning default
2814 Beginning default clock snapshot of \bt_p{message}.
2816 @bt_pre_not_null{message}
2817 @bt_pre_is_disc_pkt_msg{message}
2819 The discarded packets messages of the \bt_stream_cls of
2821 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2823 extern const bt_clock_snapshot
*
2824 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
2825 const bt_message
*message
);
2829 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2833 \ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2837 Discarded packets message from which to borrow the end default clock
2841 End default clock snapshot of \bt_p{message}.
2843 @bt_pre_not_null{message}
2844 @bt_pre_is_disc_pkt_msg{message}
2846 The discarded packets messages of the \bt_stream_cls of
2848 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2850 extern const bt_clock_snapshot
*
2851 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
2852 const bt_message
*message
);
2856 Borrows the default \bt_clock_cls of the \bt_stream_cls
2857 of the \bt_disc_pkt_msg \bt_p{message}.
2859 See the stream class's
2860 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2863 This is a helper which is equivalent to
2866 bt_stream_class_borrow_default_clock_class_const(
2867 bt_stream_borrow_class_const(
2868 bt_message_discarded_packets_borrow_stream_const(message)))
2872 Discarded packets message from which to borrow its stream's class's
2873 default clock class.
2876 \em Borrowed reference of the default clock class of
2877 the stream class of \bt_p{message}, or \c NULL if none.
2879 @bt_pre_not_null{message}
2880 @bt_pre_is_disc_pkt_msg{message}
2882 extern const bt_clock_class
*
2883 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
2884 const bt_message
*message
);
2888 Sets the number of discarded packets of the \bt_disc_pkt_msg
2889 \bt_p{message} to \bt_p{count}.
2891 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2895 Discarded packets message of which to set the number of discarded
2896 packets to \bt_p{count}.
2898 New number of discarded packets of \bt_p{message}.
2900 @bt_pre_not_null{message}
2901 @bt_pre_hot{message}
2902 @bt_pre_is_disc_pkt_msg{message}
2904 @sa bt_message_discarded_packets_get_count() —
2905 Returns the number of discarded packets of a discarded packets
2908 extern void bt_message_discarded_packets_set_count(bt_message
*message
,
2913 Returns the number of discarded packets of the \bt_disc_pkt_msg
2916 See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2920 Discarded packets message of which to get the number of discarded
2923 <strong>If this function returns
2924 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2925 the number of discarded packets of \bt_p{message}.
2927 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2928 The number of discarded packets of \bt_p{message} is available.
2929 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2930 The number of discarded packets of \bt_p{message} is not available.
2932 @bt_pre_not_null{message}
2933 @bt_pre_is_disc_pkt_msg{message}
2934 @bt_pre_not_null{count}
2936 @sa bt_message_discarded_packets_set_count() —
2937 Sets the number of discarded packets of a discarded packets message.
2939 extern bt_property_availability
bt_message_discarded_packets_get_count(
2940 const bt_message
*message
, uint64_t *count
);
2945 @name Message iterator inactivity message
2951 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2952 the \bt_clock_cls \bt_p{clock_class} with the value
2953 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2954 \bt_p{self_message_iterator}.
2956 On success, the returned message iterator inactivity message has the
2957 following property values:
2964 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2966 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2967 with the value \bt_p{clock_snapshot_value}.
2970 @param[in] self_message_iterator
2971 Self message iterator from which to create the message iterator
2973 @param[in] clock_class
2974 Class of the fictitious instance of which
2975 \bt_p{clock_snapshot_value} is the value of its snapshot.
2976 @param[in] clock_snapshot_value
2977 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2980 New message iterator inactivity message reference, or \c NULL on
2983 @bt_pre_not_null{self_message_iterator}
2984 @bt_pre_not_null{clock_class}
2986 @bt_post_success_frozen{clock_class}
2989 bt_message
*bt_message_message_iterator_inactivity_create(
2990 bt_self_message_iterator
*self_message_iterator
,
2991 const bt_clock_class
*clock_class
,
2992 uint64_t clock_snapshot_value
);
2996 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2998 See the \ref api-msg-inac-prop-cs "clock snapshot" property.
3001 Message iterator inactivity message from which to borrow the clock
3005 Clock snapshot of \bt_p{message}.
3007 @bt_pre_not_null{message}
3008 @bt_pre_is_inac_msg{message}
3010 extern const bt_clock_snapshot
*
3011 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
3012 const bt_message
*message
);
3017 @name Message reference count
3023 Increments the \ref api-fund-shared-object "reference count" of
3024 the message \bt_p{message}.
3028 Message of which to increment the reference count.
3033 @sa bt_message_put_ref() —
3034 Decrements the reference count of a message.
3036 extern void bt_message_get_ref(const bt_message
*message
);
3040 Decrements the \ref api-fund-shared-object "reference count" of
3041 the message \bt_p{message}.
3045 Message of which to decrement the reference count.
3050 @sa bt_message_get_ref() —
3051 Increments the reference count of a message.
3053 extern void bt_message_put_ref(const bt_message
*message
);
3057 Decrements the reference count of the message \bt_p{_message}, and
3058 then sets \bt_p{_message} to \c NULL.
3062 Message of which to decrement the reference count.
3064 Can contain \c NULL.
3067 @bt_pre_assign_expr{_message}
3069 #define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3071 bt_message_put_ref(_message); \
3072 (_message) = NULL; \
3077 Decrements the reference count of the message \bt_p{_dst}, sets
3078 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3080 This macro effectively moves a message reference from the expression
3081 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3082 \bt_p{_dst} reference.
3086 Destination expression.
3088 Can contain \c NULL.
3094 Can contain \c NULL.
3097 @bt_pre_assign_expr{_dst}
3098 @bt_pre_assign_expr{_src}
3100 #define BT_MESSAGE_MOVE_REF(_dst, _src) \
3102 bt_message_put_ref(_dst); \
3111 @name Message Interchange Protocol version
3117 Status codes for bt_get_greatest_operative_mip_version().
3119 typedef enum bt_get_greatest_operative_mip_version_status
{
3124 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
3130 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
= __BT_FUNC_STATUS_NO_MATCH
,
3136 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
3142 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
3143 } bt_get_greatest_operative_mip_version_status
;
3147 Computes the greatest \bt_mip version which
3148 you can use to create a trace processing \bt_graph to which you
3149 intend to \ref api-graph-lc-add "add components" described by the
3150 component descriptors \bt_p{component_descriptors}, and sets
3151 \bt_p{*mip_version} to the result.
3153 This function calls the
3154 \link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3155 method for each component descriptor in \bt_p{component_descriptors},
3156 and then returns the greatest common (operative) MIP version, if any.
3157 The "get supported MIP versions" method receives \bt_p{logging_level} as
3158 its \bt_p{logging_level} parameter.
3160 If this function does not find an operative MIP version for the
3161 component descriptors of \bt_p{component_descriptors}, it returns
3162 #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3165 As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
3166 returns 0, this function always sets \bt_p{*mip_version} to
3169 @param[in] component_descriptors
3170 Component descriptors for which to get the supported MIP versions
3171 to compute the greatest operative MIP version.
3172 @param[in] logging_level
3173 Logging level to use when calling the "get supported MIP versions"
3174 method for each component descriptor in
3175 \bt_p{component_descriptors}.
3176 @param[out] mip_version
3177 <strong>On success</strong>, \bt_p{*mip_version} is the greatest
3178 operative MIP version of all the component descriptors in
3179 \bt_p{component_descriptors}.
3181 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3183 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
3184 No operative MIP version exists for the component descriptors of
3185 \bt_p{component_descriptors}.
3186 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
3188 @retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3191 @bt_pre_not_null{component_descriptors}
3193 \bt_p{component_descriptors} contains one or more component
3195 @bt_pre_not_null{mip_version}
3197 extern bt_get_greatest_operative_mip_version_status
3198 bt_get_greatest_operative_mip_version(
3199 const bt_component_descriptor_set
*component_descriptors
,
3200 bt_logging_level logging_level
, uint64_t *mip_version
);
3204 Returns the maximal available \bt_mip version as of
3205 \bt_name_version_min_maj.
3207 As of \bt_name_version_min_maj, this function returns
3208 \bt_max_mip_version.
3211 Maximal available MIP version (\bt_max_mip_version).
3213 extern uint64_t bt_get_maximal_mip_version(void);
3223 #endif /* BABELTRACE2_GRAPH_MESSAGE_H */