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