Commit | Line | Data |
---|---|---|
56e18c4c | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
56e18c4c | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
56e18c4c PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_TRACE_IR_STREAM_CLASS_H |
8 | #define BABELTRACE2_TRACE_IR_STREAM_CLASS_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
56e18c4c PP |
16 | #include <stdint.h> |
17 | ||
3fadfbc0 | 18 | #include <babeltrace2/types.h> |
56e18c4c PP |
19 | |
20 | #ifdef __cplusplus | |
21 | extern "C" { | |
22 | #endif | |
23 | ||
43c59509 PP |
24 | /*! |
25 | @defgroup api-tir-stream-cls Stream class | |
26 | @ingroup api-tir | |
27 | ||
28 | @brief | |
29 | Class of \bt_p_stream. | |
30 | ||
31 | A <strong><em>stream class</em></strong> is the class of \bt_p_stream: | |
32 | ||
33 | @image html trace-structure.png | |
34 | ||
35 | In the illustration above, notice that: | |
36 | ||
37 | - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages". | |
38 | ||
39 | The sequence always starts with a \bt_sb_msg and ends with a | |
40 | \bt_se_msg. | |
41 | ||
42 | - A stream is an instance of a stream class. | |
43 | ||
44 | A stream class is a \ref api-tir "trace IR" metadata object. | |
45 | ||
46 | A stream class is a \ref api-fund-shared-object "shared object": get a | |
47 | new reference with bt_stream_class_get_ref() and put an existing | |
48 | reference with bt_stream_class_put_ref(). | |
49 | ||
50 | Some library functions \ref api-fund-freezing "freeze" stream classes on | |
51 | success. The documentation of those functions indicate this | |
52 | postcondition. You can still create and add an \bt_p_ev_cls to a frozen | |
53 | stream class with bt_event_class_create() or | |
54 | bt_event_class_create_with_id(). | |
55 | ||
56 | The type of a stream class is #bt_stream_class. | |
57 | ||
58 | A \bt_trace_cls contains stream classes. All the stream classes of a | |
59 | given trace class have unique | |
60 | \ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class | |
61 | which contains a stream class with bt_stream_class_borrow_trace_class() | |
62 | or bt_stream_class_borrow_trace_class_const(). | |
63 | ||
64 | A stream class contains \bt_p_ev_cls. All the event classes of a given | |
65 | stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get | |
66 | the number of event classes in a stream class with | |
67 | bt_stream_class_get_event_class_count(). Borrow a specific event class | |
68 | from a stream class with bt_stream_class_borrow_event_class_by_index(), | |
69 | bt_stream_class_borrow_event_class_by_index_const(), | |
70 | bt_stream_class_borrow_event_class_by_id(), and | |
71 | bt_stream_class_borrow_event_class_by_id_const(). | |
72 | ||
73 | A stream class controls what its instances (\bt_p_stream) support: | |
74 | ||
75 | <dl> | |
76 | <dt>Default clock</dt> | |
77 | <dd> | |
78 | By default, a stream class's streams do not have default clocks. | |
79 | ||
80 | Set the default \bt_clock_cls of a stream class with | |
81 | bt_stream_class_set_default_clock_class(). This makes all its | |
82 | streams have their own default clock. | |
83 | </dd> | |
84 | ||
85 | <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt> | |
86 | <dd> | |
87 | By default, a stream class's streams do not support \bt_p_pkt. | |
88 | ||
89 | In other words, you cannot create a packet for such a stream, | |
90 | therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this | |
91 | stream either. | |
92 | ||
93 | Enable packet support for a stream class's streams with | |
94 | bt_stream_class_set_supports_packets(). | |
95 | ||
96 | bt_stream_class_set_supports_packets() also configures whether or | |
97 | not the packets of the stream class's instances have beginning | |
98 | and/or end default \bt_p_cs. | |
99 | </dd> | |
100 | ||
101 | <dt>Discarded events</dt> | |
102 | <dd> | |
103 | By default, a stream class's streams do not support discarded | |
104 | events. | |
105 | ||
106 | In other words, you cannot create \bt_p_disc_ev_msg for such a | |
107 | stream. | |
108 | ||
109 | Enable discarded events support for a stream class's streams with | |
110 | bt_stream_class_set_supports_discarded_events(). | |
111 | ||
112 | bt_stream_class_set_supports_discarded_events() also configures | |
113 | whether or not the discarded events messages of the stream class's | |
114 | instances have beginning and end default \bt_p_cs to indicate the | |
115 | discarded events time range. | |
116 | </dd> | |
117 | ||
118 | <dt>Discarded packets</dt> | |
119 | <dd> | |
120 | By default, a stream class's streams do not support discarded | |
121 | packets. | |
122 | ||
123 | In other words, you cannot create \bt_p_disc_pkt_msg for such a | |
124 | stream. | |
125 | ||
126 | Enable discarded packets support for a stream class's streams with | |
127 | bt_stream_class_set_supports_discarded_packets(). This also implies | |
128 | that you must enable packet support with | |
129 | bt_stream_class_set_supports_packets(). | |
130 | ||
131 | bt_stream_class_set_supports_discarded_packets() also configures | |
132 | whether or not the discarded packets messages of the stream class's | |
133 | instances have beginning and end \bt_p_cs to indicate the | |
134 | discarded packets time range. | |
135 | </dd> | |
136 | </dl> | |
137 | ||
138 | Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a | |
139 | stream class get automatic numeric IDs with | |
140 | bt_stream_class_set_assigns_automatic_event_class_id() and | |
141 | bt_stream_class_set_assigns_automatic_stream_id(). | |
142 | ||
143 | To create a default stream class: | |
144 | ||
145 | <dl> | |
146 | <dt> | |
147 | If bt_trace_class_assigns_automatic_stream_class_id() returns | |
148 | #BT_TRUE (the default) for the trace class to use | |
149 | </dt> | |
150 | <dd>Use bt_stream_class_create().</dd> | |
151 | ||
152 | <dt> | |
153 | If bt_trace_class_assigns_automatic_stream_class_id() returns | |
154 | #BT_FALSE for the trace class to use | |
155 | </dt> | |
156 | <dd>Use bt_stream_class_create_with_id().</dd> | |
157 | </dl> | |
158 | ||
159 | <h1>Properties</h1> | |
160 | ||
161 | A stream class has the following properties: | |
162 | ||
163 | <dl> | |
164 | <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt> | |
165 | <dd> | |
166 | Numeric ID, unique amongst the numeric IDs of the stream class's | |
167 | \bt_trace_cls's stream classes. | |
168 | ||
169 | Depending on whether or not the stream class's trace class | |
170 | automatically assigns \bt_ev_cls IDs | |
171 | (see bt_trace_class_assigns_automatic_stream_class_id()), | |
172 | set the stream class's numeric ID on creation with | |
173 | bt_stream_class_create() or bt_stream_class_create_with_id(). | |
174 | ||
175 | You cannot change the numeric ID once the stream class is created. | |
176 | ||
177 | Get a stream class's numeric ID with bt_stream_class_get_id(). | |
178 | </dd> | |
179 | ||
180 | <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt> | |
181 | <dd> | |
182 | Name of the stream class. | |
183 | ||
184 | Use bt_stream_class_set_name() and bt_stream_class_get_name(). | |
185 | </dd> | |
186 | ||
187 | <dt> | |
188 | \anchor api-tir-stream-cls-prop-def-clock-cls | |
189 | \bt_dt_opt Default clock class | |
190 | </dt> | |
191 | <dd> | |
192 | Default \bt_clock_cls of the stream class. | |
193 | ||
194 | As of \bt_name_version_min_maj, a stream class either has a default | |
195 | clock class or none: it cannot have more than one clock class. | |
196 | ||
197 | When a stream class has a default clock class, then all its | |
198 | instances (\bt_p_stream) have a default clock which is an instance | |
199 | of the stream class's default clock class. | |
200 | ||
201 | Use bt_stream_class_set_default_clock_class(), | |
202 | bt_stream_class_borrow_default_clock_class(), and | |
203 | bt_stream_class_borrow_default_clock_class_const(). | |
204 | </dd> | |
205 | ||
206 | <dt> | |
207 | \anchor api-tir-stream-cls-prop-pc-fc | |
208 | \bt_dt_opt Packet context field class | |
209 | </dt> | |
210 | <dd> | |
211 | \bt_c_pkt context \bt_fc of the stream class. | |
212 | ||
213 | This property is only relevant if the stream class | |
214 | \ref api-tir-stream-cls-prop-supports-pkt "supports packets". | |
215 | ||
216 | The context of a \bt_pkt contains data which is common to all the | |
217 | packet's \bt_p_ev. | |
218 | ||
219 | Use bt_stream_class_set_packet_context_field_class() | |
220 | bt_stream_class_borrow_packet_context_field_class(), | |
221 | and bt_stream_class_borrow_packet_context_field_class_const(). | |
222 | </dd> | |
223 | ||
224 | <dt> | |
225 | \anchor api-tir-stream-cls-prop-ecc-fc | |
226 | \bt_dt_opt Event common context field class | |
227 | </dt> | |
228 | <dd> | |
229 | \bt_c_ev common context \bt_fc of the stream class. | |
230 | ||
231 | The common context of an \bt_ev contains contextual data of which | |
232 | the layout is common to all the stream class's \bt_p_ev_cls. | |
233 | ||
234 | Use bt_stream_class_set_event_common_context_field_class() | |
235 | bt_stream_class_borrow_event_common_context_field_class(), | |
236 | and bt_stream_class_borrow_event_common_context_field_class_const(). | |
237 | </dd> | |
238 | ||
239 | <dt> | |
240 | \anchor api-tir-stream-cls-prop-auto-ec-id | |
241 | Assigns automatic event class IDs? | |
242 | </dt> | |
243 | <dd> | |
244 | Whether or not the \bt_p_ev_cls you create and add to the stream | |
245 | class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically. | |
246 | ||
247 | Depending on the value of this property, to create an event class | |
248 | and add it to the stream class: | |
249 | ||
250 | <dl> | |
251 | <dt>#BT_TRUE</dt> | |
252 | <dd> | |
253 | Use bt_event_class_create(). | |
254 | </dd> | |
255 | ||
256 | <dt>#BT_FALSE</dt> | |
257 | <dd> | |
258 | Use bt_event_class_create_with_id(). | |
259 | </dd> | |
260 | </dl> | |
261 | ||
262 | Use bt_stream_class_set_assigns_automatic_event_class_id() | |
263 | and bt_stream_class_assigns_automatic_event_class_id(). | |
264 | </dd> | |
265 | ||
266 | <dt> | |
267 | \anchor api-tir-stream-cls-prop-auto-stream-id | |
268 | Assigns automatic stream IDs? | |
269 | </dt> | |
270 | <dd> | |
271 | Whether or not the streams you create from the stream class | |
272 | get \ref api-tir-stream-prop-id "numeric IDs" automatically. | |
273 | ||
274 | Depending on the value of this property, to create a stream | |
275 | from the stream class: | |
276 | ||
277 | <dl> | |
278 | <dt>#BT_TRUE</dt> | |
279 | <dd> | |
280 | Use bt_stream_create(). | |
281 | </dd> | |
282 | ||
283 | <dt>#BT_FALSE</dt> | |
284 | <dd> | |
285 | Use bt_stream_create_with_id(). | |
286 | </dd> | |
287 | </dl> | |
288 | ||
289 | Use bt_stream_class_set_assigns_automatic_stream_id() | |
290 | and bt_stream_class_assigns_automatic_stream_id(). | |
291 | </dd> | |
292 | ||
293 | <dt> | |
294 | \anchor api-tir-stream-cls-prop-supports-pkt | |
295 | Supports packets? | |
296 | </dt> | |
297 | <dd> | |
298 | Whether or not the streams you create from the stream class | |
299 | have \bt_p_pkt. | |
300 | ||
301 | If a stream has packets, then all the stream's \bt_p_ev are | |
302 | conceptually contained within packets, which means you must | |
303 | create \bt_p_ev_msg for such streams with | |
304 | bt_message_event_create_with_packet() or | |
305 | bt_message_event_create_with_packet_and_default_clock_snapshot() | |
306 | instead of bt_message_event_create() or | |
307 | bt_message_event_create_with_default_clock_snapshot(). | |
308 | ||
309 | It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to | |
310 | indicate where packets begin and end within the stream's | |
311 | \ref api-msg-seq "message sequence". | |
312 | ||
313 | Use bt_stream_class_set_supports_packets() and | |
314 | bt_stream_class_supports_packets(). | |
315 | </dd> | |
316 | ||
317 | <dt> | |
318 | \anchor api-tir-stream-cls-prop-pkt-beg-cs | |
319 | Packets have a beginning default clock snapshot? | |
320 | </dt> | |
321 | <dd> | |
322 | Whether or not the \bt_p_pkt of the streams you create from the | |
323 | stream class have beginning default \bt_p_cs. | |
324 | ||
325 | This property is only relevant if the stream class | |
326 | \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and | |
327 | has a | |
328 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
329 | ||
330 | If the stream packets have a beginning default clock snapshot, then | |
331 | you must create \bt_p_pb_msg with | |
332 | bt_message_packet_beginning_create_with_default_clock_snapshot() | |
333 | instead of bt_message_packet_beginning_create(). | |
334 | ||
335 | Use bt_stream_class_set_supports_packets() and | |
336 | bt_stream_class_packets_have_beginning_default_clock_snapshot(). | |
337 | </dd> | |
338 | ||
339 | <dt> | |
340 | \anchor api-tir-stream-cls-prop-pkt-end-cs | |
341 | Packets have an end default clock snapshot? | |
342 | </dt> | |
343 | <dd> | |
344 | Whether or not the \bt_p_pkt of the streams you create from the | |
345 | stream class have end default \bt_p_cs. | |
346 | ||
347 | This property is only relevant if the stream class | |
348 | \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and | |
349 | has a | |
350 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
351 | ||
352 | If the stream packets have an end default clock snapshot, then you | |
353 | must create \bt_p_pe_msg with | |
354 | bt_message_packet_end_create_with_default_clock_snapshot() instead | |
355 | of bt_message_packet_end_create(). | |
356 | ||
357 | Use bt_stream_class_set_supports_packets() and | |
358 | bt_stream_class_packets_have_end_default_clock_snapshot(). | |
359 | </dd> | |
360 | ||
361 | <dt> | |
362 | \anchor api-tir-stream-cls-prop-supports-disc-ev | |
363 | Supports discarded events? | |
364 | </dt> | |
365 | <dd> | |
366 | Whether or not the streams you create from the stream class can have | |
367 | discarded events. | |
368 | ||
369 | If the stream class supports discarded events, then you can create | |
370 | \bt_p_disc_ev_msg for this stream. | |
371 | ||
372 | Use bt_stream_class_set_supports_discarded_events() | |
373 | and bt_stream_class_supports_discarded_events(). | |
374 | </dd> | |
375 | ||
376 | <dt> | |
377 | \anchor api-tir-stream-cls-prop-disc-ev-cs | |
378 | Discarded events have default clock snapshots? | |
379 | </dt> | |
380 | <dd> | |
381 | Whether or not the stream's \bt_p_disc_ev_msg have | |
382 | default beginning and end \bt_p_cs to indicate the discarded events | |
383 | time range. | |
384 | ||
385 | This property is only relevant if the stream class | |
386 | \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events" | |
387 | and has a | |
388 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
389 | ||
390 | If the stream's discarded events messages have beginning and end | |
391 | default clock snapshots, then you must create them with | |
392 | bt_message_discarded_events_create_with_default_clock_snapshots() | |
393 | instead of bt_message_discarded_events_create(). | |
394 | ||
395 | Use bt_stream_class_set_supports_discarded_events() | |
396 | and bt_stream_class_discarded_events_have_default_clock_snapshots(). | |
397 | </dd> | |
398 | ||
399 | <dt> | |
400 | \anchor api-tir-stream-cls-prop-supports-disc-pkt | |
401 | Supports discarded packets? | |
402 | </dt> | |
403 | <dd> | |
404 | Whether or not the streams you create from the stream class can have | |
405 | discarded packets. | |
406 | ||
407 | This property is only relevant if the stream class | |
408 | \ref api-tir-stream-cls-prop-supports-pkt "supports packets". | |
409 | ||
410 | If the stream class supports discarded packets, then you can create | |
411 | \bt_p_disc_pkt_msg for this stream. | |
412 | ||
413 | Use bt_stream_class_set_supports_discarded_packets() | |
414 | and bt_stream_class_supports_discarded_packets(). | |
415 | </dd> | |
416 | ||
417 | <dt> | |
418 | \anchor api-tir-stream-cls-prop-disc-pkt-cs | |
419 | Discarded packets have default clock snapshots? | |
420 | </dt> | |
421 | <dd> | |
422 | Whether or not the stream's \bt_p_disc_pkt_msg have | |
423 | default beginning and end \bt_p_cs to indicate the discarded | |
424 | packets time range. | |
425 | ||
426 | This property is only relevant if the stream class | |
427 | \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets" | |
428 | and has a | |
429 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
430 | ||
431 | If the stream's discarded packets messages have default clock | |
432 | snapshots, then you must create them with | |
433 | bt_message_discarded_packets_create_with_default_clock_snapshots() | |
434 | instead of bt_message_discarded_packets_create(). | |
435 | ||
436 | Use bt_stream_class_set_supports_discarded_packets() | |
437 | and bt_stream_class_discarded_packets_have_default_clock_snapshots(). | |
438 | </dd> | |
439 | ||
440 | <dt> | |
441 | \anchor api-tir-stream-cls-prop-user-attrs | |
442 | \bt_dt_opt User attributes | |
443 | </dt> | |
444 | <dd> | |
445 | User attributes of the stream class. | |
446 | ||
447 | User attributes are custom attributes attached to a stream class. | |
448 | ||
449 | Use bt_stream_class_set_user_attributes(), | |
450 | bt_stream_class_borrow_user_attributes(), and | |
451 | bt_stream_class_borrow_user_attributes_const(). | |
452 | </dd> | |
453 | </dl> | |
454 | */ | |
455 | ||
456 | /*! @{ */ | |
457 | ||
458 | /*! | |
459 | @name Type | |
460 | @{ | |
461 | ||
462 | @typedef struct bt_stream_class bt_stream_class; | |
463 | ||
464 | @brief | |
465 | Stream class. | |
466 | ||
467 | @} | |
468 | */ | |
469 | ||
470 | /*! | |
471 | @name Creation | |
472 | @{ | |
473 | */ | |
474 | ||
475 | /*! | |
476 | @brief | |
477 | Creates a default stream class and adds it to the \bt_trace_cls | |
478 | \bt_p{trace_class}. | |
479 | ||
480 | @attention | |
481 | @parblock | |
482 | Only use this function if | |
483 | ||
484 | @code | |
485 | bt_trace_class_assigns_automatic_stream_class_id(trace_class) | |
486 | @endcode | |
487 | ||
488 | returns #BT_TRUE. | |
489 | ||
490 | Otherwise, use bt_stream_class_create_with_id(). | |
491 | @endparblock | |
492 | ||
493 | On success, the returned stream class has the following property values: | |
494 | ||
495 | <table> | |
496 | <tr> | |
497 | <th>Property | |
498 | <th>Value | |
499 | <tr> | |
500 | <td>\ref api-tir-stream-cls-prop-id "Numeric ID" | |
501 | <td>Automatically assigned by \bt_p{trace_class} | |
502 | <tr> | |
503 | <td>\ref api-tir-stream-cls-prop-name "Name" | |
504 | <td>\em None | |
505 | <tr> | |
506 | <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" | |
507 | <td>\em None | |
508 | <tr> | |
509 | <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" | |
510 | <td>\em None | |
511 | <tr> | |
512 | <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" | |
513 | <td>\em None | |
514 | <tr> | |
515 | <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" | |
516 | <td>Yes | |
517 | <tr> | |
518 | <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" | |
519 | <td>Yes | |
520 | <tr> | |
521 | <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" | |
522 | <td>No | |
523 | <tr> | |
524 | <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" | |
525 | <td>No | |
526 | <tr> | |
527 | <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" | |
528 | <td>No | |
529 | <tr> | |
530 | <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" | |
531 | <td>No | |
532 | <tr> | |
533 | <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" | |
534 | <td>No | |
535 | <tr> | |
536 | <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" | |
537 | <td>No | |
538 | <tr> | |
539 | <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" | |
540 | <td>No | |
541 | <tr> | |
542 | <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes" | |
543 | <td>Empty \bt_map_val | |
544 | </table> | |
545 | ||
546 | @param[in] trace_class | |
547 | Trace class to add the created stream class to. | |
548 | ||
549 | @returns | |
550 | New stream class reference, or \c NULL on memory error. | |
551 | ||
552 | @bt_pre_not_null{trace_class} | |
553 | @pre | |
554 | <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code> | |
555 | returns #BT_TRUE. | |
556 | ||
557 | @bt_post_success_frozen{trace_class} | |
558 | ||
559 | @sa bt_stream_class_create_with_id() — | |
560 | Creates a stream class with a specific numeric ID and adds it to a | |
561 | trace class. | |
562 | */ | |
b19ff26f | 563 | extern bt_stream_class *bt_stream_class_create( |
4c81a2b7 | 564 | bt_trace_class *trace_class) __BT_NOEXCEPT; |
56e18c4c | 565 | |
43c59509 PP |
566 | /*! |
567 | @brief | |
568 | Creates a default stream class with the numeric ID \bt_p{id} and adds | |
569 | it to the \bt_trace_cls \bt_p{trace_class}. | |
570 | ||
571 | @attention | |
572 | @parblock | |
573 | Only use this function if | |
574 | ||
575 | @code | |
576 | bt_trace_class_assigns_automatic_stream_class_id(trace_class) | |
577 | @endcode | |
578 | ||
579 | returns #BT_FALSE. | |
580 | ||
581 | Otherwise, use bt_stream_class_create(). | |
582 | @endparblock | |
583 | ||
584 | On success, the returned stream class has the following property values: | |
585 | ||
586 | <table> | |
587 | <tr> | |
588 | <th>Property | |
589 | <th>Value | |
590 | <tr> | |
591 | <td>\ref api-tir-stream-cls-prop-id "Numeric ID" | |
592 | <td>\bt_p{id} | |
593 | <tr> | |
594 | <td>\ref api-tir-stream-cls-prop-name "Name" | |
595 | <td>\em None | |
596 | <tr> | |
597 | <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" | |
598 | <td>\em None | |
599 | <tr> | |
600 | <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" | |
601 | <td>\em None | |
602 | <tr> | |
603 | <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" | |
604 | <td>\em None | |
605 | <tr> | |
606 | <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" | |
607 | <td>Yes | |
608 | <tr> | |
609 | <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" | |
610 | <td>Yes | |
611 | <tr> | |
612 | <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" | |
613 | <td>No | |
614 | <tr> | |
615 | <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" | |
616 | <td>No | |
617 | <tr> | |
618 | <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" | |
619 | <td>No | |
620 | <tr> | |
621 | <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" | |
622 | <td>No | |
623 | <tr> | |
624 | <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" | |
625 | <td>No | |
626 | <tr> | |
627 | <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" | |
628 | <td>No | |
629 | <tr> | |
630 | <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" | |
631 | <td>No | |
632 | <tr> | |
633 | <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes" | |
634 | <td>Empty \bt_map_val | |
635 | </table> | |
636 | ||
637 | @param[in] trace_class | |
638 | Trace class to add the created stream class to. | |
639 | @param[in] id | |
640 | Numeric ID of the stream class to create and add to | |
641 | \bt_p{trace_class}. | |
642 | ||
643 | @returns | |
644 | New stream class reference, or \c NULL on memory error. | |
645 | ||
646 | @bt_pre_not_null{trace_class} | |
647 | @pre | |
648 | <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code> | |
649 | returns #BT_FALSE. | |
650 | @pre | |
651 | \bt_p{trace_class} does not contain a stream class with the numeric | |
652 | ID \bt_p{id}. | |
653 | ||
654 | @bt_post_success_frozen{trace_class} | |
655 | ||
656 | @sa bt_stream_class_create() — | |
657 | Creates a stream class with an automatic numeric ID and adds it to a | |
658 | trace class. | |
659 | */ | |
b19ff26f | 660 | extern bt_stream_class *bt_stream_class_create_with_id( |
4c81a2b7 | 661 | bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT; |
56e18c4c | 662 | |
43c59509 | 663 | /*! @} */ |
c6962c96 | 664 | |
43c59509 PP |
665 | /*! |
666 | @name Trace class access | |
667 | @{ | |
668 | */ | |
669 | ||
670 | /*! | |
671 | @brief | |
672 | Borrows the \bt_trace_cls which contains the stream class | |
673 | \bt_p{stream_class}. | |
674 | ||
675 | @param[in] stream_class | |
676 | Stream class from which to borrow the trace class which contains it. | |
c6962c96 | 677 | |
43c59509 PP |
678 | @returns |
679 | Trace class which contains \bt_p{stream_class}. | |
680 | ||
681 | @bt_pre_not_null{stream_class} | |
682 | ||
683 | @sa bt_stream_class_borrow_trace_class_const() — | |
684 | \c const version of this function. | |
685 | */ | |
b19ff26f | 686 | extern bt_trace_class *bt_stream_class_borrow_trace_class( |
4c81a2b7 | 687 | bt_stream_class *stream_class) __BT_NOEXCEPT; |
56e18c4c | 688 | |
43c59509 PP |
689 | /*! |
690 | @brief | |
691 | Borrows the \bt_trace_cls which contains the stream class | |
692 | \bt_p{stream_class} (\c const version). | |
693 | ||
694 | See bt_stream_class_borrow_trace_class(). | |
695 | */ | |
696 | extern const bt_trace_class *bt_stream_class_borrow_trace_class_const( | |
4c81a2b7 | 697 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
698 | |
699 | /*! @} */ | |
700 | ||
701 | /*! | |
702 | @name Event class access | |
703 | @{ | |
704 | */ | |
705 | ||
706 | /*! | |
707 | @brief | |
708 | Returns the number of \bt_p_ev_cls contained in the stream | |
709 | class \bt_p{stream_class}. | |
710 | ||
711 | @param[in] stream_class | |
712 | Stream class of which to get the number of contained event classes. | |
713 | ||
714 | @returns | |
715 | Number of contained event classes in \bt_p{stream_class}. | |
716 | ||
717 | @bt_pre_not_null{stream_class} | |
718 | */ | |
719 | extern uint64_t bt_stream_class_get_event_class_count( | |
4c81a2b7 | 720 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
721 | |
722 | /*! | |
723 | @brief | |
724 | Borrows the \bt_ev_cls at index \bt_p{index} from the | |
725 | stream class \bt_p{stream_class}. | |
726 | ||
727 | @param[in] stream_class | |
728 | Stream class from which to borrow the event class at index | |
729 | \bt_p{index}. | |
730 | @param[in] index | |
731 | Index of the event class to borrow from \bt_p{stream_class}. | |
732 | ||
733 | @returns | |
734 | @parblock | |
735 | \em Borrowed reference of the event class of | |
736 | \bt_p{stream_class} at index \bt_p{index}. | |
737 | ||
738 | The returned pointer remains valid as long as \bt_p{stream_class} | |
739 | exists. | |
740 | @endparblock | |
741 | ||
742 | @bt_pre_not_null{stream_class} | |
743 | @pre | |
744 | \bt_p{index} is less than the number of event classes in | |
745 | \bt_p{stream_class} (as returned by | |
746 | bt_stream_class_get_event_class_count()). | |
747 | ||
748 | @sa bt_stream_class_get_event_class_count() — | |
749 | Returns the number of event classes contained in a stream class. | |
750 | @sa bt_stream_class_borrow_event_class_by_index_const() — | |
751 | \c const version of this function. | |
752 | */ | |
753 | extern bt_event_class * | |
754 | bt_stream_class_borrow_event_class_by_index( | |
4c81a2b7 | 755 | bt_stream_class *stream_class, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
756 | |
757 | /*! | |
758 | @brief | |
759 | Borrows the \bt_ev_cls at index \bt_p{index} from the | |
760 | stream class \bt_p{stream_class} (\c const version). | |
761 | ||
762 | See bt_stream_class_borrow_event_class_by_index(). | |
763 | */ | |
764 | extern const bt_event_class * | |
765 | bt_stream_class_borrow_event_class_by_index_const( | |
4c81a2b7 PP |
766 | const bt_stream_class *stream_class, uint64_t index) |
767 | __BT_NOEXCEPT; | |
43c59509 PP |
768 | |
769 | /*! | |
770 | @brief | |
771 | Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the | |
772 | stream class \bt_p{stream_class}. | |
773 | ||
774 | If there's no event class having the numeric ID \bt_p{id} in | |
775 | \bt_p{stream_class}, this function returns \c NULL. | |
776 | ||
777 | @param[in] stream_class | |
778 | Stream class from which to borrow the event class having the | |
779 | numeric ID \bt_p{id}. | |
780 | @param[in] id | |
781 | ID of the event class to borrow from \bt_p{stream_class}. | |
782 | ||
783 | @returns | |
784 | @parblock | |
785 | \em Borrowed reference of the event class of | |
786 | \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL | |
787 | if none. | |
788 | ||
789 | The returned pointer remains valid as long as \bt_p{stream_class} | |
790 | exists. | |
791 | @endparblock | |
792 | ||
793 | @bt_pre_not_null{stream_class} | |
794 | ||
795 | @sa bt_stream_class_borrow_event_class_by_id_const() — | |
796 | \c const version of this function. | |
797 | */ | |
798 | extern bt_event_class * | |
799 | bt_stream_class_borrow_event_class_by_id( | |
4c81a2b7 | 800 | bt_stream_class *stream_class, uint64_t id) __BT_NOEXCEPT; |
43c59509 PP |
801 | |
802 | /*! | |
803 | @brief | |
804 | Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the | |
805 | stream class \bt_p{stream_class} (\c const version). | |
806 | ||
807 | See bt_stream_class_borrow_event_class_by_id(). | |
808 | */ | |
809 | extern const bt_event_class * | |
810 | bt_stream_class_borrow_event_class_by_id_const( | |
4c81a2b7 | 811 | const bt_stream_class *stream_class, uint64_t id) __BT_NOEXCEPT; |
43c59509 PP |
812 | |
813 | /*! @} */ | |
814 | ||
815 | /*! | |
816 | @name Properties | |
817 | @{ | |
818 | */ | |
819 | ||
820 | /*! | |
821 | @brief | |
822 | Returns the numeric ID of the stream class \bt_p{stream_class}. | |
823 | ||
824 | See the \ref api-tir-stream-cls-prop-id "numeric ID" property. | |
825 | ||
826 | @param[in] stream_class | |
827 | Stream class of which to get the numeric ID. | |
828 | ||
829 | @returns | |
830 | Numeric ID of \bt_p{stream_class}. | |
831 | ||
832 | @bt_pre_not_null{stream_class} | |
833 | ||
834 | @sa bt_stream_class_create_with_id() — | |
835 | Creates a stream class with a specific numeric ID and adds it to a | |
836 | trace class. | |
837 | */ | |
838 | extern uint64_t bt_stream_class_get_id( | |
4c81a2b7 | 839 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
840 | |
841 | /*! | |
842 | @brief | |
843 | Status codes for bt_stream_class_set_name(). | |
844 | */ | |
d24d5663 | 845 | typedef enum bt_stream_class_set_name_status { |
43c59509 PP |
846 | /*! |
847 | @brief | |
848 | Success. | |
849 | */ | |
d24d5663 | 850 | BT_STREAM_CLASS_SET_NAME_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
851 | |
852 | /*! | |
853 | @brief | |
854 | Out of memory. | |
855 | */ | |
856 | BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 PP |
857 | } bt_stream_class_set_name_status; |
858 | ||
43c59509 PP |
859 | /*! |
860 | @brief | |
861 | Sets the name of the stream class \bt_p{stream_class} to | |
862 | a copy of \bt_p{name}. | |
863 | ||
864 | See the \ref api-tir-stream-cls-prop-name "name" property. | |
865 | ||
866 | @param[in] stream_class | |
867 | Stream class of which to set the name to \bt_p{name}. | |
868 | @param[in] name | |
869 | New name of \bt_p{stream_class} (copied). | |
870 | ||
871 | @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK | |
872 | Success. | |
873 | @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR | |
874 | Out of memory. | |
875 | ||
876 | @bt_pre_not_null{stream_class} | |
877 | @bt_pre_hot{stream_class} | |
878 | @bt_pre_not_null{name} | |
879 | ||
880 | @sa bt_stream_class_get_name() — | |
881 | Returns the name of a stream class. | |
882 | */ | |
d24d5663 | 883 | extern bt_stream_class_set_name_status bt_stream_class_set_name( |
4c81a2b7 | 884 | bt_stream_class *stream_class, const char *name) __BT_NOEXCEPT; |
56e18c4c | 885 | |
43c59509 PP |
886 | /*! |
887 | @brief | |
888 | Returns the name of the stream class \bt_p{stream_class}. | |
56e18c4c | 889 | |
43c59509 | 890 | See the \ref api-tir-stream-cls-prop-name "name" property. |
56e18c4c | 891 | |
43c59509 | 892 | If \bt_p{stream_class} has no name, this function returns \c NULL. |
2e90378a | 893 | |
43c59509 PP |
894 | @param[in] stream_class |
895 | Stream class of which to get the name. | |
896 | ||
897 | @returns | |
898 | @parblock | |
899 | Name of \bt_p{stream_class}, or \c NULL if none. | |
900 | ||
901 | The returned pointer remains valid as long as \bt_p{stream_class} | |
902 | is not modified. | |
903 | @endparblock | |
904 | ||
905 | @bt_pre_not_null{stream_class} | |
906 | ||
907 | @sa bt_stream_class_set_name() — | |
908 | Sets the name of a stream class. | |
909 | */ | |
910 | extern const char *bt_stream_class_get_name( | |
4c81a2b7 | 911 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
912 | |
913 | /*! | |
914 | @brief | |
915 | Status codes for bt_stream_class_set_default_clock_class(). | |
916 | */ | |
917 | typedef enum bt_stream_class_set_default_clock_class_status { | |
918 | /*! | |
919 | @brief | |
920 | Success. | |
921 | */ | |
922 | BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK, | |
923 | } bt_stream_class_set_default_clock_class_status; | |
924 | ||
925 | /*! | |
926 | @brief | |
927 | Sets the default \bt_clock_cls of the stream class | |
928 | \bt_p{stream_class} to \bt_p{clock_class}. | |
929 | ||
930 | See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" | |
931 | property. | |
932 | ||
933 | @param[in] stream_class | |
934 | Stream class of which to set the default clock class to | |
935 | \bt_p{clock_class}. | |
936 | @param[in] clock_class | |
937 | New default clock class of \bt_p{stream_class}. | |
938 | ||
939 | @retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK | |
940 | Success. | |
941 | ||
942 | @bt_pre_not_null{stream_class} | |
943 | @bt_pre_hot{stream_class} | |
944 | @bt_pre_not_null{clock_class} | |
945 | ||
946 | @sa bt_stream_class_borrow_default_clock_class() — | |
947 | Borrows the default clock class of a stream class. | |
948 | @sa bt_stream_class_borrow_default_clock_class_const() — | |
949 | Borrows the default clock class of a stream class (\c const version). | |
950 | */ | |
951 | extern bt_stream_class_set_default_clock_class_status | |
952 | bt_stream_class_set_default_clock_class( | |
2e90378a | 953 | bt_stream_class *stream_class, |
4c81a2b7 | 954 | bt_clock_class *clock_class) __BT_NOEXCEPT; |
43c59509 PP |
955 | |
956 | /*! | |
957 | @brief | |
958 | Borrows the default \bt_clock_cls from the stream class | |
959 | \bt_p{stream_class}. | |
960 | ||
961 | See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" | |
962 | property. | |
2e90378a | 963 | |
43c59509 PP |
964 | If \bt_p{stream_class} has no default clock class, this function |
965 | returns \c NULL. | |
966 | ||
967 | @param[in] stream_class | |
968 | Stream class from which to borrow the default clock class. | |
969 | ||
970 | @returns | |
971 | \em Borrowed reference of the default clock class of | |
972 | \bt_p{stream_class}, or \c NULL if none. | |
973 | ||
974 | @bt_pre_not_null{stream_class} | |
975 | ||
976 | @sa bt_stream_class_set_default_clock_class() — | |
977 | Sets the default clock class of a stream class. | |
978 | @sa bt_stream_class_borrow_default_clock_class_const() — | |
979 | \c const version of this function. | |
980 | */ | |
981 | extern bt_clock_class *bt_stream_class_borrow_default_clock_class( | |
4c81a2b7 | 982 | bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
983 | |
984 | /*! | |
985 | @brief | |
986 | Borrows the default \bt_clock_cls from the stream class | |
987 | \bt_p{stream_class} (\c const version). | |
988 | ||
989 | See bt_stream_class_borrow_default_clock_class(). | |
990 | */ | |
991 | extern const bt_clock_class * | |
992 | bt_stream_class_borrow_default_clock_class_const( | |
4c81a2b7 | 993 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
994 | |
995 | /*! | |
996 | @brief | |
997 | Status codes for bt_stream_class_set_packet_context_field_class() | |
998 | and bt_stream_class_set_event_common_context_field_class(). | |
999 | */ | |
d24d5663 | 1000 | typedef enum bt_stream_class_set_field_class_status { |
43c59509 PP |
1001 | /*! |
1002 | @brief | |
1003 | Success. | |
1004 | */ | |
d24d5663 | 1005 | BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1006 | |
1007 | /*! | |
1008 | @brief | |
1009 | Out of memory. | |
1010 | */ | |
1011 | BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 PP |
1012 | } bt_stream_class_set_field_class_status; |
1013 | ||
43c59509 PP |
1014 | /*! |
1015 | @brief | |
1016 | Sets the packet context \bt_fc of the stream class | |
1017 | \bt_p{stream_class} to \bt_p{field_class}. | |
1018 | ||
1019 | See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class" | |
1020 | property. | |
1021 | ||
1022 | \bt_p{stream_class} must support packets (see | |
1023 | bt_stream_class_set_supports_packets()). | |
26fc5aed | 1024 | |
43c59509 PP |
1025 | @param[in] stream_class |
1026 | Stream class of which to set the packet context field class to | |
1027 | \bt_p{field_class}. | |
1028 | @param[in] field_class | |
1029 | New packet context field class of \bt_p{stream_class}. | |
1030 | ||
1031 | @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK | |
1032 | Success. | |
1033 | @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR | |
1034 | Out of memory. | |
1035 | ||
1036 | @bt_pre_not_null{stream_class} | |
1037 | @bt_pre_hot{stream_class} | |
1038 | @pre | |
1039 | <code>bt_stream_class_supports_packets(stream_class)</code> | |
1040 | returns #BT_TRUE. | |
1041 | @bt_pre_not_null{field_class} | |
1042 | @bt_pre_is_struct_fc{field_class} | |
1043 | @pre | |
1044 | \bt_p{field_class}, or any of its contained field classes, | |
1045 | is not already part of a stream class or of an \bt_ev_cls. | |
1046 | @pre | |
1047 | If any of the field classes recursively contained in | |
1048 | \bt_p{field_class} has a | |
1049 | \ref api-tir-fc-link "link to another field class", it must honor | |
1050 | the field class link rules. | |
1051 | @pre | |
1052 | If any of the field classes recursively contained in | |
1053 | \bt_p{field_class} has a | |
1054 | \ref api-tir-fc-link "link to another field class", it must honor | |
1055 | the field class link rules. | |
1056 | ||
1057 | @bt_post_success_frozen{field_class} | |
1058 | ||
1059 | @sa bt_stream_class_borrow_packet_context_field_class() — | |
1060 | Borrows the packet context field class of a stream class. | |
1061 | @sa bt_stream_class_borrow_packet_context_field_class_const() — | |
1062 | Borrows the packet context field class of a stream class | |
1063 | (\c const version). | |
1064 | */ | |
d24d5663 | 1065 | extern bt_stream_class_set_field_class_status |
a6ae8edc | 1066 | bt_stream_class_set_packet_context_field_class( |
b19ff26f | 1067 | bt_stream_class *stream_class, |
4c81a2b7 | 1068 | bt_field_class *field_class) __BT_NOEXCEPT; |
56e18c4c | 1069 | |
43c59509 PP |
1070 | /*! |
1071 | @brief | |
1072 | Borrows the packet context \bt_fc from the stream class | |
1073 | \bt_p{stream_class}. | |
1074 | ||
1075 | See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class" | |
1076 | property. | |
1077 | ||
1078 | If \bt_p{stream_class} has no packet context field class, this function | |
1079 | returns \c NULL. | |
1080 | ||
1081 | @param[in] stream_class | |
1082 | Stream class from which to borrow the packet context field class. | |
1083 | ||
1084 | @returns | |
1085 | \em Borrowed reference of the packet context field class of | |
1086 | \bt_p{stream_class}, or \c NULL if none. | |
1087 | ||
1088 | @bt_pre_not_null{stream_class} | |
1089 | ||
1090 | @sa bt_stream_class_set_packet_context_field_class() — | |
1091 | Sets the packet context field class of a stream class. | |
1092 | @sa bt_stream_class_borrow_packet_context_field_class_const() — | |
1093 | \c const version of this function. | |
1094 | */ | |
740faaf4 PP |
1095 | extern bt_field_class * |
1096 | bt_stream_class_borrow_packet_context_field_class( | |
4c81a2b7 | 1097 | bt_stream_class *stream_class) __BT_NOEXCEPT; |
740faaf4 | 1098 | |
43c59509 PP |
1099 | /*! |
1100 | @brief | |
1101 | Borrows the packet context \bt_fc from the stream class | |
1102 | \bt_p{stream_class} (\c const version). | |
1103 | ||
1104 | See bt_stream_class_borrow_packet_context_field_class(). | |
1105 | */ | |
1106 | extern const bt_field_class * | |
1107 | bt_stream_class_borrow_packet_context_field_class_const( | |
4c81a2b7 | 1108 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1109 | |
1110 | /*! | |
1111 | @brief | |
1112 | Sets the event common context \bt_fc of the stream class | |
1113 | \bt_p{stream_class} to \bt_p{field_class}. | |
1114 | ||
1115 | See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class" | |
1116 | property. | |
1117 | ||
1118 | @param[in] stream_class | |
1119 | Stream class of which to set the event common context field class to | |
1120 | \bt_p{field_class}. | |
1121 | @param[in] field_class | |
1122 | New event common context field class of \bt_p{stream_class}. | |
1123 | ||
1124 | @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK | |
1125 | Success. | |
1126 | @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR | |
1127 | Out of memory. | |
1128 | ||
1129 | @bt_pre_not_null{stream_class} | |
1130 | @bt_pre_hot{stream_class} | |
1131 | @bt_pre_not_null{field_class} | |
1132 | @bt_pre_is_struct_fc{field_class} | |
1133 | @pre | |
1134 | \bt_p{field_class}, or any of its contained field classes, | |
1135 | is not already part of a stream class or of an \bt_ev_cls. | |
1136 | @pre | |
1137 | If any of the field classes recursively contained in | |
1138 | \bt_p{field_class} has a | |
1139 | \ref api-tir-fc-link "link to another field class", it must honor | |
1140 | the field class link rules. | |
1141 | ||
1142 | @bt_post_success_frozen{field_class} | |
1143 | ||
1144 | @sa bt_stream_class_borrow_event_common_context_field_class() — | |
1145 | Borrows the event common context field class of a stream class. | |
1146 | @sa bt_stream_class_borrow_event_common_context_field_class_const() — | |
1147 | Borrows the event common context field class of a stream class | |
1148 | (\c const version). | |
1149 | */ | |
d24d5663 | 1150 | extern bt_stream_class_set_field_class_status |
40f4ba76 | 1151 | bt_stream_class_set_event_common_context_field_class( |
b19ff26f | 1152 | bt_stream_class *stream_class, |
4c81a2b7 | 1153 | bt_field_class *field_class) __BT_NOEXCEPT; |
56e18c4c | 1154 | |
43c59509 PP |
1155 | /*! |
1156 | @brief | |
1157 | Borrows the event common context \bt_fc from the stream class | |
1158 | \bt_p{stream_class}. | |
1159 | ||
1160 | See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class" | |
1161 | property. | |
1162 | ||
1163 | If \bt_p{stream_class} has no event common context field class, this | |
1164 | function returns \c NULL. | |
1165 | ||
1166 | @param[in] stream_class | |
1167 | Stream class from which to borrow the event common context | |
1168 | field class. | |
1169 | ||
1170 | @returns | |
1171 | \em Borrowed reference of the event common context field class of | |
1172 | \bt_p{stream_class}, or \c NULL if none. | |
1173 | ||
1174 | @bt_pre_not_null{stream_class} | |
1175 | ||
1176 | @sa bt_stream_class_set_event_common_context_field_class() — | |
1177 | Sets the event common context field class of a stream class. | |
1178 | @sa bt_stream_class_borrow_event_common_context_field_class_const() — | |
1179 | \c const version of this function. | |
1180 | */ | |
1181 | ||
740faaf4 PP |
1182 | extern bt_field_class * |
1183 | bt_stream_class_borrow_event_common_context_field_class( | |
4c81a2b7 | 1184 | bt_stream_class *stream_class) __BT_NOEXCEPT; |
740faaf4 | 1185 | |
43c59509 PP |
1186 | /*! |
1187 | @brief | |
1188 | Borrows the event common context \bt_fc from the stream class | |
1189 | \bt_p{stream_class} (\c const version()). | |
56e18c4c | 1190 | |
43c59509 PP |
1191 | See bt_stream_class_borrow_event_common_context_field_class(). |
1192 | */ | |
1193 | extern const bt_field_class * | |
1194 | bt_stream_class_borrow_event_common_context_field_class_const( | |
4c81a2b7 | 1195 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
56e18c4c | 1196 | |
43c59509 PP |
1197 | /*! |
1198 | @brief | |
1199 | Sets whether or not the stream class \bt_p{stream_class} | |
1200 | automatically assigns a numeric ID to an \bt_ev_cls you create and | |
1201 | add to it. | |
56e18c4c | 1202 | |
43c59509 PP |
1203 | See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?" |
1204 | property. | |
d24d5663 | 1205 | |
43c59509 PP |
1206 | @param[in] stream_class |
1207 | Stream class of which to set whether or not it assigns automatic | |
1208 | event class IDs. | |
1209 | @param[in] assigns_automatic_event_class_id | |
1210 | #BT_TRUE to make \bt_p{stream_class} assign automatic event class | |
1211 | IDs. | |
1212 | ||
1213 | @bt_pre_not_null{stream_class} | |
1214 | @bt_pre_hot{stream_class} | |
1215 | ||
1216 | @sa bt_stream_class_assigns_automatic_event_class_id() — | |
1217 | Returns whether or not a stream class automatically assigns | |
1218 | event class IDs. | |
1219 | */ | |
1220 | extern void bt_stream_class_set_assigns_automatic_event_class_id( | |
b19ff26f | 1221 | bt_stream_class *stream_class, |
4c81a2b7 | 1222 | bt_bool assigns_automatic_event_class_id) __BT_NOEXCEPT; |
43c59509 PP |
1223 | |
1224 | /*! | |
1225 | @brief | |
1226 | Returns whether or not the stream class \bt_p{stream_class} | |
1227 | automatically assigns a numeric ID to an \bt_ev_cls you create | |
1228 | and add to it. | |
1229 | ||
1230 | See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?" | |
1231 | property. | |
1232 | ||
1233 | @param[in] stream_class | |
1234 | Stream class of which to get whether or not it assigns automatic | |
1235 | event class IDs. | |
1236 | ||
1237 | @returns | |
1238 | #BT_TRUE if \bt_p{stream_class} automatically | |
1239 | assigns event class IDs. | |
1240 | ||
1241 | @bt_pre_not_null{stream_class} | |
1242 | ||
1243 | @sa bt_stream_class_set_assigns_automatic_event_class_id() — | |
1244 | Sets whether or not a stream class automatically assigns | |
1245 | event class IDs. | |
1246 | */ | |
1247 | extern bt_bool bt_stream_class_assigns_automatic_event_class_id( | |
4c81a2b7 | 1248 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1249 | |
1250 | /*! | |
1251 | @brief | |
1252 | Sets whether or not the stream class \bt_p{stream_class} | |
1253 | automatically assigns a numeric ID to a \bt_stream you create from | |
1254 | it. | |
1255 | ||
1256 | See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?" | |
1257 | property. | |
1258 | ||
1259 | @param[in] stream_class | |
1260 | Stream class of which to set whether or not it assigns automatic | |
1261 | stream IDs. | |
1262 | @param[in] assigns_automatic_stream_id | |
1263 | #BT_TRUE to make \bt_p{stream_class} assign automatic stream | |
1264 | IDs. | |
1265 | ||
1266 | @bt_pre_not_null{stream_class} | |
1267 | @bt_pre_hot{stream_class} | |
1268 | ||
1269 | @sa bt_stream_class_assigns_automatic_stream_id() — | |
1270 | Returns whether or not a stream class automatically assigns | |
1271 | stream IDs. | |
1272 | */ | |
1273 | extern void bt_stream_class_set_assigns_automatic_stream_id( | |
4c81a2b7 PP |
1274 | bt_stream_class *stream_class, |
1275 | bt_bool assigns_automatic_stream_id) __BT_NOEXCEPT; | |
43c59509 PP |
1276 | |
1277 | /*! | |
1278 | @brief | |
1279 | Returns whether or not the stream class \bt_p{stream_class} | |
1280 | automatically assigns a numeric ID to a \bt_stream you create | |
1281 | from it. | |
1282 | ||
1283 | See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?" | |
1284 | property. | |
1285 | ||
1286 | @param[in] stream_class | |
1287 | Stream class of which to get whether or not it assigns automatic | |
1288 | stream IDs. | |
1289 | ||
1290 | @returns | |
1291 | #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs. | |
1292 | ||
1293 | @bt_pre_not_null{stream_class} | |
1294 | ||
1295 | @sa bt_stream_class_set_assigns_automatic_stream_id() — | |
1296 | Sets whether or not a stream class automatically assigns | |
1297 | stream IDs. | |
1298 | */ | |
1299 | extern bt_bool bt_stream_class_assigns_automatic_stream_id( | |
4c81a2b7 | 1300 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1301 | |
1302 | /*! | |
1303 | @brief | |
1304 | Sets whether or not the instances (\bt_p_stream) of the | |
1305 | stream class \bt_p{stream_class} have \bt_p_pkt and, if so, | |
1306 | if those packets have beginning and/or end default | |
1307 | \bt_p_cs. | |
1308 | ||
1309 | See the | |
1310 | \ref api-tir-stream-cls-prop-supports-pkt "supports packets?", | |
1311 | \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?", | |
1312 | and | |
1313 | \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?" | |
1314 | properties. | |
1315 | ||
1316 | @param[in] stream_class | |
1317 | Stream class of which to set whether or not its streams have | |
1318 | packets. | |
1319 | @param[in] supports_packets | |
1320 | #BT_TRUE to make the streams of \bt_p{stream_class} have packets. | |
1321 | @param[in] with_beginning_default_clock_snapshot | |
1322 | #BT_TRUE to make the packets of the streams of \bt_p{stream_class} | |
1323 | have a beginning default clock snapshot. | |
1324 | @param[in] with_end_default_clock_snapshot | |
1325 | #BT_TRUE to make the packets of the streams of \bt_p{stream_class} | |
1326 | have an end default clock snapshot. | |
1327 | ||
1328 | @bt_pre_not_null{stream_class} | |
1329 | @bt_pre_hot{stream_class} | |
1330 | @pre | |
1331 | <strong>If \bt_p{with_beginning_default_clock_snapshot} is | |
1332 | #BT_TRUE</strong>, | |
1333 | \bt_p{supports_packets} is also #BT_TRUE. | |
1334 | @pre | |
1335 | <strong>If \bt_p{with_beginning_default_clock_snapshot} is | |
1336 | #BT_TRUE</strong>, | |
1337 | \bt_p{supports_packets} is also #BT_TRUE. | |
1338 | @pre | |
1339 | <strong>If \bt_p{with_beginning_default_clock_snapshot} or | |
1340 | \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>, | |
1341 | \bt_p{stream_class} has a | |
1342 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
1343 | ||
1344 | @sa bt_stream_class_supports_packets() — | |
1345 | Returns whether or not a stream class's streams have packets. | |
1346 | @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() — | |
1347 | Returns whether or not the packets of a stream class's streams | |
1348 | have a beginning default clock snapshot. | |
1349 | @sa bt_stream_class_packets_have_end_default_clock_snapshot() — | |
1350 | Returns whether or not the packets of a stream class's streams | |
1351 | have an end default clock snapshot. | |
1352 | */ | |
1353 | extern void bt_stream_class_set_supports_packets( | |
1354 | bt_stream_class *stream_class, bt_bool supports_packets, | |
1355 | bt_bool with_beginning_default_clock_snapshot, | |
4c81a2b7 | 1356 | bt_bool with_end_default_clock_snapshot) __BT_NOEXCEPT; |
43c59509 PP |
1357 | |
1358 | /*! | |
1359 | @brief | |
1360 | Returns whether or not the instances (\bt_p_stream) of the | |
1361 | stream class \bt_p{stream_class} have \bt_p_pkt. | |
1362 | ||
1363 | See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?" | |
1364 | property. | |
1365 | ||
1366 | @param[in] stream_class | |
1367 | Stream class of which to get whether or not its streams have | |
1368 | packets. | |
1369 | ||
1370 | @returns | |
1371 | #BT_TRUE if the streams of \bt_p{stream_class} have packets. | |
1372 | ||
1373 | @bt_pre_not_null{stream_class} | |
1374 | ||
1375 | @sa bt_stream_class_set_supports_packets() — | |
1376 | Sets whether or not a stream class's streams have packets. | |
1377 | */ | |
1378 | extern bt_bool bt_stream_class_supports_packets( | |
4c81a2b7 | 1379 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1380 | |
1381 | /*! | |
1382 | @brief | |
1383 | Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream) | |
1384 | of the stream class \bt_p{stream_class} have a beginning | |
1385 | default \bt_cs. | |
1386 | ||
1387 | See the | |
1388 | \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?" | |
1389 | property. | |
1390 | ||
1391 | @param[in] stream_class | |
1392 | Stream class of which to get whether or not its streams's packets | |
1393 | have a beginning default clock snapshot. | |
1394 | ||
1395 | @returns | |
1396 | #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a | |
1397 | beginning default clock snapshot. | |
1398 | ||
1399 | @bt_pre_not_null{stream_class} | |
1400 | ||
1401 | @sa bt_stream_class_set_supports_packets() — | |
1402 | Sets whether or not a stream class's streams have packets. | |
1403 | @sa bt_stream_class_packets_have_end_default_clock_snapshot() — | |
1404 | Returns whether or not the packets of a stream class's streams | |
1405 | have an end default clock snapshot. | |
1406 | */ | |
1407 | extern bt_bool bt_stream_class_packets_have_beginning_default_clock_snapshot( | |
4c81a2b7 | 1408 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1409 | |
1410 | /*! | |
1411 | @brief | |
1412 | Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream) | |
1413 | of the stream class \bt_p{stream_class} have an end | |
1414 | default \bt_cs. | |
1415 | ||
1416 | See the | |
1417 | \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?" | |
1418 | property. | |
1419 | ||
1420 | @param[in] stream_class | |
1421 | Stream class of which to get whether or not its streams's packets | |
1422 | have an end default clock snapshot. | |
1423 | ||
1424 | @returns | |
1425 | #BT_TRUE if the packets of the streams of \bt_p{stream_class} have | |
1426 | an end default clock snapshot. | |
1427 | ||
1428 | @bt_pre_not_null{stream_class} | |
1429 | ||
1430 | @sa bt_stream_class_set_supports_packets() — | |
1431 | Sets whether or not a stream class's streams have packets. | |
1432 | @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() — | |
1433 | Returns whether or not the packets of a stream class's streams | |
1434 | have a beginning default clock snapshot. | |
1435 | */ | |
1436 | extern bt_bool bt_stream_class_packets_have_end_default_clock_snapshot( | |
4c81a2b7 | 1437 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1438 | |
1439 | /*! | |
1440 | @brief | |
1441 | Sets whether or not the instances (\bt_p_stream) of the | |
1442 | stream class \bt_p{stream_class} can have discarded events and, | |
1443 | if so, if the \bt_p_disc_ev_msg of those streams have | |
1444 | beginning and end default \bt_p_cs. | |
1445 | ||
1446 | See the | |
1447 | \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?" | |
1448 | and | |
1449 | \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?" | |
1450 | properties. | |
1451 | ||
1452 | @param[in] stream_class | |
1453 | Stream class of which to set whether or not its streams can have | |
1454 | discarded events. | |
1455 | @param[in] supports_discarded_events | |
1456 | #BT_TRUE to make the streams of \bt_p{stream_class} be able to | |
1457 | have discarded events. | |
1458 | @param[in] with_default_clock_snapshots | |
1459 | #BT_TRUE to make the discarded events messages the streams of | |
1460 | \bt_p{stream_class} have beginning and end default clock snapshots. | |
1461 | ||
1462 | @bt_pre_not_null{stream_class} | |
1463 | @bt_pre_hot{stream_class} | |
1464 | @pre | |
1465 | <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>, | |
1466 | \bt_p{supports_discarded_events} is also #BT_TRUE. | |
1467 | @pre | |
1468 | <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>, | |
1469 | \bt_p{stream_class} has a | |
1470 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
1471 | ||
1472 | @sa bt_stream_class_supports_discarded_events() — | |
1473 | Returns whether or not a stream class's streams can have | |
1474 | discarded events. | |
1475 | @sa bt_stream_class_discarded_events_have_default_clock_snapshots() — | |
1476 | Returns whether or not the discarded events messages of a | |
1477 | stream class's streams have beginning and end default clock | |
1478 | snapshots. | |
1479 | */ | |
1480 | extern void bt_stream_class_set_supports_discarded_events( | |
1481 | bt_stream_class *stream_class, | |
1482 | bt_bool supports_discarded_events, | |
4c81a2b7 | 1483 | bt_bool with_default_clock_snapshots) __BT_NOEXCEPT; |
43c59509 PP |
1484 | |
1485 | /*! | |
1486 | @brief | |
1487 | Returns whether or not the instances (\bt_p_stream) of the | |
1488 | stream class \bt_p{stream_class} can have discarded events. | |
1489 | ||
1490 | See the | |
1491 | \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?" | |
1492 | property. | |
1493 | ||
1494 | @param[in] stream_class | |
1495 | Stream class of which to get whether or not its streams can have | |
1496 | discarded events. | |
1497 | ||
1498 | @returns | |
1499 | #BT_TRUE if the streams of \bt_p{stream_class} can have discarded | |
1500 | events. | |
1501 | ||
1502 | @bt_pre_not_null{stream_class} | |
1503 | ||
1504 | @sa bt_stream_class_set_supports_discarded_events() — | |
1505 | Sets whether or not a stream class's streams can have discarded | |
1506 | events. | |
1507 | */ | |
1508 | extern bt_bool bt_stream_class_supports_discarded_events( | |
4c81a2b7 | 1509 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1510 | |
1511 | /*! | |
1512 | @brief | |
1513 | Returns whether or not the \bt_p_disc_ev_msg of the instances | |
1514 | (\bt_p_stream) of the stream class \bt_p{stream_class} have | |
1515 | beginning and end default \bt_p_cs. | |
1516 | ||
1517 | See the | |
1518 | \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?" | |
1519 | property. | |
1520 | ||
1521 | @param[in] stream_class | |
1522 | Stream class of which to get whether or not its streams's discarded | |
1523 | events messages have a beginning and end default clock snapshots. | |
1524 | ||
1525 | @returns | |
1526 | #BT_TRUE if the discarded events messages of the streams of | |
1527 | \bt_p{stream_class} have beginning and end default clock snapshots. | |
1528 | ||
1529 | @bt_pre_not_null{stream_class} | |
1530 | ||
1531 | @sa bt_stream_class_set_supports_discarded_events() — | |
1532 | Sets whether or not a stream class's streams can have discarded | |
1533 | events. | |
1534 | */ | |
1535 | extern bt_bool bt_stream_class_discarded_events_have_default_clock_snapshots( | |
4c81a2b7 | 1536 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1537 | |
1538 | /*! | |
1539 | @brief | |
1540 | Sets whether or not the instances (\bt_p_stream) of the | |
1541 | stream class \bt_p{stream_class} can have discarded packets and, | |
1542 | if so, if the \bt_p_disc_pkt_msg of those streams have | |
1543 | beginning and end default \bt_p_cs. | |
1544 | ||
1545 | See the | |
1546 | \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?" | |
1547 | and | |
1548 | \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?" | |
1549 | properties. | |
1550 | ||
1551 | \bt_p{stream_class} must support packets (see | |
1552 | bt_stream_class_set_supports_packets()). | |
1553 | ||
1554 | @param[in] stream_class | |
1555 | Stream class of which to set whether or not its streams can have | |
1556 | discarded packets. | |
1557 | @param[in] supports_discarded_packets | |
1558 | #BT_TRUE to make the streams of \bt_p{stream_class} be able to | |
1559 | have discarded packets. | |
1560 | @param[in] with_default_clock_snapshots | |
1561 | #BT_TRUE to make the discarded packets messages the streams of | |
1562 | \bt_p{stream_class} have beginning and end default clock snapshots. | |
1563 | ||
1564 | @bt_pre_not_null{stream_class} | |
1565 | @bt_pre_hot{stream_class} | |
1566 | @pre | |
1567 | <code>bt_stream_class_supports_packets(stream_class)</code> | |
1568 | returns #BT_TRUE. | |
1569 | @pre | |
1570 | <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>, | |
1571 | \bt_p{supports_discarded_packets} is also #BT_TRUE. | |
1572 | @pre | |
1573 | <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>, | |
1574 | \bt_p{stream_class} has a | |
1575 | \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". | |
1576 | ||
1577 | @sa bt_stream_class_supports_discarded_packets() — | |
1578 | Returns whether or not a stream class's streams can have | |
1579 | discarded packets. | |
1580 | @sa bt_stream_class_discarded_packets_have_default_clock_snapshots() — | |
1581 | Returns whether or not the discarded packets messages of a | |
1582 | stream class's streams have beginning and end default clock | |
1583 | snapshots. | |
1584 | */ | |
1585 | extern void bt_stream_class_set_supports_discarded_packets( | |
1586 | bt_stream_class *stream_class, | |
1587 | bt_bool supports_discarded_packets, | |
4c81a2b7 | 1588 | bt_bool with_default_clock_snapshots) __BT_NOEXCEPT; |
43c59509 PP |
1589 | |
1590 | /*! | |
1591 | @brief | |
1592 | Returns whether or not the instances (\bt_p_stream) of the | |
1593 | stream class \bt_p{stream_class} can have discarded packets. | |
1594 | ||
1595 | See the | |
1596 | \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?" | |
1597 | property. | |
1598 | ||
1599 | @param[in] stream_class | |
1600 | Stream class of which to get whether or not its streams can have | |
1601 | discarded packets. | |
1602 | ||
1603 | @returns | |
1604 | #BT_TRUE if the streams of \bt_p{stream_class} can have discarded | |
1605 | packets. | |
1606 | ||
1607 | @bt_pre_not_null{stream_class} | |
1608 | ||
1609 | @sa bt_stream_class_set_supports_discarded_packets() — | |
1610 | Sets whether or not a stream class's streams can have discarded | |
1611 | packets. | |
1612 | */ | |
1613 | extern bt_bool bt_stream_class_supports_discarded_packets( | |
4c81a2b7 | 1614 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1615 | |
1616 | /*! | |
1617 | @brief | |
1618 | Returns whether or not the \bt_p_disc_pkt_msg of the instances | |
1619 | (\bt_p_stream) of the stream class \bt_p{stream_class} have | |
1620 | beginning and end default \bt_p_cs. | |
1621 | ||
1622 | See the | |
1623 | \ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?" | |
1624 | property. | |
1625 | ||
1626 | @param[in] stream_class | |
1627 | Stream class of which to get whether or not its streams's discarded | |
1628 | packets messages have a beginning and end default clock snapshots. | |
1629 | ||
1630 | @returns | |
1631 | #BT_TRUE if the discarded packets messages of the streams of | |
1632 | \bt_p{stream_class} have beginning and end default clock snapshots. | |
1633 | ||
1634 | @bt_pre_not_null{stream_class} | |
1635 | ||
1636 | @sa bt_stream_class_set_supports_discarded_packets() — | |
1637 | Sets whether or not a stream class's streams can have discarded | |
1638 | packets. | |
1639 | */ | |
1640 | extern bt_bool bt_stream_class_discarded_packets_have_default_clock_snapshots( | |
4c81a2b7 | 1641 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1642 | |
1643 | /*! | |
1644 | @brief | |
1645 | Sets the user attributes of the stream class \bt_p{stream_class} to | |
1646 | \bt_p{user_attributes}. | |
1647 | ||
1648 | See the \ref api-tir-stream-cls-prop-user-attrs "user attributes" | |
1649 | property. | |
1650 | ||
1651 | @note | |
1652 | When you create a default stream class with bt_stream_class_create() | |
1653 | or bt_stream_class_create_with_id(), the stream class's initial user | |
1654 | attributes is an empty \bt_map_val. Therefore you can borrow it with | |
1655 | bt_stream_class_borrow_user_attributes() and fill it directly | |
1656 | instead of setting a new one with this function. | |
1657 | ||
1658 | @param[in] stream_class | |
1659 | Stream class of which to set the user attributes to | |
1660 | \bt_p{user_attributes}. | |
1661 | @param[in] user_attributes | |
1662 | New user attributes of \bt_p{stream_class}. | |
1663 | ||
1664 | @bt_pre_not_null{stream_class} | |
1665 | @bt_pre_hot{stream_class} | |
1666 | @bt_pre_not_null{user_attributes} | |
1667 | @bt_pre_is_map_val{user_attributes} | |
1668 | ||
1669 | @sa bt_stream_class_borrow_user_attributes() — | |
1670 | Borrows the user attributes of a stream class. | |
1671 | */ | |
1672 | extern void bt_stream_class_set_user_attributes( | |
4c81a2b7 PP |
1673 | bt_stream_class *stream_class, |
1674 | const bt_value *user_attributes) __BT_NOEXCEPT; | |
43c59509 PP |
1675 | |
1676 | /*! | |
1677 | @brief | |
1678 | Borrows the user attributes of the stream class \bt_p{stream_class}. | |
1679 | ||
1680 | See the \ref api-tir-stream-cls-prop-user-attrs "user attributes" | |
1681 | property. | |
1682 | ||
1683 | @note | |
1684 | When you create a default stream class with bt_stream_class_create() | |
1685 | or bt_stream_class_create_with_id(), the stream class's initial user | |
1686 | attributes is an empty \bt_map_val. | |
1687 | ||
1688 | @param[in] stream_class | |
1689 | Stream class from which to borrow the user attributes. | |
1690 | ||
1691 | @returns | |
1692 | User attributes of \bt_p{stream_class} (a \bt_map_val). | |
1693 | ||
1694 | @bt_pre_not_null{stream_class} | |
1695 | ||
1696 | @sa bt_stream_class_set_user_attributes() — | |
1697 | Sets the user attributes of a stream class. | |
1698 | @sa bt_stream_class_borrow_user_attributes_const() — | |
1699 | \c const version of this function. | |
1700 | */ | |
1701 | extern bt_value *bt_stream_class_borrow_user_attributes( | |
4c81a2b7 | 1702 | bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1703 | |
1704 | /*! | |
1705 | @brief | |
1706 | Borrows the user attributes of the stream class \bt_p{stream_class} | |
1707 | (\c const version). | |
1708 | ||
1709 | See bt_stream_class_borrow_user_attributes(). | |
1710 | */ | |
1711 | extern const bt_value *bt_stream_class_borrow_user_attributes_const( | |
4c81a2b7 | 1712 | const bt_stream_class *stream_class) __BT_NOEXCEPT; |
43c59509 PP |
1713 | |
1714 | /*! @} */ | |
1715 | ||
1716 | /*! | |
1717 | @name Reference count | |
1718 | @{ | |
1719 | */ | |
1720 | ||
1721 | /*! | |
1722 | @brief | |
1723 | Increments the \ref api-fund-shared-object "reference count" of | |
1724 | the stream class \bt_p{stream_class}. | |
1725 | ||
1726 | @param[in] stream_class | |
1727 | @parblock | |
1728 | Stream class of which to increment the reference count. | |
1729 | ||
1730 | Can be \c NULL. | |
1731 | @endparblock | |
1732 | ||
1733 | @sa bt_stream_class_put_ref() — | |
1734 | Decrements the reference count of a stream class. | |
1735 | */ | |
4c81a2b7 PP |
1736 | extern void bt_stream_class_get_ref( |
1737 | const bt_stream_class *stream_class) __BT_NOEXCEPT; | |
43c59509 PP |
1738 | |
1739 | /*! | |
1740 | @brief | |
1741 | Decrements the \ref api-fund-shared-object "reference count" of | |
1742 | the stream class \bt_p{stream_class}. | |
1743 | ||
1744 | @param[in] stream_class | |
1745 | @parblock | |
1746 | Stream class of which to decrement the reference count. | |
1747 | ||
1748 | Can be \c NULL. | |
1749 | @endparblock | |
1750 | ||
1751 | @sa bt_stream_class_get_ref() — | |
1752 | Increments the reference count of a stream class. | |
1753 | */ | |
4c81a2b7 PP |
1754 | extern void bt_stream_class_put_ref( |
1755 | const bt_stream_class *stream_class) __BT_NOEXCEPT; | |
43c59509 PP |
1756 | |
1757 | /*! | |
1758 | @brief | |
1759 | Decrements the reference count of the stream class | |
1760 | \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL. | |
1761 | ||
1762 | @param _stream_class | |
1763 | @parblock | |
1764 | Stream class of which to decrement the reference count. | |
1765 | ||
1766 | Can contain \c NULL. | |
1767 | @endparblock | |
1768 | ||
1769 | @bt_pre_assign_expr{_stream_class} | |
1770 | */ | |
1771 | #define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \ | |
1772 | do { \ | |
1773 | bt_stream_class_put_ref(_stream_class); \ | |
1774 | (_stream_class) = NULL; \ | |
1775 | } while (0) | |
1776 | ||
1777 | /*! | |
1778 | @brief | |
1779 | Decrements the reference count of the stream class \bt_p{_dst}, sets | |
1780 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
1781 | ||
1782 | This macro effectively moves a stream class reference from the expression | |
1783 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
1784 | \bt_p{_dst} reference. | |
1785 | ||
1786 | @param _dst | |
1787 | @parblock | |
1788 | Destination expression. | |
1789 | ||
1790 | Can contain \c NULL. | |
1791 | @endparblock | |
1792 | @param _src | |
1793 | @parblock | |
1794 | Source expression. | |
1795 | ||
1796 | Can contain \c NULL. | |
1797 | @endparblock | |
1798 | ||
1799 | @bt_pre_assign_expr{_dst} | |
1800 | @bt_pre_assign_expr{_src} | |
1801 | */ | |
1802 | #define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \ | |
1803 | do { \ | |
1804 | bt_stream_class_put_ref(_dst); \ | |
1805 | (_dst) = (_src); \ | |
1806 | (_src) = NULL; \ | |
1807 | } while (0) | |
1808 | ||
1809 | /*! @} */ | |
1810 | ||
1811 | /*! @} */ | |
56e18c4c | 1812 | |
56e18c4c PP |
1813 | #ifdef __cplusplus |
1814 | } | |
1815 | #endif | |
1816 | ||
924dc299 | 1817 | #endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_H */ |