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