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