include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / graph / message.h
CommitLineData
43c59509 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
43c59509 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
43c59509
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_GRAPH_MESSAGE_H
8#define BABELTRACE2_GRAPH_MESSAGE_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
43c59509
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
16#include <babeltrace2/types.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/*!
23@defgroup api-msg Messages
24@ingroup api-comp-cls-dev
25
26@brief
27 Elements exchanged between \bt_p_comp.
28
29<strong><em>Messages</em></strong> are the objects which are exchanged
30between \bt_p_comp in a trace processing \bt_graph to accomplish a
31trace processing job.
32
33\bt_cp_msg_iter create messages while message iterators \em and
34\bt_p_sink_comp consume messages.
35
36There are eight types of messages:
37
38- \bt_c_sb_msg
39- \bt_c_se_msg
40- \bt_c_ev_msg
41- \bt_c_pb_msg
42- \bt_c_pe_msg
43- \bt_c_disc_ev_msg
44- \bt_c_disc_pkt_msg
45- \bt_c_inac_msg
46
47The type of a message is #bt_message.
48
49Get the type enumerator of a message with bt_message_get_type().
50
51A message is a \ref api-fund-shared-object "shared object": get a
52new reference with bt_message_get_ref() and put an existing
53reference with bt_message_put_ref().
54
55Some library functions \ref api-fund-freezing "freeze" messages on
56success. The documentation of those functions indicate this
57postcondition.
58
59Messages transport objects of the \ref api-tir API, which is an
60intermediate representation of the tracing domain concepts.
61
62All types of messages, except the \bt_inac_msg type, are related to a
63specific <em>\bt_stream</em>, which represents a conceptual
64\ref api-msg-seq "sequence of messages".
65
66Some types of messages can have a default \bt_cs, depending on whether
67or not their stream has a conceptual default clock, that is, whether or
68not the stream's \ref api-tir-stream-cls "class" has a
69\ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
70The creation functions for those types of messages contain
71<code>_with_default_clock_snapshot</code> (for example,
72bt_message_event_create_with_default_clock_snapshot()).
73
74For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
75is optional, therefore they have dedicated
76bt_message_stream_beginning_set_default_clock_snapshot() and
77bt_message_stream_end_set_default_clock_snapshot() functions.
78
79All the message creation functions take a \bt_self_msg_iter as their
80first parameter. This is because a message iterator method is the only
81valid context to create a message.
82
83<h1>Message types</h1>
84
85This section details each type of message.
86
87The following table shows the creation functions and types for each type
88of message:
89
90<table>
91 <tr>
92 <th>Name
93 <th>Type enumerator
94 <th>Creation functions
95 <tr>
96 <td>\ref api-msg-sb "Stream beginning"
97 <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
98 <td>bt_message_stream_beginning_create()
99 <tr>
100 <td>\ref api-msg-se "Stream end"
101 <td>#BT_MESSAGE_TYPE_STREAM_END
102 <td>bt_message_stream_end_create()
103 <tr>
104 <td>\ref api-msg-ev "Event"
105 <td>#BT_MESSAGE_TYPE_EVENT
106 <td>
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()
111 <tr>
112 <td>\ref api-msg-pb "Packet beginning"
113 <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
114 <td>
115 bt_message_packet_beginning_create()<br>
116 bt_message_packet_beginning_create_with_default_clock_snapshot()
117 <tr>
118 <td>\ref api-msg-pe "Packet end"
119 <td>#BT_MESSAGE_TYPE_PACKET_END
120 <td>
121 bt_message_packet_end_create()<br>
122 bt_message_packet_end_create_with_default_clock_snapshot()
123 <tr>
124 <td>\ref api-msg-disc-ev "Discarded events"
125 <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
126 <td>
127 bt_message_discarded_events_create()<br>
128 bt_message_discarded_events_create_with_default_clock_snapshots()
129 <tr>
130 <td>\ref api-msg-disc-pkt "Discarded packets"
131 <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
132 <td>
133 bt_message_discarded_packets_create()<br>
134 bt_message_discarded_packets_create_with_default_clock_snapshots()
135 <tr>
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()
139</table>
140
141<h2>\anchor api-msg-sb Stream beginning message</h2>
142
143A <strong><em>stream beginning message</em></strong> indicates the
144beginning of a \bt_stream.
145
146For a given stream:
147
148- A stream beginning message is always the first one in the
149 \ref api-msg-seq "message sequence".
150
151- There can be only one stream beginning message.
152
153Create a stream beginning message with
154bt_message_stream_beginning_create().
155
156A stream beginning message has the following properties:
157
158<dl>
159 <dt>\anchor api-msg-sb-prop-stream Stream</dt>
160 <dd>
161 \bt_c_stream of which the message indicates the beginning.
162
163 You cannot change the stream once the message is created.
164
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().
168 </dd>
169
170 <dt>
171 \anchor api-msg-sb-prop-cs
172 \bt_dt_opt Default \bt_cs
173 </dt>
174 <dd>
175 Snapshot of the message's \bt_stream's default clock when the
176 stream begins.
177
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".
181
182 When a stream beginning message has no default clock snapshot,
183 then its time is <em>unknown</em>.
184
185 Set a stream beginning message's default clock snapshot with
186 bt_message_stream_beginning_set_default_clock_snapshot().
187
188 Borrow a stream beginning message's default clock snapshot with
189 bt_message_stream_beginning_borrow_default_clock_snapshot_const().
190 </dd>
191</dl>
192
193<h2>\anchor api-msg-se Stream end message</h2>
194
195A <strong><em>stream end message</em></strong> indicates the
196end of a \bt_stream.
197
198For a given stream:
199
200- A stream end message is always the last one in the
201 \ref api-msg-seq "message sequence".
202
203- There can be only one stream end message.
204
205Create a stream end message with bt_message_stream_end_create().
206
207A stream end message has the following properties:
208
209<dl>
210 <dt>\anchor api-msg-se-prop-stream Stream</dt>
211 <dd>
212 \bt_c_stream of which the message indicates the end.
213
214 You cannot change the stream once the message is created.
215
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().
219 </dd>
220
221 <dt>
222 \anchor api-msg-se-prop-cs
223 \bt_dt_opt Default \bt_cs
224 </dt>
225 <dd>
226 Snapshot of the message's \bt_stream's default clock when the
227 stream ends.
228
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".
232
233 When a stream end message has no default clock snapshot, then its
234 time is <em>unknown</em>.
235
236 Set a stream end message's default clock snapshot with
237 bt_message_stream_end_set_default_clock_snapshot().
238
239 Borrow a stream end message's default clock snapshot with
240 bt_message_stream_end_borrow_default_clock_snapshot_const().
241 </dd>
242</dl>
243
244<h2>\anchor api-msg-ev Event message</h2>
245
246An <strong><em>event message</em></strong> transports an \bt_ev and has,
247possibly, a default \bt_cs.
248
249Within its \bt_stream's \ref api-msg-seq "message sequence", an event
250message can only occur:
251
252<dl>
253 <dt>
254 If the stream's \ref api-tir-stream-cls "class"
255 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
256 </dt>
257 <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
258
259 <dt>
260 If the stream's class does not support packets
261 </dt>
262 <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
263</dl>
264
265To create an event message for a given stream, use:
266
267<dl>
268 <dt>
269 If the stream's \ref api-tir-stream-cls "class"
270 \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
271 </dt>
272 <dd>
273 <dl>
274 <dt>
275 If the stream's class has a
276 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
277 </dt>
278 <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
279
280 <dt>
281 If the stream's class does not have a
282 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
283 </dt>
284 <dd>bt_message_event_create_with_packet()</dd>
285 </dl>
286
287 Those two creation functions accept a \bt_pkt parameter which is
288 the packet logically containing the message's event. A packet is
289 part of a stream.
290 </dd>
291
292 <dt>
293 If the stream's class does not supports packets
294 </dt>
295 <dd>
296 <dl>
297 <dt>
298 If the stream's class has a default clock class
299 </dt>
300 <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
301
302 <dt>
303 If the stream's class does not have a
304 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
305 </dt>
306 <dd>bt_message_event_create()</dd>
307 </dl>
308 </dd>
309</dl>
310
311The four creation functions above accept an \bt_ev_cls parameter. When
312you create the message, the library instantiates this event class as an
313\bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
314This event class must be part of the class of the event message's
315stream.
316
317An event message's event is initially <em>not set</em>: before you emit
318the event message from a \bt_msg_iter's
319\link api-msg-iter-cls-meth-next "next" method\endlink, you need to
320borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
321bt_event_borrow_specific_context_field(), and
322bt_event_borrow_common_context_field()) and, recursively, set the values
323of the all their inner fields.
324
325An event message has the following properties:
326
327<dl>
328 <dt>\anchor api-msg-ev-prop-ev Event</dt>
329 <dd>
330 \bt_c_ev which the message transports.
331
332 This is an instance of the \bt_ev_cls which was passed to the
333 message's creation function.
334
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().
338
339 Borrow an event message's event with bt_message_event_borrow_event()
340 and bt_message_event_borrow_event_const().
341 </dd>
342
343 <dt>
344 \anchor api-msg-ev-prop-cs
345 \bt_dt_opt Default \bt_cs
346 </dt>
347 <dd>
348 Snapshot of the message's \bt_stream's default clock when the
349 event occurs.
350
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.
355
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.
359
360 Borrow an event message's default clock snapshot with
361 bt_message_event_borrow_default_clock_snapshot_const().
362 </dd>
363</dl>
364
365<h2>\anchor api-msg-pb Packet beginning message</h2>
366
367A <strong><em>packet beginning message</em></strong> indicates the
368beginning of a \bt_pkt.
369
370A 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".
373
374For a given packet, there can be only one packet beginning message.
375
376Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
377beginning message can only occur after the \bt_sb_msg and before the
378\bt_se_msg.
379
380To create a packet beginning message for a given stream, use:
381
382<dl>
383 <dt>
384 If, for this stream's class,
385 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
386 </dt>
387 <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
388
389 <dt>
390 If, for this stream's class, packets do not have a beginning default
391 clock snapshot
392 </dt>
393 <dd>bt_message_packet_beginning_create()</dd>
394</dl>
395
396A packet beginning message has the following properties:
397
398<dl>
399 <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
400 <dd>
401 \bt_c_pkt of which the message indicates the beginning.
402
403 You cannot change the packet once the message is created.
404
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().
408 </dd>
409
410 <dt>
411 \anchor api-msg-pb-prop-cs
412 \bt_dt_opt Default \bt_cs
413 </dt>
414 <dd>
415 Snapshot of the message's \bt_stream's default clock when the
416 packet begins.
417
418 A packet beginning message has a default clock snapshot if:
419
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".
422
423 - For its stream's class,
424 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
425
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.
429
430 Borrow a packet beginning message's default clock snapshot with
431 bt_message_packet_beginning_borrow_default_clock_snapshot_const().
432 </dd>
433</dl>
434
435<h2>\anchor api-msg-pe Packet end message</h2>
436
437A <strong><em>packet end message</em></strong> indicates the
438end of a \bt_pkt.
439
440A 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".
443
444For a given packet, there can be only one packet end message.
445
446Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
447end message can only occur:
448
449- After the \bt_sb_msg and before the \bt_se_msg.
450- After a \bt_pb_msg for the same packet.
451
452To create a packet end message for a given stream, use:
453
454<dl>
455 <dt>
456 If, for this stream's class,
457 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
458 </dt>
459 <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
460
461 <dt>
462 If, for this stream's class, packets do not have an end default
463 clock snapshot
464 </dt>
465 <dd>bt_message_packet_end_create()</dd>
466</dl>
467
468A packet end message has the following properties:
469
470<dl>
471 <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
472 <dd>
473 \bt_c_pkt of which the message indicates the end.
474
475 You cannot change the packet once the message is created.
476
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().
480 </dd>
481
482 <dt>
483 \anchor api-msg-pe-prop-cs
484 \bt_dt_opt Default \bt_cs
485 </dt>
486 <dd>
487 Snapshot of the message's \bt_stream's default clock when the
488 packet ends.
489
490 A packet end message has a default clock snapshot if:
491
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".
494
495 - For its stream's class,
496 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
497
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.
501
502 Borrow a packet end message's default clock snapshot with
503 bt_message_packet_end_borrow_default_clock_snapshot_const().
504 </dd>
505</dl>
506
507<h2>\anchor api-msg-disc-ev Discarded events message</h2>
508
509A <strong><em>discarded events message</em></strong> indicates that
510events were discarded at <em>tracing time</em>. It does \em not indicate
511that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
512
513A 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".
516
517Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
518events message can only occur after the \bt_sb_msg and before the
519\bt_se_msg.
520
521To create a discarded events message for a given stream, use:
522
523<dl>
524 <dt>
525 If, for this stream's class,
526 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
527 </dt>
528 <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
529
530 <dt>
531 If, for this stream's class, discarded events do not have default
532 clock snapshots
533 </dt>
534 <dd>bt_message_discarded_events_create()</dd>
535</dl>
536
537A discarded events message has the following properties:
538
539<dl>
540 <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
541 <dd>
542 \bt_c_stream into which events were discarded.
543
544 You cannot change the stream once the message is created.
545
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().
549 </dd>
550
551 <dt>
552 \anchor api-msg-disc-ev-prop-cs-beg
553 \bt_dt_opt Beginning default \bt_cs
554 </dt>
555 <dd>
556 Snapshot of the message's \bt_stream's default clock which indicates
557 the beginning of the discarded events time range.
558
559 A discarded events message has a beginning default clock snapshot
560 if:
561
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".
564
565 - For its stream's class,
566 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
567
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
571 message.
572
573 Borrow a discarded events message's beginning default clock snapshot
574 with
575 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
576 </dd>
577
578 <dt>
579 \anchor api-msg-disc-ev-prop-cs-end
580 \bt_dt_opt End default \bt_cs
581 </dt>
582 <dd>
583 Snapshot of the message's \bt_stream's default clock which indicates
584 the end of the discarded events time range.
585
586 A discarded events message has an end default clock snapshot if:
587
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".
590
591 - For its stream's class,
592 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
593
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.
598
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.
602
603 Borrow a discarded events message's end default clock snapshot with
604 bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
605 </dd>
606
607 <dt>
608 \anchor api-msg-disc-ev-prop-count
609 \bt_dt_opt Discarded event count
610 </dt>
611 <dd>
612 Exact number of discarded events.
613
614 If this property is missing, then the number of discarded events
615 is at least one.
616
617 Use bt_message_discarded_events_set_count() and
618 bt_message_discarded_events_get_count().
619 </dd>
620</dl>
621
622<h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
623
624A <strong><em>discarded packets message</em></strong> indicates that
625packets were discarded at <em>tracing time</em>. It does \em not
626indicate that whole packets were dropped during a trace processing
627\bt_graph run.
628
629A 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".
632
633Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
634packets message can only occur:
635
636- After the \bt_sb_msg.
637- Before the \bt_se_msg.
638- One of:
639 - Before any \bt_pb_msg.
640 - After any \bt_pe_msg.
641 - Between a packet end and a packet beginning message.
642
643To create a discarded packets message for a given stream, use:
644
645<dl>
646 <dt>
647 If, for this stream's class,
648 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
649 </dt>
650 <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
651
652 <dt>
653 If, for this stream's class, discarded packets do not have default
654 clock snapshots
655 </dt>
656 <dd>bt_message_discarded_packets_create()</dd>
657</dl>
658
659A discarded packets message has the following properties:
660
661<dl>
662 <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
663 <dd>
664 \bt_c_stream into which packets were discarded.
665
666 You cannot change the stream once the message is created.
667
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().
671 </dd>
672
673 <dt>
674 \anchor api-msg-disc-pkt-prop-cs-beg
675 \bt_dt_opt Beginning default \bt_cs
676 </dt>
677 <dd>
678 Snapshot of the message's \bt_stream's default clock which indicates
679 the beginning of the discarded packets time range.
680
681 A discarded packets message has a beginning default clock snapshot
682 if:
683
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".
686
687 - For its stream's class,
688 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
689
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
693 message.
694
695 Borrow a discarded packets message's beginning default clock snapshot
696 with
697 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
698 </dd>
699
700 <dt>
701 \anchor api-msg-disc-pkt-prop-cs-end
702 \bt_dt_opt End default \bt_cs
703 </dt>
704 <dd>
705 Snapshot of the message's \bt_stream's default clock which indicates
706 the end of the discarded packets time range.
707
708 A discarded packets message has an end default clock snapshot if:
709
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".
712
713 - For its stream's class,
714 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
715
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.
720
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
724 message.
725
726 Borrow a discarded packets message's end default clock snapshot with
727 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
728 </dd>
729
730 <dt>
731 \anchor api-msg-disc-pkt-prop-count
732 \bt_dt_opt Discarded packet count
733 </dt>
734 <dd>
735 Exact number of discarded packets.
736
737 If this property is missing, then the number of discarded packets
738 is at least one.
739
740 Use bt_message_discarded_packets_set_count() and
741 bt_message_discarded_packets_get_count().
742 </dd>
743</dl>
744
745<h2>\anchor api-msg-inac Message iterator inactivity</h2>
746
747A <strong><em>message iterator inactivity message</em></strong>
748indicates that, within the \ref api-msg-seq "message sequence" of a
749given \bt_msg_iter, there's no messages since the last message (if any)
750until a given point in time.
751
752A message iterator inactivity message is the only type of message that's
753not related to a \bt_stream: it targets the whole message sequence of a
754message iterator, and can occur at any position within the sequence.
755
756This message is mostly significant for real-time message iterators: if a
757message iterator A indicates that there's no messages until a given
758point in time T, then a downstream filter message iterator B which
759relies on multiple upstream message iterators does not have to wait for
760new messages from A until T.
761
762In other words, a message iterator inactivity message can help
763downstream message iterators or \bt_p_sink_comp <em>progress</em>.
764
765Create a message iterator inactivity message with
766bt_message_message_iterator_inactivity_create(). You must pass a
767\bt_clock_cls and the value of a fictitious (clock) instance to this
768function so that it creates a \bt_cs.
769
770A message iterator inactivity message has the following property:
771
772<dl>
773 <dt>
774 \anchor api-msg-inac-prop-cs
775 \bt_dt_opt \bt_c_cs
776 </dt>
777 <dd>
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".
781
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.
785
786 Borrow a message iterator inactivity message's clock snapshot
787 with
788 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
789 </dd>
790</dl>
791
792<h1>\anchor api-msg-mip Message Interchange Protocol</h1>
793
794The <em>Message Interchange Protocol</em> (MIP) is the system of rules
795used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
796trace processing graph.
797
798The MIP covers everything related to messages and what they contain, as
799well as how they are ordered within the \ref api-msg-seq "sequence" that
800a message iterator produces.
801
802For example:
803
804- A valid message sequence for a given \bt_stream starts with a
805 \bt_sb_msg and ends with a \bt_se_msg.
806
807- The maximum
808 \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
1eca514c 809 is [0,&nbsp;2<sup>64</sup>&nbsp;−&nbsp;1].
43c59509
PP
810
811- The available message types are stream beginning and end, event,
812 packet beginning and end, discarded events and packets, and message
813 iterator inactivity.
814
815The MIP has a version which is a single major number, independent from
816the \bt_name project's version. As of \bt_name_version_min_maj, the only
817available MIP version is 0.
818
819If what the MIP covers changes in a breaking or semantical way in the
820future, the MIP and \bt_name's minor versions will be bumped.
821
822When you create a trace processing \bt_graph with bt_graph_create(), you
823must 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
825version with bt_self_component_get_graph_mip_version() and behave
826accordingly. In other words, if the configured MIP version is 0, then a
827component cannot use features introduced by MIP version&nbsp;1. For
828example, should the project introduce a new type of \bt_fc, the MIP
829version would be bumped.
830
831A component which cannot honor a given MIP can fail at
832initialization time, making the corresponding
833<code>bt_graph_add_*_component*()</code> call fail too. To avoid any
834surprise, you can create a \bt_comp_descr_set with descriptors of the
835components you intend to add to a trace processing graph and call
836bt_get_greatest_operative_mip_version() to get the greatest (most
837recent) MIP version you can use.
838
839To get the library's latest MIP version, use
840bt_get_maximal_mip_version().
841
842The ultimate goal of the MIP version feature is for the \bt_name project
843to be able to introduce new features or even major breaking changes
844without breaking existing \bt_p_comp_cls. This is especially important
845considering that \bt_name supports \bt_p_plugin written by different
846authors. Of course one of the project's objectives is to bump the MIP
847version as rarely as possible. When it is required, though, it's a
848welcome tool to make the project evolve gracefully.
849
850The Message Interchange Protocol has no dedicated documentation as this
851very message module (and its submodules, like \ref api-tir)
852documentation is enough. You can consider that all the
853functions of the message and trace IR objects have an implicit MIP
854version \ref api-fund-pre-post "precondition". When a given
855function documentation does not explicitly document a MIP version
856precondition, it means that the effective MIP version has no effect on
857said function's behaviour.
858
859<h2>\anchor api-msg-seq Message sequence rules</h2>
860
861The purpose of a \bt_msg_iter is to iterate a sequence of messages.
862
863Those messages can be related to different \bt_p_stream:
864
865@image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
866
867However, for such a message sequence, the current \bt_mip
868(version \bt_max_mip_version) dictates that:
869
870<ul>
871 <li>
872 For a given \bt_stream:
873
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
880 packet end message.
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.
885
886 The rules above can be summarized by the following regular
887 expressions:
888
889 <dl>
890 <dt>Without packets</dt>
891 <dd>
892 @code{.unparsed}
893 SB (E | DE)* SE
894 @endcode
895 </dd>
896
897 <dt>With packets</dt>
898 <dd>
899 @code{.unparsed}
900 SB ((PB (E | DE)* PE) | DE | DP)* SE
901 @endcode
902 </dd>
903 </dl>
904
905 With this alphabet:
906
907 <dl>
908 <dt>SB</dt>
909 <dd>\bt_c_sb_msg</dd>
910
911 <dt>SE</dt>
912 <dd>\bt_c_se_msg</dd>
913
914 <dt>E</dt>
915 <dd>\bt_c_ev_msg</dd>
916
917 <dt>PB</dt>
918 <dd>\bt_c_pb_msg</dd>
919
920 <dt>PE</dt>
921 <dd>\bt_c_pe_msg</dd>
922
923 <dt>DE</dt>
924 <dd>\bt_c_disc_ev_msg</dd>
925
926 <dt>DP</dt>
927 <dd>\bt_c_disc_pkt_msg</dd>
928 </dl>
929 <li>
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.
933
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.
936 <li>
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").
940</ul>
941*/
942
943/*! @{ */
944
945/*!
946@name Type
947@{
948
949@typedef struct bt_message bt_message;
950
951@brief
952 Message.
953
954@}
955*/
956
957/*!
958@name Type query
959@{
960*/
961
962/*!
963@brief
964 Message type enumerators.
965*/
966typedef enum bt_message_type {
967 /*!
968 @brief
969 \bt_c_sb_msg.
970 */
971 BT_MESSAGE_TYPE_STREAM_BEGINNING = 1 << 0,
972
973 /*!
974 @brief
975 \bt_c_se_msg.
976 */
977 BT_MESSAGE_TYPE_STREAM_END = 1 << 1,
978
979 /*!
980 @brief
981 \bt_c_ev_msg.
982 */
983 BT_MESSAGE_TYPE_EVENT = 1 << 2,
984
985 /*!
986 @brief
987 \bt_c_pb_msg.
988 */
989 BT_MESSAGE_TYPE_PACKET_BEGINNING = 1 << 3,
990
991 /*!
992 @brief
993 \bt_c_pe_msg.
994 */
995 BT_MESSAGE_TYPE_PACKET_END = 1 << 4,
996
997 /*!
998 @brief
999 \bt_c_disc_ev_msg.
1000 */
1001 BT_MESSAGE_TYPE_DISCARDED_EVENTS = 1 << 5,
1002
1003 /*!
1004 @brief
1005 \bt_c_disc_pkt_msg.
1006 */
1007 BT_MESSAGE_TYPE_DISCARDED_PACKETS = 1 << 6,
1008
1009 /*!
1010 @brief
1011 \bt_c_inac_msg.
1012 */
1013 BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY = 1 << 7,
1014} bt_message_type;
1015
1016/*!
1017@brief
1018 Returns the type enumerator of the message \bt_p{message}.
1019
1020@param[in] message
1021 Message of which to get the type enumerator
1022
1023@returns
1024 Type enumerator of \bt_p{message}.
1025
1026@bt_pre_not_null{message}
1027*/
4c81a2b7
PP
1028extern bt_message_type bt_message_get_type(const bt_message *message)
1029 __BT_NOEXCEPT;
43c59509
PP
1030
1031/*! @} */
1032
1033/*!
1034@name Common stream message
1035@{
1036*/
1037
1038/*!
1039@brief
1040 Return type of
1041 bt_message_stream_beginning_borrow_default_clock_snapshot_const()
1042 and
1043 bt_message_stream_end_borrow_default_clock_snapshot_const().
1044*/
1045typedef enum bt_message_stream_clock_snapshot_state {
1046 /*!
1047 @brief
1048 Known \bt_cs.
1049 */
1050 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN = 1,
1051
1052 /*!
1053 @brief
1054 Unknown (no) \bt_cs.
1055 */
1056 BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN = 0,
1057} bt_message_stream_clock_snapshot_state;
1058
1059/*! @} */
1060
1061/*!
1062@name Stream beginning message
1063@{
1064*/
1065
1066/*!
1067@brief
1068 Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
1069 \bt_msg_iter \bt_p{self_message_iterator}.
1070
1071On success, the returned stream beginning message has the following
1072property values:
1073
1074<table>
1075 <tr>
1076 <th>Property
1077 <th>Value
1078 <tr>
1079 <td>\ref api-msg-sb-prop-stream "Stream"
1080 <td>\bt_p{stream}
1081 <tr>
1082 <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
1083 <td>\em None
1084</table>
1085
1086@param[in] self_message_iterator
1087 Self message iterator from which to create the stream beginning
1088 message.
1089@param[in] stream
1090 Stream of which the message to create indicates the beginning.
1091
1092@returns
1093 New stream beginning message reference, or \c NULL on memory error.
1094
1095@bt_pre_not_null{self_message_iterator}
1096@bt_pre_not_null{stream}
1097
1098@bt_post_success_frozen{stream}
1099*/
1100extern
1101bt_message *bt_message_stream_beginning_create(
1102 bt_self_message_iterator *self_message_iterator,
4c81a2b7 1103 const bt_stream *stream) __BT_NOEXCEPT;
43c59509
PP
1104
1105/*!
1106@brief
1107 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
1108
1109See the \ref api-msg-sb-prop-stream "stream" property.
1110
1111@param[in] message
1112 Stream beginning message from which to borrow the stream.
1113
1114@returns
1115 @parblock
1116 \em Borrowed reference of the stream of \bt_p{message}.
1117
1118 The returned pointer remains valid as long as \bt_p{message} exists.
1119 @endparblock
1120
1121@bt_pre_not_null{message}
1122@bt_pre_is_sb_msg{message}
1123
1124@sa bt_message_stream_beginning_borrow_stream_const() &mdash;
1125 \c const version of this function.
1126*/
1127extern bt_stream *bt_message_stream_beginning_borrow_stream(
4c81a2b7 1128 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1129
1130/*!
1131@brief
1132 Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
1133 (\c const version).
1134
1135See bt_message_stream_beginning_borrow_stream().
1136*/
1137extern const bt_stream *bt_message_stream_beginning_borrow_stream_const(
4c81a2b7 1138 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1139
1140/*!
1141@brief
1142 Sets the value, in clock cycles, of the default \bt_cs of the
1143 \bt_sb_msg \bt_p{message} to \bt_p{value}.
1144
1145See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1146
1147@param[in] message
1148 Stream beginning message of which to set the default clock snapshot
1149 value to \bt_p{value}.
1150@param[in] value
1151 New value (clock cycles) of the default clock snapshot of
1152 \bt_p{message}.
1153
1154@bt_pre_not_null{message}
1155@bt_pre_hot{message}
1156@bt_pre_is_sb_msg{message}
1157@pre
1158 The \bt_stream_cls of \bt_p{message} has a
1159 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1160
1161@sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() &mdash;
1162 Borrows the default clock snapshot of a stream beginning message.
1163*/
1164extern
1165void bt_message_stream_beginning_set_default_clock_snapshot(
4c81a2b7 1166 bt_message *message, uint64_t value) __BT_NOEXCEPT;
43c59509
PP
1167
1168/*!
1169@brief
1170 Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
1171
1172See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
1173
1174@param[in] message
1175 Stream beginning message from which to borrow the default clock
1176 snapshot.
1177@param[out] clock_snapshot
1178 <strong>If this function returns
1179 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1180 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1181 clock snapshot of \bt_p{message}.
1182
1183@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1184 The default clock snapshot of \bt_p{message} is known and returned
1185 as \bt_p{*clock_snapshot}.
1186@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1187 \bt_p{message} has no default clock snapshot: its time is unknown.
1188
1189@bt_pre_not_null{message}
1190@bt_pre_is_sb_msg{message}
1191@pre
1192 The \bt_stream_cls of \bt_p{message} has a
1193 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1194@bt_pre_not_null{clock_snapshot}
1195
1196@sa bt_message_stream_beginning_set_default_clock_snapshot() &mdash;
1197 Sets the default clock snapshot of a stream beginning message.
1198*/
1199extern bt_message_stream_clock_snapshot_state
1200bt_message_stream_beginning_borrow_default_clock_snapshot_const(
1201 const bt_message *message,
4c81a2b7 1202 const bt_clock_snapshot **clock_snapshot) __BT_NOEXCEPT;
43c59509
PP
1203
1204/*!
1205@brief
1206 Borrows the default \bt_clock_cls of the \bt_stream_cls
1207 of the \bt_sb_msg \bt_p{message}.
1208
1209See the stream class's
1210\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1211property.
1212
1213This is a helper which is equivalent to
1214
1215@code
1216bt_stream_class_borrow_default_clock_class_const(
1217 bt_stream_borrow_class_const(
1218 bt_message_stream_beginning_borrow_stream_const(message)))
1219@endcode
1220
1221@param[in] message
1222 Stream beginning message from which to borrow its stream's class's
1223 default clock class.
1224
1225@returns
1226 \em Borrowed reference of the default clock class of
1227 the stream class of \bt_p{message}, or \c NULL if none.
1228
1229@bt_pre_not_null{message}
1230@bt_pre_is_sb_msg{message}
1231*/
1232extern const bt_clock_class *
1233bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
4c81a2b7 1234 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1235
1236/*! @} */
1237
1238/*!
1239@name Stream end message
1240@{
1241*/
1242
1243/*!
1244@brief
1245 Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
1246 \bt_msg_iter \bt_p{self_message_iterator}.
1247
1248On success, the returned stream end message has the following
1249property values:
1250
1251<table>
1252 <tr>
1253 <th>Property
1254 <th>Value
1255 <tr>
1256 <td>\ref api-msg-se-prop-stream "Stream"
1257 <td>\bt_p{stream}
1258 <tr>
1259 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1260 <td>\em None
1261</table>
1262
1263@param[in] self_message_iterator
1264 Self message iterator from which to create the stream end
1265 message.
1266@param[in] stream
1267 Stream of which the message to create indicates the end.
1268
1269@returns
1270 New stream end message reference, or \c NULL on memory error.
1271
1272@bt_pre_not_null{self_message_iterator}
1273@bt_pre_not_null{stream}
1274
1275@bt_post_success_frozen{stream}
1276*/
1277extern
1278bt_message *bt_message_stream_end_create(
1279 bt_self_message_iterator *self_message_iterator,
4c81a2b7 1280 const bt_stream *stream) __BT_NOEXCEPT;
43c59509
PP
1281
1282/*!
1283@brief
1284 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
1285
1286See the \ref api-msg-se-prop-stream "stream" property.
1287
1288@param[in] message
1289 Stream end message from which to borrow the stream.
1290
1291@returns
1292 @parblock
1293 \em Borrowed reference of the stream of \bt_p{message}.
1294
1295 The returned pointer remains valid as long as \bt_p{message} exists.
1296 @endparblock
1297
1298@bt_pre_not_null{message}
1299@bt_pre_is_se_msg{message}
1300
1301@sa bt_message_stream_end_borrow_stream_const() &mdash;
1302 \c const version of this function.
1303*/
1304extern bt_stream *bt_message_stream_end_borrow_stream(
4c81a2b7 1305 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1306
1307/*!
1308@brief
1309 Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
1310 (\c const version).
1311
1312See bt_message_stream_end_borrow_stream().
1313*/
1314extern const bt_stream *bt_message_stream_end_borrow_stream_const(
4c81a2b7 1315 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1316
1317/*!
1318@brief
1319 Sets the value, in clock cycles, of the default \bt_cs of the
1320 \bt_se_msg \bt_p{message} to \bt_p{value}.
1321
1322See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1323
1324@param[in] message
1325 Stream end message of which to set the default clock snapshot
1326 value to \bt_p{value}.
1327@param[in] value
1328 New value (clock cycles) of the default clock snapshot of
1329 \bt_p{message}.
1330
1331@bt_pre_not_null{message}
1332@bt_pre_hot{message}
1333@bt_pre_is_se_msg{message}
1334@pre
1335 The \bt_stream_cls of \bt_p{message} has a
1336 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1337
1338@sa bt_message_stream_end_borrow_default_clock_snapshot_const() &mdash;
1339 Borrows the default clock snapshot of a stream end message.
1340*/
1341extern
1342void bt_message_stream_end_set_default_clock_snapshot(
4c81a2b7 1343 bt_message *message, uint64_t value) __BT_NOEXCEPT;
43c59509
PP
1344
1345/*!
1346@brief
1347 Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
1348
1349See the \ref api-msg-se-prop-cs "default clock snapshot" property.
1350
1351@param[in] message
1352 Stream end message from which to borrow the default clock
1353 snapshot.
1354@param[out] clock_snapshot
1355 <strong>If this function returns
1356 #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
1357 \bt_p{*clock_snapshot} is a \em borrowed reference of the default
1358 clock snapshot of \bt_p{message}.
1359
1360@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
1361 The default clock snapshot of \bt_p{message} is known and returned
1362 as \bt_p{*clock_snapshot}.
1363@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
1364 \bt_p{message} has no default clock snapshot: its time is unknown.
1365
1366@bt_pre_not_null{message}
1367@bt_pre_is_se_msg{message}
1368@pre
1369 The \bt_stream_cls of \bt_p{message} has a
1370 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1371@bt_pre_not_null{clock_snapshot}
1372
1373@sa bt_message_stream_end_set_default_clock_snapshot() &mdash;
1374 Sets the default clock snapshot of a stream end message.
1375*/
1376extern bt_message_stream_clock_snapshot_state
1377bt_message_stream_end_borrow_default_clock_snapshot_const(
1378 const bt_message *message,
4c81a2b7 1379 const bt_clock_snapshot **clock_snapshot) __BT_NOEXCEPT;
43c59509
PP
1380
1381/*!
1382@brief
1383 Borrows the default \bt_clock_cls of the \bt_stream_cls
1384 of the \bt_se_msg \bt_p{message}.
1385
1386See the stream class's
1387\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1388property.
1389
1390This is a helper which is equivalent to
1391
1392@code
1393bt_stream_class_borrow_default_clock_class_const(
1394 bt_stream_borrow_class_const(
1395 bt_message_stream_end_borrow_stream_const(message)))
1396@endcode
1397
1398@param[in] message
1399 Stream end message from which to borrow its stream's class's
1400 default clock class.
1401
1402@returns
1403 \em Borrowed reference of the default clock class of
1404 the stream class of \bt_p{message}, or \c NULL if none.
1405
1406@bt_pre_not_null{message}
1407@bt_pre_is_se_msg{message}
1408*/
1409extern const bt_clock_class *
1410bt_message_stream_end_borrow_stream_class_default_clock_class_const(
4c81a2b7 1411 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1412
1413/*! @} */
1414
1415/*!
1416@name Event message
1417@{
1418*/
1419
1420/*!
1421@brief
1422 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1423 \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
1424 \bt_msg_iter \bt_p{self_message_iterator}.
1425
1426@attention
1427 @parblock
1428 Only use this function if
1429
1430 @code
1431 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1432 @endcode
1433
1434 returns #BT_FALSE and
1435
1436 @code
1437 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1438 @endcode
1439
1440 returns \c NULL.
1441
1442 Otherwise, use
1443 bt_message_event_create_with_default_clock_snapshot(),
1444 bt_message_event_create_with_packet(), or
1445 bt_message_event_create_with_packet_and_default_clock_snapshot().
1446 @endparblock
1447
1448On success, the returned event message has the following property
1449values:
1450
1451<table>
1452 <tr>
1453 <th>Property
1454 <th>Value
1455 <tr>
1456 <td>\ref api-msg-ev-prop-ev "Event"
1457 <td>
1458 An instance (with \bt_p_field that are not set) of
1459 \bt_p{event_class}.
1460 <tr>
1461 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1462 <td>\em None
1463</table>
1464
1465@param[in] self_message_iterator
1466 Self message iterator from which to create the event message.
1467@param[in] event_class
1468 Class of the \bt_ev of the message to create.
1469@param[in] stream
1470 Stream conceptually containing the event of the message to create.
1471
1472@returns
1473 New event message reference, or \c NULL on memory error.
1474
1475@bt_pre_not_null{self_message_iterator}
1476@pre
1477 The \bt_stream_cls of \bt_p{event_class} is also the class of
1478 \bt_p{stream}, that is,
1479 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1480 and
1481 <code>bt_stream_borrow_class_const(stream)</code> have the
1482 same value.
1483@bt_pre_not_null{stream}
1484@pre
1485 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1486 returns #BT_FALSE.
1487@pre
1488 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1489 returns \c NULL.
1490
1491@bt_post_success_frozen{event_class}
1492@bt_post_success_frozen{stream}
1493*/
1494extern
1495bt_message *bt_message_event_create(
1496 bt_self_message_iterator *self_message_iterator,
1497 const bt_event_class *event_class,
4c81a2b7 1498 const bt_stream *stream) __BT_NOEXCEPT;
43c59509
PP
1499
1500/*!
1501@brief
1502 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1503 \bt_p{event_class} and a default \bt_cs with the value
1504 \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
1505 the \bt_msg_iter \bt_p{self_message_iterator}.
1506
1507@attention
1508 @parblock
1509 Only use this function if
1510
1511 @code
1512 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
1513 @endcode
1514
1515 returns #BT_FALSE and
1516
1517 @code
1518 bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
1519 @endcode
1520
1521 does \em not return \c NULL.
1522
1523 Otherwise, use
1524 bt_message_event_create(),
1525 bt_message_event_create_with_packet(), or
1526 bt_message_event_create_with_packet_and_default_clock_snapshot().
1527 @endparblock
1528
1529On success, the returned event message has the following property
1530values:
1531
1532<table>
1533 <tr>
1534 <th>Property
1535 <th>Value
1536 <tr>
1537 <td>\ref api-msg-ev-prop-ev "Event"
1538 <td>
1539 An instance (with \bt_p_field that are not set) of
1540 \bt_p{event_class}.
1541 <tr>
1542 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1543 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1544</table>
1545
1546@param[in] self_message_iterator
1547 Self message iterator from which to create the event message.
1548@param[in] event_class
1549 Class of the \bt_ev of the message to create.
1550@param[in] stream
1551 Stream conceptually containing the event of the message to create.
1552@param[in] clock_snapshot_value
1553 Value (clock cycles) of the default clock snapshot of
1554 \bt_p{message}.
1555
1556@returns
1557 New event message reference, or \c NULL on memory error.
1558
1559@bt_pre_not_null{self_message_iterator}
1560@pre
1561 The \bt_stream_cls of \bt_p{event_class} is also the class of
1562 \bt_p{stream}, that is,
1563 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1564 and
1565 <code>bt_stream_borrow_class_const(stream)</code> have the
1566 same value.
1567@bt_pre_not_null{stream}
1568@pre
1569 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
1570 returns #BT_FALSE.
1571@pre
1572 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
1573 does \em not return \c NULL.
1574
1575@bt_post_success_frozen{event_class}
1576@bt_post_success_frozen{stream}
1577*/
1578extern
1579bt_message *bt_message_event_create_with_default_clock_snapshot(
1580 bt_self_message_iterator *self_message_iterator,
1581 const bt_event_class *event_class,
4c81a2b7
PP
1582 const bt_stream *stream, uint64_t clock_snapshot_value)
1583 __BT_NOEXCEPT;
43c59509
PP
1584
1585/*!
1586@brief
1587 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1588 \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
1589 \bt_msg_iter \bt_p{self_message_iterator}.
1590
1591@attention
1592 @parblock
1593 Only use this function if
1594
1595 @code
1596 bt_stream_class_supports_packets(
1597 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1598 @endcode
1599
1600 returns #BT_TRUE and
1601
1602 @code
1603 bt_stream_class_borrow_default_clock_class_const(
1604 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1605 @endcode
1606
1607 returns \c NULL.
1608
1609 Otherwise, use
1610 bt_message_event_create(),
1611 bt_message_event_create_with_default_clock_snapshot(), or
1612 bt_message_event_create_with_packet_and_default_clock_snapshot().
1613 @endparblock
1614
1615On success, the returned event message has the following property
1616values:
1617
1618<table>
1619 <tr>
1620 <th>Property
1621 <th>Value
1622 <tr>
1623 <td>\ref api-msg-ev-prop-ev "Event"
1624 <td>
1625 An instance (with \bt_p_field that are not set) of
1626 \bt_p{event_class}.
1627 <tr>
1628 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1629 <td>\em None
1630</table>
1631
1632@param[in] self_message_iterator
1633 Self message iterator from which to create the event message.
1634@param[in] event_class
1635 Class of the \bt_ev of the message to create.
1636@param[in] packet
1637 Packet conceptually containing the event of the message to create.
1638
1639@returns
1640 New event message reference, or \c NULL on memory error.
1641
1642@bt_pre_not_null{self_message_iterator}
1643@pre
1644 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1645 \bt_p{packet}, that is,
1646 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1647 and
1648 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1649 have the same value.
1650@bt_pre_not_null{packet}
1651@pre
1652 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1653 returns #BT_TRUE.
1654@pre
1655 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1656 returns \c NULL.
1657@pre
1658 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1659 any, and all its contained \bt_p_field, recursively, are set.
1660
1661@bt_post_success_frozen{event_class}
1662@bt_post_success_frozen{packet}
1663*/
1664extern
1665bt_message *bt_message_event_create_with_packet(
1666 bt_self_message_iterator *self_message_iterator,
1667 const bt_event_class *event_class,
4c81a2b7 1668 const bt_packet *packet) __BT_NOEXCEPT;
43c59509
PP
1669
1670/*!
1671@brief
1672 Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
1673 \bt_p{event_class} and a default \bt_cs with the value
1674 \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
1675 the \bt_msg_iter \bt_p{self_message_iterator}.
1676
1677@attention
1678 @parblock
1679 Only use this function if
1680
1681 @code
1682 bt_stream_class_supports_packets(
1683 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1684 @endcode
1685
1686 returns #BT_TRUE and
1687
1688 @code
1689 bt_stream_class_borrow_default_clock_class_const(
1690 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1691 @endcode
1692
1693 does \em not return \c NULL.
1694
1695 Otherwise, use
1696 bt_message_event_create(),
1697 bt_message_event_create_with_default_clock_snapshot(), or
1698 bt_message_event_create_with_packet().
1699 @endparblock
1700
1701On success, the returned event message has the following property
1702values:
1703
1704<table>
1705 <tr>
1706 <th>Property
1707 <th>Value
1708 <tr>
1709 <td>\ref api-msg-ev-prop-ev "Event"
1710 <td>
1711 An instance (with \bt_p_field that are not set) of
1712 \bt_p{event_class}.
1713 <tr>
1714 <td>\ref api-msg-se-prop-cs "Default clock snapshot"
1715 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1716</table>
1717
1718@param[in] self_message_iterator
1719 Self message iterator from which to create the event message.
1720@param[in] event_class
1721 Class of the \bt_ev of the message to create.
1722@param[in] packet
1723 Packet conceptually containing the event of the message to create.
1724@param[in] clock_snapshot_value
1725 Value (clock cycles) of the default clock snapshot of
1726 \bt_p{message}.
1727
1728@returns
1729 New event message reference, or \c NULL on memory error.
1730
1731@bt_pre_not_null{self_message_iterator}
1732@pre
1733 The \bt_stream_cls of \bt_p{event_class} is also the stream class of
1734 \bt_p{packet}, that is,
1735 <code>bt_event_class_borrow_stream_class_const(event_class)</code>
1736 and
1737 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
1738 have the same value.
1739@bt_pre_not_null{packet}
1740@pre
1741 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1742 returns #BT_TRUE.
1743@pre
1744 <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
1745 does \em not return \c NULL.
1746@pre
1747 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1748 any, and all its contained \bt_p_field, recursively, are set.
1749
1750@bt_post_success_frozen{event_class}
1751@bt_post_success_frozen{stream}
1752*/
1753extern
1754bt_message *bt_message_event_create_with_packet_and_default_clock_snapshot(
1755 bt_self_message_iterator *self_message_iterator,
1756 const bt_event_class *event_class,
4c81a2b7
PP
1757 const bt_packet *packet, uint64_t clock_snapshot_value)
1758 __BT_NOEXCEPT;
43c59509
PP
1759
1760/*!
1761@brief
1762 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
1763
1764See the \ref api-msg-ev-prop-ev "event" property.
1765
1766@param[in] message
1767 Event message from which to borrow the event.
1768
1769@returns
1770 @parblock
1771 \em Borrowed reference of the event of \bt_p{message}.
1772
1773 The returned pointer remains valid as long as \bt_p{message} exists.
1774 @endparblock
1775
1776@bt_pre_not_null{message}
1777@bt_pre_is_ev_msg{message}
1778
1779@sa bt_message_event_borrow_event_const() &mdash;
1780 \c const version of this function.
1781*/
4c81a2b7
PP
1782extern bt_event *bt_message_event_borrow_event(bt_message *message)
1783 __BT_NOEXCEPT;
43c59509
PP
1784
1785/*!
1786@brief
1787 Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
1788 (\c const version).
1789
1790See bt_message_event_borrow_event().
1791*/
1792extern const bt_event *bt_message_event_borrow_event_const(
4c81a2b7 1793 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1794
1795/*!
1796@brief
1797 Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
1798
1799See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
1800
1801@param[in] message
1802 Event message from which to borrow the default clock snapshot.
1803
1804@returns
1805 Default clock snapshot of \bt_p{message}.
1806
1807@bt_pre_not_null{message}
1808@bt_pre_is_ev_msg{message}
1809@pre
1810 The \bt_stream_cls of \bt_p{message} has a
1811 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1812*/
1813extern const bt_clock_snapshot *
4c81a2b7
PP
1814bt_message_event_borrow_default_clock_snapshot_const(const bt_message *message)
1815 __BT_NOEXCEPT;
43c59509
PP
1816
1817/*!
1818@brief
1819 Borrows the default \bt_clock_cls of the \bt_stream_cls
1820 of the \bt_ev_msg \bt_p{message}.
1821
1822See the stream class's
1823\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1824property.
1825
1826This is a helper which is equivalent to
1827
1828@code
1829bt_stream_class_borrow_default_clock_class_const(
1830 bt_stream_borrow_class_const(
1831 bt_event_borrow_stream_const(
1832 bt_message_event_borrow_event_const(message))))
1833@endcode
1834
1835@param[in] message
1836 Event message from which to borrow its stream's class's
1837 default clock class.
1838
1839@returns
1840 \em Borrowed reference of the default clock class of
1841 the stream class of \bt_p{message}, or \c NULL if none.
1842
1843@bt_pre_not_null{message}
1844@bt_pre_is_ev_msg{message}
1845*/
1846extern const bt_clock_class *
1847bt_message_event_borrow_stream_class_default_clock_class_const(
4c81a2b7 1848 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
1849
1850/*! @} */
1851
1852/*!
1853@name Packet beginning message
1854@{
1855*/
1856
1857/*!
1858@brief
1859 Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
1860 \bt_msg_iter \bt_p{self_message_iterator}.
1861
1862@attention
1863 @parblock
1864 Only use this function if
1865
1866 @code
1867 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1868 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1869 @endcode
1870
1871 returns #BT_FALSE.
1872
1873 Otherwise, use
1874 bt_message_packet_beginning_create_with_default_clock_snapshot().
1875 @endparblock
1876
1877On success, the returned packet beginning message has the following
1878property values:
1879
1880<table>
1881 <tr>
1882 <th>Property
1883 <th>Value
1884 <tr>
1885 <td>\ref api-msg-pb-prop-pkt "Packet"
1886 <td>\bt_p{packet}
1887 <tr>
1888 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1889 <td>\em None
1890</table>
1891
1892@param[in] self_message_iterator
1893 Self message iterator from which to create the packet beginning
1894 message.
1895@param[in] packet
1896 Packet of which the message to create indicates the beginning.
1897
1898@returns
1899 New packet beginning message reference, or \c NULL on memory error.
1900
1901@bt_pre_not_null{self_message_iterator}
1902@bt_pre_not_null{packet}
1903@pre
1904 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1905 returns #BT_FALSE for
1906 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1907@pre
1908 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1909 any, and all its contained \bt_p_field, recursively, are set.
1910
1911@bt_post_success_frozen{packet}
1912*/
1913extern
1914bt_message *bt_message_packet_beginning_create(
1915 bt_self_message_iterator *self_message_iterator,
4c81a2b7 1916 const bt_packet *packet) __BT_NOEXCEPT;
43c59509
PP
1917
1918/*!
1919@brief
1920 Creates a \bt_pb_msg having a default \bt_cs with the value
1921 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
1922 \bt_msg_iter \bt_p{self_message_iterator}.
1923
1924@attention
1925 @parblock
1926 Only use this function if
1927
1928 @code
1929 bt_stream_class_packets_have_beginning_default_clock_snapshot(
1930 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
1931 @endcode
1932
1933 returns #BT_TRUE.
1934
1935 Otherwise, use
1936 bt_message_packet_beginning_create().
1937 @endparblock
1938
1939On success, the returned packet beginning message has the following
1940property values:
1941
1942<table>
1943 <tr>
1944 <th>Property
1945 <th>Value
1946 <tr>
1947 <td>\ref api-msg-pb-prop-pkt "Packet"
1948 <td>\bt_p{packet}
1949 <tr>
1950 <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
1951 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
1952</table>
1953
1954@param[in] self_message_iterator
1955 Self message iterator from which to create the packet beginning
1956 message.
1957@param[in] packet
1958 Packet of which the message to create indicates the beginning.
1959@param[in] clock_snapshot_value
1960 Value (clock cycles) of the default clock snapshot of
1961 \bt_p{message}.
1962
1963@returns
1964 New packet beginning message reference, or \c NULL on memory error.
1965
1966@bt_pre_not_null{self_message_iterator}
1967@bt_pre_not_null{packet}
1968@pre
1969 bt_stream_class_packets_have_beginning_default_clock_snapshot()
1970 returns #BT_TRUE for
1971 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
1972@pre
1973 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
1974 any, and all its contained \bt_p_field, recursively, are set.
1975
1976@bt_post_success_frozen{packet}
1977*/
1978extern
1979bt_message *bt_message_packet_beginning_create_with_default_clock_snapshot(
1980 bt_self_message_iterator *self_message_iterator,
4c81a2b7
PP
1981 const bt_packet *packet, uint64_t clock_snapshot_value)
1982 __BT_NOEXCEPT;
43c59509
PP
1983
1984/*!
1985@brief
1986 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
1987
1988See the \ref api-msg-pb-prop-pkt "packet" property.
1989
1990@param[in] message
1991 Packet beginning message from which to borrow the packet.
1992
1993@returns
1994 @parblock
1995 \em Borrowed reference of the packet of \bt_p{message}.
1996
1997 The returned pointer remains valid as long as \bt_p{message} exists.
1998 @endparblock
1999
2000@bt_pre_not_null{message}
2001@bt_pre_is_pb_msg{message}
2002
2003@sa bt_message_packet_beginning_borrow_packet_const() &mdash;
2004 \c const version of this function.
2005*/
2006extern bt_packet *bt_message_packet_beginning_borrow_packet(
4c81a2b7 2007 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2008
2009/*!
2010@brief
2011 Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
2012 (\c const version).
2013
2014See bt_message_packet_beginning_borrow_packet().
2015*/
2016extern const bt_packet *bt_message_packet_beginning_borrow_packet_const(
4c81a2b7 2017 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2018
2019/*!
2020@brief
2021 Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
2022
2023See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
2024
2025@param[in] message
2026 Packet beginning message from which to borrow the default clock
2027 snapshot.
2028
2029@returns
2030 Default clock snapshot of \bt_p{message}.
2031
2032@bt_pre_not_null{message}
2033@bt_pre_is_pb_msg{message}
2034@pre
2035 The packets of the \bt_stream_cls of \bt_p{message}
2036 \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
2037*/
2038extern const bt_clock_snapshot *
2039bt_message_packet_beginning_borrow_default_clock_snapshot_const(
4c81a2b7 2040 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2041
2042/*!
2043@brief
2044 Borrows the default \bt_clock_cls of the \bt_stream_cls
2045 of the \bt_pb_msg \bt_p{message}.
2046
2047See the stream class's
2048\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2049property.
2050
2051This is a helper which is equivalent to
2052
2053@code
2054bt_stream_class_borrow_default_clock_class_const(
2055 bt_stream_borrow_class_const(
2056 bt_packet_borrow_stream_const(
2057 bt_message_packet_beginning_borrow_packet_const(message))))
2058@endcode
2059
2060@param[in] message
2061 Packet beginning message from which to borrow its stream's class's
2062 default clock class.
2063
2064@returns
2065 \em Borrowed reference of the default clock class of
2066 the stream class of \bt_p{message}, or \c NULL if none.
2067
2068@bt_pre_not_null{message}
2069@bt_pre_is_pb_msg{message}
2070*/
2071extern const bt_clock_class *
2072bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
4c81a2b7 2073 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2074
2075/*! @} */
2076
2077/*!
2078@name Packet end message
2079@{
2080*/
2081
2082/*!
2083@brief
2084 Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
2085 \bt_msg_iter \bt_p{self_message_iterator}.
2086
2087@attention
2088 @parblock
2089 Only use this function if
2090
2091 @code
2092 bt_stream_class_packets_have_end_default_clock_snapshot(
2093 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2094 @endcode
2095
2096 returns #BT_FALSE.
2097
2098 Otherwise, use
2099 bt_message_packet_end_create_with_default_clock_snapshot().
2100 @endparblock
2101
2102On success, the returned packet end message has the following
2103property values:
2104
2105<table>
2106 <tr>
2107 <th>Property
2108 <th>Value
2109 <tr>
2110 <td>\ref api-msg-pe-prop-pkt "Packet"
2111 <td>\bt_p{packet}
2112 <tr>
2113 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2114 <td>\em None
2115</table>
2116
2117@param[in] self_message_iterator
2118 Self message iterator from which to create the packet end message.
2119@param[in] packet
2120 Packet of which the message to create indicates the end.
2121
2122@returns
2123 New packet end message reference, or \c NULL on memory error.
2124
2125@bt_pre_not_null{self_message_iterator}
2126@bt_pre_not_null{packet}
2127@pre
2128 bt_stream_class_packets_have_end_default_clock_snapshot()
2129 returns #BT_FALSE for
2130 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2131@pre
2132 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2133 any, and all its contained \bt_p_field, recursively, are set.
2134
2135@bt_post_success_frozen{packet}
2136*/
2137extern
2138bt_message *bt_message_packet_end_create(
2139 bt_self_message_iterator *self_message_iterator,
4c81a2b7 2140 const bt_packet *packet) __BT_NOEXCEPT;
43c59509
PP
2141
2142/*!
2143@brief
2144 Creates a \bt_pe_msg having a default \bt_cs with the value
2145 \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
2146 \bt_msg_iter \bt_p{self_message_iterator}.
2147
2148@attention
2149 @parblock
2150 Only use this function if
2151
2152 @code
2153 bt_stream_class_packets_have_end_default_clock_snapshot(
2154 bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
2155 @endcode
2156
2157 returns #BT_TRUE.
2158
2159 Otherwise, use
2160 bt_message_packet_end_create().
2161 @endparblock
2162
2163On success, the returned packet end message has the following
2164property values:
2165
2166<table>
2167 <tr>
2168 <th>Property
2169 <th>Value
2170 <tr>
2171 <td>\ref api-msg-pe-prop-pkt "Packet"
2172 <td>\bt_p{packet}
2173 <tr>
2174 <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
2175 <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
2176</table>
2177
2178@param[in] self_message_iterator
2179 Self message iterator from which to create the packet end
2180 message.
2181@param[in] packet
2182 Packet of which the message to create indicates the end.
2183@param[in] clock_snapshot_value
2184 Value (clock cycles) of the default clock snapshot of
2185 \bt_p{message}.
2186
2187@returns
2188 New packet end message reference, or \c NULL on memory error.
2189
2190@bt_pre_not_null{self_message_iterator}
2191@bt_pre_not_null{packet}
2192@pre
2193 bt_stream_class_packets_have_end_default_clock_snapshot()
2194 returns #BT_TRUE for
2195 <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
2196@pre
2197 The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
2198 any, and all its contained \bt_p_field, recursively, are set.
2199
2200@bt_post_success_frozen{packet}
2201*/
2202extern
2203bt_message *bt_message_packet_end_create_with_default_clock_snapshot(
2204 bt_self_message_iterator *self_message_iterator,
4c81a2b7
PP
2205 const bt_packet *packet, uint64_t clock_snapshot_value)
2206 __BT_NOEXCEPT;
43c59509
PP
2207
2208/*!
2209@brief
2210 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
2211
2212See the \ref api-msg-pe-prop-pkt "packet" property.
2213
2214@param[in] message
2215 Packet end message from which to borrow the packet.
2216
2217@returns
2218 @parblock
2219 \em Borrowed reference of the packet of \bt_p{message}.
2220
2221 The returned pointer remains valid as long as \bt_p{message} exists.
2222 @endparblock
2223
2224@bt_pre_not_null{message}
2225@bt_pre_is_pe_msg{message}
2226
2227@sa bt_message_packet_end_borrow_packet_const() &mdash;
2228 \c const version of this function.
2229*/
2230extern bt_packet *bt_message_packet_end_borrow_packet(
4c81a2b7 2231 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2232
2233/*!
2234@brief
2235 Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
2236 (\c const version).
2237
2238See bt_message_packet_end_borrow_packet().
2239*/
2240extern const bt_packet *bt_message_packet_end_borrow_packet_const(
4c81a2b7 2241 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2242
2243/*!
2244@brief
2245 Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
2246
2247See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
2248
2249@param[in] message
2250 Packet end message from which to borrow the default clock
2251 snapshot.
2252
2253@returns
2254 Default clock snapshot of \bt_p{message}.
2255
2256@bt_pre_not_null{message}
2257@bt_pre_is_pe_msg{message}
2258@pre
2259 The packets of the \bt_stream_cls of \bt_p{message}
2260 \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
2261*/
2262extern const bt_clock_snapshot *
2263bt_message_packet_end_borrow_default_clock_snapshot_const(
4c81a2b7 2264 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2265
2266/*!
2267@brief
2268 Borrows the default \bt_clock_cls of the \bt_stream_cls
2269 of the \bt_pe_msg \bt_p{message}.
2270
2271See the stream class's
2272\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2273property.
2274
2275This is a helper which is equivalent to
2276
2277@code
2278bt_stream_class_borrow_default_clock_class_const(
2279 bt_stream_borrow_class_const(
2280 bt_packet_borrow_stream_const(
2281 bt_message_packet_end_borrow_packet_const(message))))
2282@endcode
2283
2284@param[in] message
2285 Packet end message from which to borrow its stream's class's
2286 default clock class.
2287
2288@returns
2289 \em Borrowed reference of the default clock class of
2290 the stream class of \bt_p{message}, or \c NULL if none.
2291
2292@bt_pre_not_null{message}
2293@bt_pre_is_pe_msg{message}
2294*/
2295extern const bt_clock_class *
2296bt_message_packet_end_borrow_stream_class_default_clock_class_const(
4c81a2b7 2297 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2298
2299/*! @} */
2300
2301/*!
2302@name Discarded events message
2303@{
2304*/
2305
2306/*!
2307@brief
2308 Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
2309 \bt_msg_iter \bt_p{self_message_iterator}.
2310
2311@attention
2312 @parblock
2313 Only use this function if
2314
2315 @code
2316 bt_stream_class_discarded_events_have_default_clock_snapshots(
2317 bt_stream_borrow_class_const(stream))
2318 @endcode
2319
2320 returns #BT_FALSE.
2321
2322 Otherwise, use
2323 bt_message_discarded_events_create_with_default_clock_snapshots().
2324 @endparblock
2325
2326On success, the returned discarded events message has the following
2327property values:
2328
2329<table>
2330 <tr>
2331 <th>Property
2332 <th>Value
2333 <tr>
2334 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2335 <td>\bt_p{stream}
2336 <tr>
2337 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2338 <td>\em None
2339 <tr>
2340 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2341 <td>\em None
2342 <tr>
2343 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2344 <td>\em None
2345</table>
2346
2347@param[in] self_message_iterator
2348 Self message iterator from which to create the discarded events
2349 message.
2350@param[in] stream
2351 Stream from which the events were discarded.
2352
2353@returns
2354 New discarded events message reference, or \c NULL on memory error.
2355
2356@bt_pre_not_null{self_message_iterator}
2357@bt_pre_not_null{stream}
2358@pre
2359 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2360 returns #BT_FALSE.
2361
2362@bt_post_success_frozen{stream}
2363*/
2364extern bt_message *bt_message_discarded_events_create(
2365 bt_self_message_iterator *self_message_iterator,
4c81a2b7 2366 const bt_stream *stream) __BT_NOEXCEPT;
43c59509
PP
2367
2368/*!
2369@brief
2370 Creates a \bt_disc_ev_msg having the beginning and end default
2371 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2372 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2373 from the \bt_msg_iter \bt_p{self_message_iterator}.
2374
2375@attention
2376 @parblock
2377 Only use this function if
2378
2379 @code
2380 bt_stream_class_discarded_events_have_default_clock_snapshots(
2381 bt_stream_borrow_class_const(stream))
2382 @endcode
2383
2384 returns #BT_TRUE.
2385
2386 Otherwise, use
2387 bt_message_discarded_events_create().
2388 @endparblock
2389
2390On success, the returned discarded events message has the following
2391property values:
2392
2393<table>
2394 <tr>
2395 <th>Property
2396 <th>Value
2397 <tr>
2398 <td>\ref api-msg-disc-ev-prop-stream "Stream"
2399 <td>\bt_p{stream}
2400 <tr>
2401 <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
2402 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2403 <tr>
2404 <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
2405 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2406 <tr>
2407 <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
2408 <td>\em None
2409</table>
2410
2411@param[in] self_message_iterator
2412 Self message iterator from which to create the discarded events
2413 message.
2414@param[in] stream
2415 Stream from which the events were discarded.
2416@param[in] beginning_clock_snapshot_value
2417 Value (clock cycles) of the beginning default clock snapshot of
2418 \bt_p{message}.
2419@param[in] end_clock_snapshot_value
2420 Value (clock cycles) of the end default clock snapshot of
2421 \bt_p{message}.
2422
2423@returns
2424 New discarded events message reference, or \c NULL on memory error.
2425
2426@bt_pre_not_null{self_message_iterator}
2427@bt_pre_not_null{stream}
2428@pre
2429 <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2430 returns #BT_TRUE.
5d9ef4cb 2431 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
43c59509
PP
2432
2433@bt_post_success_frozen{stream}
2434*/
2435extern bt_message *bt_message_discarded_events_create_with_default_clock_snapshots(
2436 bt_self_message_iterator *self_message_iterator,
2437 const bt_stream *stream,
2438 uint64_t beginning_clock_snapshot_value,
4c81a2b7
PP
2439 uint64_t end_clock_snapshot_value)
2440 __BT_NOEXCEPT;
43c59509
PP
2441
2442/*!
2443@brief
2444 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
2445
2446See the \ref api-msg-disc-ev-prop-stream "stream" property.
2447
2448@param[in] message
2449 Discarded events message from which to borrow the stream.
2450
2451@returns
2452 @parblock
2453 \em Borrowed reference of the stream of \bt_p{message}.
2454
2455 The returned pointer remains valid as long as \bt_p{message} exists.
2456 @endparblock
2457
2458@bt_pre_not_null{message}
2459@bt_pre_is_disc_ev_msg{message}
2460
2461@sa bt_message_discarded_events_borrow_stream_const() &mdash;
2462 \c const version of this function.
2463*/
2464extern bt_stream *bt_message_discarded_events_borrow_stream(
4c81a2b7 2465 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2466
2467/*!
2468@brief
2469 Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
2470 (\c const version).
2471
2472See bt_message_discarded_events_borrow_stream().
2473*/
2474extern const bt_stream *
4c81a2b7
PP
2475bt_message_discarded_events_borrow_stream_const(const bt_message *message)
2476 __BT_NOEXCEPT;
43c59509
PP
2477
2478/*!
2479@brief
2480 Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
2481 \bt_p{message}.
2482
2483See the
2484\ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
2485property.
2486
2487@param[in] message
2488 Discarded events message from which to borrow the beginning default
2489 clock snapshot.
2490
2491@returns
2492 Beginning default clock snapshot of \bt_p{message}.
2493
2494@bt_pre_not_null{message}
2495@bt_pre_is_disc_ev_msg{message}
2496@pre
2497 The discarded packets messages of the \bt_stream_cls of
2498 \bt_p{message}
2499 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2500*/
2501extern const bt_clock_snapshot *
2502bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
4c81a2b7 2503 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2504
2505/*!
2506@brief
2507 Borrows the end default \bt_cs of the \bt_disc_ev_msg
2508 \bt_p{message}.
2509
2510See the
2511\ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
2512property.
2513
2514@param[in] message
2515 Discarded events message from which to borrow the end default clock
2516 snapshot.
2517
2518@returns
2519 End default clock snapshot of \bt_p{message}.
2520
2521@bt_pre_not_null{message}
2522@bt_pre_is_disc_ev_msg{message}
2523@pre
2524 The discarded packets messages of the \bt_stream_cls of
2525 \bt_p{message}
2526 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2527*/
2528extern const bt_clock_snapshot *
2529bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
4c81a2b7 2530 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2531
2532/*!
2533@brief
2534 Borrows the default \bt_clock_cls of the \bt_stream_cls
2535 of the \bt_disc_ev_msg \bt_p{message}.
2536
2537See the stream class's
2538\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2539property.
2540
2541This is a helper which is equivalent to
2542
2543@code
2544bt_stream_class_borrow_default_clock_class_const(
2545 bt_stream_borrow_class_const(
2546 bt_message_discarded_events_borrow_stream_const(message)))
2547@endcode
2548
2549@param[in] message
2550 Discarded events message from which to borrow its stream's class's
2551 default clock class.
2552
2553@returns
2554 \em Borrowed reference of the default clock class of
2555 the stream class of \bt_p{message}, or \c NULL if none.
2556
2557@bt_pre_not_null{message}
2558@bt_pre_is_disc_ev_msg{message}
2559*/
2560extern const bt_clock_class *
2561bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
4c81a2b7 2562 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2563
2564/*!
2565@brief
2566 Sets the number of discarded events of the \bt_disc_ev_msg
2567 \bt_p{message} to \bt_p{count}.
2568
2569See the \ref api-msg-disc-ev-prop-count "discarded event count"
2570property.
2571
2572@param[in] message
2573 Discarded events message of which to set the number of discarded
2574 events to \bt_p{count}.
2575@param[in] count
2576 New number of discarded events of \bt_p{message}.
2577
2578@bt_pre_not_null{message}
2579@bt_pre_hot{message}
2580@bt_pre_is_disc_ev_msg{message}
e5a41ca3
SM
2581@pre
2582 \bt_p{count} > 0
43c59509
PP
2583
2584@sa bt_message_discarded_events_get_count() &mdash;
2585 Returns the number of discarded events of a discarded events
2586 message.
2587*/
2588extern void bt_message_discarded_events_set_count(bt_message *message,
4c81a2b7 2589 uint64_t count) __BT_NOEXCEPT;
43c59509
PP
2590
2591/*!
2592@brief
2593 Returns the number of discarded events of the \bt_disc_ev_msg
2594 \bt_p{message}.
2595
2596See the \ref api-msg-disc-ev-prop-count "discarded event count"
2597property.
2598
2599@param[in] message
2600 Discarded events message of which to get the number of discarded
2601 events.
2602@param[out] count
2603 <strong>If this function returns
2604 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2605 the number of discarded events of \bt_p{message}.
2606
2607@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2608 The number of discarded events of \bt_p{message} is available.
2609@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2610 The number of discarded events of \bt_p{message} is not available.
2611
2612@bt_pre_not_null{message}
2613@bt_pre_is_disc_ev_msg{message}
2614@bt_pre_not_null{count}
2615
2616@sa bt_message_discarded_events_set_count() &mdash;
2617 Sets the number of discarded events of a discarded events message.
2618*/
2619extern bt_property_availability bt_message_discarded_events_get_count(
4c81a2b7 2620 const bt_message *message, uint64_t *count) __BT_NOEXCEPT;
43c59509
PP
2621
2622/*! @} */
2623
2624/*!
2625@name Discarded packets message
2626@{
2627*/
2628
2629/*!
2630@brief
2631 Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
2632 \bt_msg_iter \bt_p{self_message_iterator}.
2633
2634@attention
2635 @parblock
2636 Only use this function if
2637
2638 @code
2639 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2640 bt_stream_borrow_class_const(stream))
2641 @endcode
2642
2643 returns #BT_FALSE.
2644
2645 Otherwise, use
2646 bt_message_discarded_packets_create_with_default_clock_snapshots().
2647 @endparblock
2648
2649On success, the returned discarded packets message has the following
2650property values:
2651
2652<table>
2653 <tr>
2654 <th>Property
2655 <th>Value
2656 <tr>
2657 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2658 <td>\bt_p{stream}
2659 <tr>
2660 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2661 <td>\em None
2662 <tr>
2663 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2664 <td>\em None
2665 <tr>
2666 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2667 <td>\em None
2668</table>
2669
2670@param[in] self_message_iterator
2671 Self message iterator from which to create the discarded packets
2672 message.
2673@param[in] stream
2674 Stream from which the packets were discarded.
2675
2676@returns
2677 New discarded packets message reference, or \c NULL on memory error.
2678
2679@bt_pre_not_null{self_message_iterator}
2680@bt_pre_not_null{stream}
2681@pre
2682 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2683 returns #BT_FALSE.
2684
2685@bt_post_success_frozen{stream}
2686*/
2687extern bt_message *bt_message_discarded_packets_create(
2688 bt_self_message_iterator *self_message_iterator,
4c81a2b7 2689 const bt_stream *stream) __BT_NOEXCEPT;
43c59509
PP
2690
2691/*!
2692@brief
2693 Creates a \bt_disc_pkt_msg having the beginning and end default
2694 \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
2695 \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
2696 from the \bt_msg_iter \bt_p{self_message_iterator}.
2697
2698@attention
2699 @parblock
2700 Only use this function if
2701
2702 @code
2703 bt_stream_class_discarded_packets_have_default_clock_snapshots(
2704 bt_stream_borrow_class_const(stream))
2705 @endcode
2706
2707 returns #BT_TRUE.
2708
2709 Otherwise, use
2710 bt_message_discarded_packets_create().
2711 @endparblock
2712
2713On success, the returned discarded packets message has the following
2714property values:
2715
2716<table>
2717 <tr>
2718 <th>Property
2719 <th>Value
2720 <tr>
2721 <td>\ref api-msg-disc-pkt-prop-stream "Stream"
2722 <td>\bt_p{stream}
2723 <tr>
2724 <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
2725 <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
2726 <tr>
2727 <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
2728 <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
2729 <tr>
2730 <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
2731 <td>\em None
2732</table>
2733
2734@param[in] self_message_iterator
2735 Self message iterator from which to create the discarded packets
2736 message.
2737@param[in] stream
2738 Stream from which the packets were discarded.
2739@param[in] beginning_clock_snapshot_value
2740 Value (clock cycles) of the beginning default clock snapshot of
2741 \bt_p{message}.
2742@param[in] end_clock_snapshot_value
2743 Value (clock cycles) of the end default clock snapshot of
2744 \bt_p{message}.
2745
2746@returns
2747 New discarded packets message reference, or \c NULL on memory error.
2748
2749@bt_pre_not_null{self_message_iterator}
2750@bt_pre_not_null{stream}
2751@pre
2752 <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
2753 returns #BT_TRUE.
5d9ef4cb 2754 \bt_p{beginning_clock_snapshot_value} ⩽ \bt_p{end_clock_snapshot_value}
43c59509
PP
2755
2756@bt_post_success_frozen{stream}
2757*/
2758extern bt_message *bt_message_discarded_packets_create_with_default_clock_snapshots(
2759 bt_self_message_iterator *self_message_iterator,
2760 const bt_stream *stream, uint64_t beginning_clock_snapshot_value,
4c81a2b7 2761 uint64_t end_clock_snapshot_value) __BT_NOEXCEPT;
43c59509
PP
2762
2763/*!
2764@brief
2765 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
2766
2767See the \ref api-msg-disc-ev-prop-stream "stream" property.
2768
2769@param[in] message
2770 Discarded packets message from which to borrow the stream.
2771
2772@returns
2773 @parblock
2774 \em Borrowed reference of the stream of \bt_p{message}.
2775
2776 The returned pointer remains valid as long as \bt_p{message} exists.
2777 @endparblock
2778
2779@bt_pre_not_null{message}
2780@bt_pre_is_disc_pkt_msg{message}
2781
2782@sa bt_message_discarded_packets_borrow_stream_const() &mdash;
2783 \c const version of this function.
2784*/
2785extern bt_stream *bt_message_discarded_packets_borrow_stream(
4c81a2b7 2786 bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2787
2788/*!
2789@brief
2790 Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
2791 (\c const version).
2792
2793See bt_message_discarded_packets_borrow_stream().
2794*/
2795extern const bt_stream *
4c81a2b7
PP
2796bt_message_discarded_packets_borrow_stream_const(const bt_message *message)
2797 __BT_NOEXCEPT;
43c59509
PP
2798
2799/*!
2800@brief
2801 Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
2802 \bt_p{message}.
2803
2804See the
2805\ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
2806property.
2807
2808@param[in] message
2809 Discarded packets message from which to borrow the beginning default
2810 clock snapshot.
2811
2812@returns
2813 Beginning default clock snapshot of \bt_p{message}.
2814
2815@bt_pre_not_null{message}
2816@bt_pre_is_disc_pkt_msg{message}
2817@pre
2818 The discarded packets messages of the \bt_stream_cls of
2819 \bt_p{message}
2820 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2821*/
2822extern const bt_clock_snapshot *
2823bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
4c81a2b7 2824 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2825
2826/*!
2827@brief
2828 Borrows the end default \bt_cs of the \bt_disc_pkt_msg
2829 \bt_p{message}.
2830
2831See the
2832\ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
2833property.
2834
2835@param[in] message
2836 Discarded packets message from which to borrow the end default clock
2837 snapshot.
2838
2839@returns
2840 End default clock snapshot of \bt_p{message}.
2841
2842@bt_pre_not_null{message}
2843@bt_pre_is_disc_pkt_msg{message}
2844@pre
2845 The discarded packets messages of the \bt_stream_cls of
2846 \bt_p{message}
2847 \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
2848*/
2849extern const bt_clock_snapshot *
2850bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
4c81a2b7 2851 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2852
2853/*!
2854@brief
2855 Borrows the default \bt_clock_cls of the \bt_stream_cls
2856 of the \bt_disc_pkt_msg \bt_p{message}.
2857
2858See the stream class's
2859\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
2860property.
2861
2862This is a helper which is equivalent to
2863
2864@code
2865bt_stream_class_borrow_default_clock_class_const(
2866 bt_stream_borrow_class_const(
2867 bt_message_discarded_packets_borrow_stream_const(message)))
2868@endcode
2869
2870@param[in] message
2871 Discarded packets message from which to borrow its stream's class's
2872 default clock class.
2873
2874@returns
2875 \em Borrowed reference of the default clock class of
2876 the stream class of \bt_p{message}, or \c NULL if none.
2877
2878@bt_pre_not_null{message}
2879@bt_pre_is_disc_pkt_msg{message}
2880*/
2881extern const bt_clock_class *
2882bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
4c81a2b7 2883 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
2884
2885/*!
2886@brief
2887 Sets the number of discarded packets of the \bt_disc_pkt_msg
2888 \bt_p{message} to \bt_p{count}.
2889
2890See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2891property.
2892
2893@param[in] message
2894 Discarded packets message of which to set the number of discarded
2895 packets to \bt_p{count}.
2896@param[in] count
2897 New number of discarded packets of \bt_p{message}.
2898
2899@bt_pre_not_null{message}
2900@bt_pre_hot{message}
2901@bt_pre_is_disc_pkt_msg{message}
e5a41ca3
SM
2902@pre
2903 \bt_p{count} > 0
43c59509
PP
2904
2905@sa bt_message_discarded_packets_get_count() &mdash;
2906 Returns the number of discarded packets of a discarded packets
2907 message.
2908*/
2909extern void bt_message_discarded_packets_set_count(bt_message *message,
4c81a2b7 2910 uint64_t count) __BT_NOEXCEPT;
43c59509
PP
2911
2912/*!
2913@brief
2914 Returns the number of discarded packets of the \bt_disc_pkt_msg
2915 \bt_p{message}.
2916
2917See the \ref api-msg-disc-ev-prop-count "discarded packet count"
2918property.
2919
2920@param[in] message
2921 Discarded packets message of which to get the number of discarded
2922 packets.
2923@param[out] count
2924 <strong>If this function returns
2925 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
2926 the number of discarded packets of \bt_p{message}.
2927
2928@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
2929 The number of discarded packets of \bt_p{message} is available.
2930@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
2931 The number of discarded packets of \bt_p{message} is not available.
2932
2933@bt_pre_not_null{message}
2934@bt_pre_is_disc_pkt_msg{message}
2935@bt_pre_not_null{count}
2936
2937@sa bt_message_discarded_packets_set_count() &mdash;
2938 Sets the number of discarded packets of a discarded packets message.
2939*/
2940extern bt_property_availability bt_message_discarded_packets_get_count(
4c81a2b7 2941 const bt_message *message, uint64_t *count) __BT_NOEXCEPT;
43c59509
PP
2942
2943/*! @} */
2944
2945/*!
2946@name Message iterator inactivity message
2947@{
2948*/
2949
2950/*!
2951@brief
2952 Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
2953 the \bt_clock_cls \bt_p{clock_class} with the value
2954 \bt_p{clock_snapshot_value} from the \bt_msg_iter
2955 \bt_p{self_message_iterator}.
2956
2957On success, the returned message iterator inactivity message has the
2958following property values:
2959
2960<table>
2961 <tr>
2962 <th>Property
2963 <th>Value
2964 <tr>
2965 <td>\ref api-msg-inac-prop-cs "Clock snapshot"
2966 <td>
2967 \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
2968 with the value \bt_p{clock_snapshot_value}.
2969</table>
2970
2971@param[in] self_message_iterator
2972 Self message iterator from which to create the message iterator
2973 inactivity message.
2974@param[in] clock_class
2975 Class of the fictitious instance of which
2976 \bt_p{clock_snapshot_value} is the value of its snapshot.
2977@param[in] clock_snapshot_value
2978 Value (clock cycles) of the clock snapshot of \bt_p{message}.
2979
2980@returns
2981 New message iterator inactivity message reference, or \c NULL on
2982 memory error.
2983
2984@bt_pre_not_null{self_message_iterator}
2985@bt_pre_not_null{clock_class}
2986
2987@bt_post_success_frozen{clock_class}
2988*/
2989extern
2990bt_message *bt_message_message_iterator_inactivity_create(
2991 bt_self_message_iterator *self_message_iterator,
2992 const bt_clock_class *clock_class,
4c81a2b7 2993 uint64_t clock_snapshot_value) __BT_NOEXCEPT;
43c59509
PP
2994
2995/*!
2996@brief
2997 Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
2998
2999See the \ref api-msg-inac-prop-cs "clock snapshot" property.
3000
3001@param[in] message
3002 Message iterator inactivity message from which to borrow the clock
3003 snapshot.
3004
3005@returns
3006 Clock snapshot of \bt_p{message}.
3007
3008@bt_pre_not_null{message}
3009@bt_pre_is_inac_msg{message}
3010*/
3011extern const bt_clock_snapshot *
3012bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
4c81a2b7 3013 const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
3014
3015/*! @} */
3016
3017/*!
3018@name Message reference count
3019@{
3020*/
3021
3022/*!
3023@brief
3024 Increments the \ref api-fund-shared-object "reference count" of
3025 the message \bt_p{message}.
3026
3027@param[in] message
3028 @parblock
3029 Message of which to increment the reference count.
3030
3031 Can be \c NULL.
3032 @endparblock
3033
3034@sa bt_message_put_ref() &mdash;
3035 Decrements the reference count of a message.
3036*/
4c81a2b7 3037extern void bt_message_get_ref(const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
3038
3039/*!
3040@brief
3041 Decrements the \ref api-fund-shared-object "reference count" of
3042 the message \bt_p{message}.
3043
3044@param[in] message
3045 @parblock
3046 Message of which to decrement the reference count.
3047
3048 Can be \c NULL.
3049 @endparblock
3050
3051@sa bt_message_get_ref() &mdash;
3052 Increments the reference count of a message.
3053*/
4c81a2b7 3054extern void bt_message_put_ref(const bt_message *message) __BT_NOEXCEPT;
43c59509
PP
3055
3056/*!
3057@brief
3058 Decrements the reference count of the message \bt_p{_message}, and
3059 then sets \bt_p{_message} to \c NULL.
3060
3061@param _message
3062 @parblock
3063 Message of which to decrement the reference count.
3064
3065 Can contain \c NULL.
3066 @endparblock
3067
3068@bt_pre_assign_expr{_message}
3069*/
3070#define BT_MESSAGE_PUT_REF_AND_RESET(_message) \
3071 do { \
3072 bt_message_put_ref(_message); \
3073 (_message) = NULL; \
3074 } while (0)
3075
3076/*!
3077@brief
3078 Decrements the reference count of the message \bt_p{_dst}, sets
3079 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
3080
3081This macro effectively moves a message reference from the expression
3082\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
3083\bt_p{_dst} reference.
3084
3085@param _dst
3086 @parblock
3087 Destination expression.
3088
3089 Can contain \c NULL.
3090 @endparblock
3091@param _src
3092 @parblock
3093 Source expression.
3094
3095 Can contain \c NULL.
3096 @endparblock
3097
3098@bt_pre_assign_expr{_dst}
3099@bt_pre_assign_expr{_src}
3100*/
3101#define BT_MESSAGE_MOVE_REF(_dst, _src) \
3102 do { \
3103 bt_message_put_ref(_dst); \
3104 (_dst) = (_src); \
3105 (_src) = NULL; \
3106 } while (0)
3107
3108/*! @} */
3109
43c59509
PP
3110/*!
3111@name Message Interchange Protocol version
3112@{
3113*/
3114
3115/*!
3116@brief
3117 Status codes for bt_get_greatest_operative_mip_version().
3118*/
3119typedef enum bt_get_greatest_operative_mip_version_status {
3120 /*!
3121 @brief
3122 Success.
3123 */
3124 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK = __BT_FUNC_STATUS_OK,
3125
3126 /*!
3127 @brief
3128 No match found.
3129 */
3130 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH = __BT_FUNC_STATUS_NO_MATCH,
3131
3132 /*!
3133 @brief
3134 Out of memory.
3135 */
3136 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
3137
3138 /*!
3139 @brief
3140 Other error.
3141 */
3142 BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
3143} bt_get_greatest_operative_mip_version_status;
3144
3145/*!
3146@brief
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.
3152
3153This function calls the
3154\link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
3155method for each component descriptor in \bt_p{component_descriptors},
3156and then returns the greatest common (operative) MIP version, if any.
3157The "get supported MIP versions" method receives \bt_p{logging_level} as
3158its \bt_p{logging_level} parameter.
3159
3160If this function does not find an operative MIP version for the
3161component descriptors of \bt_p{component_descriptors}, it returns
3162#BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
3163
3164@note
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
3167 0 on success.
3168
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}.
3180
3181@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
3182 Success.
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
3187 Out of memory.
3188@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
3189 Other error.
3190
3191@bt_pre_not_null{component_descriptors}
3192@pre
3193 \bt_p{component_descriptors} contains one or more component
3194 descriptors.
3195@bt_pre_not_null{mip_version}
3196*/
3197extern bt_get_greatest_operative_mip_version_status
3198bt_get_greatest_operative_mip_version(
3199 const bt_component_descriptor_set *component_descriptors,
4c81a2b7
PP
3200 bt_logging_level logging_level, uint64_t *mip_version)
3201 __BT_NOEXCEPT;
43c59509
PP
3202
3203/*!
3204@brief
3205 Returns the maximal available \bt_mip version as of
3206 \bt_name_version_min_maj.
3207
3208As of \bt_name_version_min_maj, this function returns
3209\bt_max_mip_version.
3210
3211@returns
3212 Maximal available MIP version (\bt_max_mip_version).
3213*/
4c81a2b7 3214extern uint64_t bt_get_maximal_mip_version(void) __BT_NOEXCEPT;
43c59509
PP
3215
3216/*! @} */
3217
3218/*! @} */
3219
3220#ifdef __cplusplus
3221}
3222#endif
3223
3224#endif /* BABELTRACE2_GRAPH_MESSAGE_H */
This page took 0.15396 seconds and 4 git commands to generate.