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