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_TRACE_H |
8 | #define BABELTRACE2_TRACE_IR_TRACE_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 | ||
d24d5663 PP |
16 | #include <stdint.h> |
17 | ||
3fadfbc0 | 18 | #include <babeltrace2/types.h> |
56e18c4c | 19 | |
56e18c4c PP |
20 | #ifdef __cplusplus |
21 | extern "C" { | |
22 | #endif | |
23 | ||
43c59509 PP |
24 | /*! |
25 | @defgroup api-tir-trace Trace | |
26 | @ingroup api-tir | |
27 | ||
28 | @brief | |
29 | Trace (set of \bt_p_stream). | |
30 | ||
31 | A <strong><em>trace</em></strong> is a set of \bt_p_stream with | |
32 | properties: | |
33 | ||
34 | @image html trace-structure.png | |
35 | ||
36 | In the illustration above, notice that a trace is an instance of a | |
37 | \bt_trace_cls and that it contains streams. | |
38 | ||
39 | Borrow the class of a trace with bt_trace_borrow_class() and | |
40 | bt_trace_borrow_class_const(). | |
41 | ||
42 | A trace is a \ref api-tir "trace IR" data object. | |
43 | ||
44 | A trace is a \ref api-fund-shared-object "shared object": get a | |
45 | new reference with bt_trace_get_ref() and put an existing | |
46 | reference with bt_trace_put_ref(). | |
47 | ||
48 | Some library functions \ref api-fund-freezing "freeze" traces on | |
49 | success. The documentation of those functions indicate this | |
50 | postcondition. With a frozen trace, you can still: | |
51 | ||
52 | - Create \bt_p_stream from it with bt_stream_create() or | |
53 | bt_stream_create_with_id(). | |
54 | - Add a destruction listener to it with | |
55 | bt_trace_add_destruction_listener(). | |
56 | ||
57 | The type of a trace is #bt_trace. | |
58 | ||
59 | A trace contains \bt_p_stream. All the streams of a | |
60 | given trace have unique \ref api-tir-stream-prop-id "numeric IDs". | |
61 | Get the number of streams in a trace with bt_trace_get_stream_count(). | |
62 | Borrow a specific stream from a trace with | |
63 | bt_trace_borrow_stream_by_index(), | |
64 | bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(), | |
65 | or bt_trace_borrow_stream_by_id_const(). | |
66 | ||
67 | Create a default trace from a \bt_trace_cls with bt_trace_create(). | |
68 | ||
69 | Add to and remove a destruction listener from a trace with | |
70 | bt_trace_add_destruction_listener() and | |
71 | bt_trace_remove_destruction_listener(). | |
72 | ||
73 | <h1>Properties</h1> | |
74 | ||
75 | A trace has the following properties: | |
76 | ||
77 | <dl> | |
78 | <dt> | |
79 | \anchor api-tir-trace-prop-name | |
80 | \bt_dt_opt Name | |
81 | </dt> | |
82 | <dd> | |
83 | Name of the trace. | |
84 | ||
85 | Use bt_trace_set_name() and bt_trace_get_name(). | |
86 | </dd> | |
87 | ||
88 | <dt> | |
89 | \anchor api-tir-trace-prop-uuid | |
90 | \bt_dt_opt UUID | |
91 | </dt> | |
92 | <dd> | |
93 | <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a> | |
94 | of the trace. | |
95 | ||
96 | The trace's UUID uniquely identifies the trace. | |
97 | ||
98 | Use bt_trace_set_uuid() and bt_trace_get_uuid(). | |
99 | </dd> | |
100 | ||
101 | <dt> | |
102 | \anchor api-tir-trace-prop-env | |
103 | \bt_dt_opt Environment | |
104 | </dt> | |
105 | <dd> | |
106 | Generic key-value store which describes the environment of the trace | |
107 | (for example, the system's hostname, its network address, the | |
108 | tracer's name and version, and the rest). | |
109 | ||
110 | Trace environment keys are strings while values are signed integers | |
111 | or strings. | |
112 | ||
113 | Set a trace environment entry's value with | |
114 | bt_trace_set_environment_entry_integer() and | |
115 | bt_trace_set_environment_entry_string(). | |
116 | ||
117 | Get the number of environment entries in a trace with | |
118 | bt_trace_get_environment_entry_count(). | |
119 | ||
120 | Borrow an environment entry from a trace with | |
121 | bt_trace_borrow_environment_entry_value_by_name_const(). | |
122 | </dd> | |
123 | ||
124 | <dt> | |
125 | \anchor api-tir-trace-prop-user-attrs | |
126 | \bt_dt_opt User attributes | |
127 | </dt> | |
128 | <dd> | |
129 | User attributes of the trace. | |
56e18c4c | 130 | |
43c59509 PP |
131 | User attributes are custom attributes attached to a trace. |
132 | ||
133 | Use bt_trace_set_user_attributes(), | |
134 | bt_trace_borrow_user_attributes(), and | |
135 | bt_trace_borrow_user_attributes_const(). | |
136 | </dd> | |
137 | </dl> | |
138 | */ | |
139 | ||
140 | /*! @{ */ | |
141 | ||
142 | /*! | |
143 | @name Type | |
144 | @{ | |
145 | ||
146 | @typedef struct bt_trace bt_trace; | |
147 | ||
148 | @brief | |
149 | Trace. | |
150 | ||
151 | @} | |
152 | */ | |
153 | ||
154 | /*! | |
155 | @name Creation | |
156 | @{ | |
157 | */ | |
158 | ||
159 | /*! | |
160 | @brief | |
161 | Creates a default trace from the \bt_trace_cls \bt_p{trace_class}. | |
162 | ||
163 | This function instantiates \bt_p{trace_class}. | |
164 | ||
165 | On success, the returned trace has the following property values: | |
166 | ||
167 | <table> | |
168 | <tr> | |
169 | <th>Property | |
170 | <th>Value | |
171 | <tr> | |
172 | <td>\ref api-tir-trace-prop-name "Name" | |
173 | <td>\em None | |
174 | <tr> | |
175 | <td>\ref api-tir-trace-prop-uuid "UUID" | |
176 | <td>\em None | |
177 | <tr> | |
178 | <td>\ref api-tir-trace-prop-env "Environment" | |
179 | <td>Empty | |
180 | <tr> | |
181 | <td>\ref api-tir-trace-prop-user-attrs "User attributes" | |
182 | <td>Empty \bt_map_val | |
183 | </table> | |
184 | ||
185 | @param[in] trace_class | |
186 | Trace class from which to create the default trace. | |
187 | ||
188 | @returns | |
189 | New trace reference, or \c NULL on memory error. | |
190 | */ | |
b19ff26f | 191 | extern bt_trace *bt_trace_create(bt_trace_class *trace_class); |
56e18c4c | 192 | |
43c59509 | 193 | /*! @} */ |
c6962c96 | 194 | |
43c59509 PP |
195 | /*! |
196 | @name Class access | |
197 | @{ | |
198 | */ | |
199 | ||
200 | /*! | |
201 | @brief | |
202 | Borrows the \ref api-tir-trace-cls "class" of the trace | |
203 | \bt_p{trace}. | |
204 | ||
205 | @param[in] trace | |
206 | Trace of which to borrow the class. | |
207 | ||
208 | @returns | |
209 | \em Borrowed reference of the class of \bt_p{trace}. | |
210 | ||
211 | @bt_pre_not_null{trace} | |
212 | ||
213 | @sa bt_trace_borrow_class_const() — | |
214 | \c const version of this function. | |
215 | */ | |
216 | extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace); | |
217 | ||
218 | /*! | |
219 | @brief | |
220 | Borrows the \ref api-tir-trace-cls "class" of the trace | |
221 | \bt_p{trace} (\c const version). | |
222 | ||
223 | See bt_trace_borrow_class(). | |
224 | */ | |
225 | extern const bt_trace_class *bt_trace_borrow_class_const( | |
226 | const bt_trace *trace); | |
227 | ||
228 | /*! @} */ | |
229 | ||
230 | /*! | |
231 | @name Stream access | |
232 | @{ | |
233 | */ | |
c6962c96 | 234 | |
43c59509 PP |
235 | /*! |
236 | @brief | |
237 | Returns the number of \bt_p_stream contained in the trace | |
238 | \bt_p{trace}. | |
239 | ||
240 | @param[in] trace | |
241 | Trace of which to get the number of contained streams. | |
242 | ||
243 | @returns | |
244 | Number of contained streams in \bt_p{trace}. | |
245 | ||
246 | @bt_pre_not_null{trace} | |
247 | */ | |
248 | extern uint64_t bt_trace_get_stream_count(const bt_trace *trace); | |
249 | ||
250 | /*! | |
251 | @brief | |
252 | Borrows the \bt_stream at index \bt_p{index} from the | |
253 | trace \bt_p{trace}. | |
254 | ||
255 | @param[in] trace | |
256 | Trace from which to borrow the stream at index | |
257 | \bt_p{index}. | |
258 | @param[in] index | |
259 | Index of the stream to borrow from \bt_p{trace}. | |
260 | ||
261 | @returns | |
262 | @parblock | |
263 | \em Borrowed reference of the stream of | |
264 | \bt_p{trace} at index \bt_p{index}. | |
265 | ||
266 | The returned pointer remains valid as long as \bt_p{trace} | |
267 | exists. | |
268 | @endparblock | |
269 | ||
270 | @bt_pre_not_null{trace} | |
271 | @pre | |
272 | \bt_p{index} is less than the number of streams in | |
273 | \bt_p{trace} (as returned by | |
274 | bt_trace_get_stream_count()). | |
275 | ||
276 | @sa bt_trace_get_stream_count() — | |
277 | Returns the number of streams contained in a trace. | |
278 | @sa bt_trace_borrow_stream_by_index_const() — | |
279 | \c const version of this function. | |
280 | */ | |
281 | extern bt_stream *bt_trace_borrow_stream_by_index(bt_trace *trace, | |
282 | uint64_t index); | |
283 | ||
284 | /*! | |
285 | @brief | |
286 | Borrows the \bt_stream at index \bt_p{index} from the | |
287 | trace \bt_p{trace} (\c const version). | |
288 | ||
289 | See bt_trace_borrow_stream_by_index(). | |
290 | */ | |
291 | extern const bt_stream *bt_trace_borrow_stream_by_index_const( | |
292 | const bt_trace *trace, uint64_t index); | |
293 | ||
294 | /*! | |
295 | @brief | |
296 | Borrows the \bt_stream having the numeric ID \bt_p{id} from the | |
297 | trace \bt_p{trace}. | |
298 | ||
299 | If there's no stream having the numeric ID \bt_p{id} in | |
300 | \bt_p{trace}, this function returns \c NULL. | |
301 | ||
302 | @param[in] trace | |
303 | Trace from which to borrow the stream having the | |
304 | numeric ID \bt_p{id}. | |
305 | @param[in] id | |
306 | ID of the stream to borrow from \bt_p{trace}. | |
307 | ||
308 | @returns | |
309 | @parblock | |
310 | \em Borrowed reference of the stream of | |
311 | \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL | |
312 | if none. | |
313 | ||
314 | The returned pointer remains valid as long as \bt_p{trace} | |
315 | exists. | |
316 | @endparblock | |
317 | ||
318 | @bt_pre_not_null{trace} | |
319 | ||
320 | @sa bt_trace_borrow_stream_by_id_const() — | |
321 | \c const version of this function. | |
322 | */ | |
323 | extern bt_stream *bt_trace_borrow_stream_by_id(bt_trace *trace, | |
324 | uint64_t id); | |
325 | ||
326 | /*! | |
327 | @brief | |
328 | Borrows the \bt_stream having the numeric ID \bt_p{id} from the | |
329 | trace \bt_p{trace} (\c const version). | |
330 | ||
331 | See bt_trace_borrow_stream_by_id(). | |
332 | */ | |
333 | extern const bt_stream *bt_trace_borrow_stream_by_id_const( | |
334 | const bt_trace *trace, uint64_t id); | |
335 | ||
336 | /*! @} */ | |
337 | ||
338 | /*! | |
339 | @name Properties | |
340 | @{ | |
341 | */ | |
342 | ||
343 | /*! | |
344 | @brief | |
345 | Status codes for bt_trace_set_name(). | |
346 | */ | |
d24d5663 | 347 | typedef enum bt_trace_set_name_status { |
43c59509 PP |
348 | /*! |
349 | @brief | |
350 | Success. | |
351 | */ | |
d24d5663 | 352 | BT_TRACE_SET_NAME_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
353 | |
354 | /*! | |
355 | @brief | |
356 | Out of memory. | |
357 | */ | |
358 | BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 PP |
359 | } bt_trace_set_name_status; |
360 | ||
43c59509 PP |
361 | /*! |
362 | @brief | |
363 | Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}. | |
364 | ||
365 | See the \ref api-tir-trace-prop-name "name" property. | |
366 | ||
367 | @param[in] trace | |
368 | Trace of which to set the name to \bt_p{name}. | |
369 | @param[in] name | |
370 | New name of \bt_p{trace} (copied). | |
371 | ||
372 | @retval #BT_TRACE_SET_NAME_STATUS_OK | |
373 | Success. | |
374 | @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR | |
375 | Out of memory. | |
376 | ||
377 | @bt_pre_not_null{trace} | |
378 | @bt_pre_hot{trace} | |
379 | @bt_pre_not_null{name} | |
380 | ||
381 | @sa bt_trace_get_name() — | |
382 | Returns the name of a trace. | |
383 | */ | |
d24d5663 | 384 | extern bt_trace_set_name_status bt_trace_set_name(bt_trace *trace, |
23578e82 | 385 | const char *name); |
56e18c4c | 386 | |
43c59509 PP |
387 | /*! |
388 | @brief | |
389 | Returns the name of the trace \bt_p{trace}. | |
390 | ||
391 | See the \ref api-tir-trace-prop-name "name" property. | |
392 | ||
393 | If \bt_p{trace} has no name, this function returns \c NULL. | |
394 | ||
395 | @param[in] trace | |
396 | Trace of which to get the name. | |
397 | ||
398 | @returns | |
399 | @parblock | |
400 | Name of \bt_p{trace}, or \c NULL if none. | |
401 | ||
402 | The returned pointer remains valid as long as \bt_p{trace} | |
403 | is not modified. | |
404 | @endparblock | |
405 | ||
406 | @bt_pre_not_null{trace} | |
407 | ||
408 | @sa bt_trace_set_name() — | |
409 | Sets the name of a trace. | |
410 | */ | |
411 | extern const char *bt_trace_get_name(const bt_trace *trace); | |
412 | ||
413 | /*! | |
414 | @brief | |
415 | Sets the | |
416 | <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a> | |
417 | of the trace \bt_p{trace} to a copy of \bt_p{uuid}. | |
418 | ||
419 | See the \ref api-tir-trace-prop-uuid "UUID" property. | |
420 | ||
421 | @param[in] trace | |
422 | Trace of which to set the UUID to \bt_p{uuid}. | |
423 | @param[in] uuid | |
424 | New UUID of \bt_p{trace} (copied). | |
425 | ||
426 | @bt_pre_not_null{trace} | |
427 | @bt_pre_hot{trace} | |
428 | @bt_pre_not_null{uuid} | |
429 | ||
430 | @sa bt_trace_get_uuid() — | |
431 | Returns the UUID of a trace. | |
432 | */ | |
335a2da5 PP |
433 | extern void bt_trace_set_uuid(bt_trace *trace, bt_uuid uuid); |
434 | ||
43c59509 PP |
435 | /*! |
436 | @brief | |
437 | Returns the UUID of the trace \bt_p{trace}. | |
438 | ||
439 | See the \ref api-tir-trace-prop-uuid "UUID" property. | |
440 | ||
441 | If \bt_p{trace} has no UUID, this function returns \c NULL. | |
442 | ||
443 | @param[in] trace | |
444 | Trace of which to get the UUID. | |
445 | ||
446 | @returns | |
447 | @parblock | |
448 | UUID of \bt_p{trace}, or \c NULL if none. | |
449 | ||
450 | The returned pointer remains valid as long as \bt_p{trace} | |
451 | is not modified. | |
452 | @endparblock | |
453 | ||
454 | @bt_pre_not_null{trace} | |
455 | ||
456 | @sa bt_trace_set_uuid() — | |
457 | Sets the UUID of a trace. | |
458 | */ | |
459 | extern bt_uuid bt_trace_get_uuid(const bt_trace *trace); | |
460 | ||
461 | /*! | |
462 | @brief | |
463 | Status codes for bt_trace_set_name(). | |
464 | */ | |
335a2da5 | 465 | typedef enum bt_trace_set_environment_entry_status { |
43c59509 PP |
466 | /*! |
467 | @brief | |
468 | Success. | |
469 | */ | |
335a2da5 | 470 | BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
471 | |
472 | /*! | |
473 | @brief | |
474 | Out of memory. | |
475 | */ | |
476 | BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
335a2da5 PP |
477 | } bt_trace_set_environment_entry_status; |
478 | ||
43c59509 PP |
479 | /*! |
480 | @brief | |
481 | Sets the value of the environment entry of the trace \bt_p{trace} | |
482 | named \bt_p{name} to the signed integer \bt_p{value}. | |
483 | ||
484 | See the \ref api-tir-trace-prop-env "environment" property. | |
485 | ||
486 | On success, if \bt_p{trace} already contains an environment entry named | |
487 | \bt_p{name}, this function replaces the existing entry's value with | |
488 | \bt_p{value}. | |
489 | ||
490 | @param[in] trace | |
491 | Trace in which to insert or replace an environment entry named | |
492 | \bt_p{name} with the value \bt_p{value}. | |
493 | @param[in] name | |
494 | Name of the entry to insert or replace in \bt_p{trace} (copied). | |
495 | @param[in] value | |
496 | Value of the environment entry to insert or replace in \bt_p{trace}. | |
497 | ||
498 | @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK | |
499 | Success. | |
500 | @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR | |
501 | Out of memory. | |
502 | ||
503 | @bt_pre_not_null{trace} | |
504 | @bt_pre_hot{trace} | |
505 | @bt_pre_not_null{name} | |
506 | ||
507 | @sa bt_trace_set_environment_entry_string() — | |
508 | Sets a trace environment entry's value to a string. | |
509 | */ | |
335a2da5 PP |
510 | extern bt_trace_set_environment_entry_status |
511 | bt_trace_set_environment_entry_integer(bt_trace *trace, const char *name, | |
512 | int64_t value); | |
513 | ||
43c59509 PP |
514 | /*! |
515 | @brief | |
516 | Sets the value of the environment entry of the trace \bt_p{trace} | |
517 | named \bt_p{name} to the string \bt_p{value}. | |
518 | ||
519 | See the \ref api-tir-trace-prop-env "environment" property. | |
520 | ||
521 | On success, if \bt_p{trace} already contains an environment entry named | |
522 | \bt_p{name}, this function replaces the existing entry's value with | |
523 | \bt_p{value}. | |
524 | ||
525 | @param[in] trace | |
526 | Trace in which to insert or replace an environment entry named | |
527 | \bt_p{name} with the value \bt_p{value}. | |
528 | @param[in] name | |
529 | Name of the entry to insert or replace in \bt_p{trace} (copied). | |
530 | @param[in] value | |
531 | Value of the environment entry to insert or replace in \bt_p{trace}. | |
532 | ||
533 | @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK | |
534 | Success. | |
535 | @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR | |
536 | Out of memory. | |
537 | ||
538 | @bt_pre_not_null{trace} | |
539 | @bt_pre_hot{trace} | |
540 | @bt_pre_not_null{name} | |
541 | @bt_pre_not_null{value} | |
542 | ||
543 | @sa bt_trace_set_environment_entry_integer() — | |
544 | Sets a trace environment entry's value to a signed integer. | |
545 | */ | |
335a2da5 PP |
546 | extern bt_trace_set_environment_entry_status |
547 | bt_trace_set_environment_entry_string(bt_trace *trace, const char *name, | |
548 | const char *value); | |
549 | ||
43c59509 PP |
550 | /*! |
551 | @brief | |
552 | Returns the number of environment entries contained in the trace | |
553 | \bt_p{trace}. | |
56e18c4c | 554 | |
43c59509 PP |
555 | See the \ref api-tir-trace-prop-env "environment" property. |
556 | ||
557 | @param[in] trace | |
558 | Trace of which to get the number of environment entries. | |
559 | ||
560 | @returns | |
561 | Number of environment entries in \bt_p{trace}. | |
562 | ||
563 | @bt_pre_not_null{trace} | |
564 | */ | |
565 | extern uint64_t bt_trace_get_environment_entry_count(const bt_trace *trace); | |
566 | ||
567 | /*! | |
568 | @brief | |
569 | Borrows the environment entry at index \bt_p{index} from the | |
570 | trace \bt_p{trace}, setting \bt_p{*name} to its name and | |
571 | \bt_p{*value} to its value. | |
572 | ||
573 | See the \ref api-tir-trace-prop-env "environment" property. | |
574 | ||
575 | @param[in] trace | |
576 | Trace from which to borrow the environment entry at index | |
577 | \bt_p{index}. | |
578 | @param[in] index | |
579 | Index of the environment entry to borrow from \bt_p{trace}. | |
580 | @param[in] name | |
581 | @parblock | |
582 | <strong>On success</strong>, \bt_p{*name} is the name of the | |
583 | environment entry at index \bt_p{index} in \bt_p{trace}. | |
584 | ||
585 | The returned pointer remains valid as long as \bt_p{trace} | |
586 | is not modified. | |
587 | @endparblock | |
588 | @param[in] value | |
589 | @parblock | |
590 | <strong>On success</strong>, \bt_p{*value} is a \em borrowed | |
591 | reference of the environment entry at index \bt_p{index} in | |
592 | \bt_p{trace}. | |
593 | ||
594 | \bt_p{*value} is either a \bt_sint_val | |
595 | (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val | |
596 | (#BT_VALUE_TYPE_STRING). | |
597 | ||
598 | The returned pointer remains valid as long as \bt_p{trace} | |
599 | is not modified. | |
600 | @endparblock | |
601 | ||
602 | @bt_pre_not_null{trace} | |
603 | @pre | |
604 | \bt_p{index} is less than the number of environment entries in | |
605 | \bt_p{trace} (as returned by | |
606 | bt_trace_get_environment_entry_count()). | |
607 | @bt_pre_not_null{name} | |
608 | @bt_pre_not_null{value} | |
609 | ||
610 | @sa bt_trace_get_environment_entry_count() — | |
611 | Returns the number of environment entries contained in a trace. | |
612 | */ | |
613 | extern void bt_trace_borrow_environment_entry_by_index_const( | |
614 | const bt_trace *trace, uint64_t index, | |
615 | const char **name, const bt_value **value); | |
616 | ||
617 | /*! | |
618 | @brief | |
619 | Borrows the value of the environment entry named \bt_p{name} | |
620 | in the trace \bt_p{trace}. | |
621 | ||
622 | See the \ref api-tir-trace-prop-env "environment" property. | |
623 | ||
624 | If there's no environment entry named \bt_p{name} in \bt_p{trace}, this | |
625 | function returns \c NULL. | |
626 | ||
627 | @param[in] trace | |
628 | Trace from which to borrow the value of the environment entry | |
629 | named \bt_p{name}. | |
630 | @param[in] name | |
631 | Name of the environment entry to borrow from \bt_p{trace}. | |
632 | ||
633 | @returns | |
634 | @parblock | |
635 | \em Borrowed reference of the value of the environment entry named | |
636 | \bt_p{name} in \bt_p{trace}. | |
637 | ||
638 | The returned value is either a \bt_sint_val | |
639 | (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val | |
640 | (#BT_VALUE_TYPE_STRING). | |
641 | ||
642 | The returned pointer remains valid as long as \bt_p{trace} | |
643 | is not modified. | |
644 | @endparblock | |
645 | ||
646 | @bt_pre_not_null{trace} | |
647 | @bt_pre_not_null{name} | |
648 | */ | |
649 | extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const( | |
650 | const bt_trace *trace, const char *name); | |
651 | ||
652 | /*! | |
653 | @brief | |
654 | Sets the user attributes of the trace \bt_p{trace} to | |
655 | \bt_p{user_attributes}. | |
656 | ||
657 | See the \ref api-tir-trace-prop-user-attrs "user attributes" | |
658 | property. | |
659 | ||
660 | @note | |
661 | When you create a default trace with bt_trace_create(), the trace's | |
662 | initial user attributes is an empty \bt_map_val. Therefore you can | |
663 | borrow it with bt_trace_borrow_user_attributes() and fill it | |
664 | directly instead of setting a new one with this function. | |
665 | ||
666 | @param[in] trace | |
667 | Trace of which to set the user attributes to \bt_p{user_attributes}. | |
668 | @param[in] user_attributes | |
669 | New user attributes of \bt_p{trace}. | |
670 | ||
671 | @bt_pre_not_null{trace} | |
672 | @bt_pre_hot{trace} | |
673 | @bt_pre_not_null{user_attributes} | |
674 | @bt_pre_is_map_val{user_attributes} | |
675 | ||
676 | @sa bt_trace_borrow_user_attributes() — | |
677 | Borrows the user attributes of a trace. | |
678 | */ | |
679 | extern void bt_trace_set_user_attributes( | |
680 | bt_trace *trace, const bt_value *user_attributes); | |
681 | ||
682 | /*! | |
683 | @brief | |
684 | Borrows the user attributes of the trace \bt_p{trace}. | |
685 | ||
686 | See the \ref api-tir-trace-prop-user-attrs "user attributes" | |
687 | property. | |
688 | ||
689 | @note | |
690 | When you create a default trace with bt_trace_create(), the trace's | |
691 | initial user attributes is an empty \bt_map_val. | |
692 | ||
693 | @param[in] trace | |
694 | Trace from which to borrow the user attributes. | |
695 | ||
696 | @returns | |
697 | User attributes of \bt_p{trace} (a \bt_map_val). | |
698 | ||
699 | @bt_pre_not_null{trace} | |
700 | ||
701 | @sa bt_trace_set_user_attributes() — | |
702 | Sets the user attributes of a trace. | |
703 | @sa bt_trace_borrow_user_attributes_const() — | |
704 | \c const version of this function. | |
705 | */ | |
706 | extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace); | |
707 | ||
708 | /*! | |
709 | @brief | |
710 | Borrows the user attributes of the trace \bt_p{trace} | |
711 | (\c const version). | |
712 | ||
713 | See bt_trace_borrow_user_attributes(). | |
714 | */ | |
715 | extern const bt_value *bt_trace_borrow_user_attributes_const( | |
716 | const bt_trace *trace); | |
717 | ||
718 | /*! @} */ | |
719 | ||
720 | /*! | |
721 | @name Listeners | |
722 | @{ | |
723 | */ | |
724 | ||
725 | /*! | |
726 | @brief | |
727 | User function for bt_trace_add_destruction_listener(). | |
728 | ||
729 | This is the user function type for a trace destruction listener. | |
730 | ||
731 | @param[in] trace | |
732 | Trace being destroyed (\ref api-fund-freezing "frozen"). | |
733 | @param[in] user_data | |
734 | User data, as passed as the \bt_p{user_data} parameter of | |
735 | bt_trace_add_destruction_listener(). | |
736 | ||
737 | @bt_pre_not_null{trace} | |
738 | ||
739 | @post | |
740 | The reference count of \bt_p{trace} is not changed. | |
741 | @bt_post_no_error | |
742 | ||
743 | @sa bt_trace_add_destruction_listener() — | |
744 | Adds a destruction listener to a trace. | |
745 | */ | |
746 | typedef void (* bt_trace_destruction_listener_func)( | |
747 | const bt_trace *trace, void *user_data); | |
748 | ||
749 | /*! | |
750 | @brief | |
751 | Status codes for bt_trace_add_destruction_listener(). | |
752 | */ | |
753 | typedef enum bt_trace_add_listener_status { | |
754 | /*! | |
755 | @brief | |
756 | Success. | |
757 | */ | |
758 | BT_TRACE_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, | |
759 | ||
760 | /*! | |
761 | @brief | |
762 | Out of memory. | |
763 | */ | |
764 | BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
765 | } bt_trace_add_listener_status; | |
766 | ||
767 | /*! | |
768 | @brief | |
769 | Adds a destruction listener having the function \bt_p{user_func} | |
770 | to the trace \bt_p{trace}. | |
771 | ||
772 | All the destruction listener user functions of a trace are called | |
773 | when it's being destroyed. | |
774 | ||
775 | If \bt_p{listener_id} is not \c NULL, then this function, on success, | |
776 | sets \bt_p{*listener_id} to the ID of the added destruction listener | |
777 | within \bt_p{trace}. You can then use this ID to remove the | |
778 | added destruction listener with bt_trace_remove_destruction_listener(). | |
779 | ||
780 | @param[in] trace | |
781 | Trace to add the destruction listener to. | |
782 | @param[in] user_func | |
783 | User function of the destruction listener to add to | |
784 | \bt_p{trace}. | |
785 | @param[in] user_data | |
786 | User data to pass as the \bt_p{user_data} parameter of | |
787 | \bt_p{user_func}. | |
788 | @param[out] listener_id | |
789 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
790 | is the ID of the added destruction listener within | |
791 | \bt_p{trace}. | |
792 | ||
793 | @retval #BT_TRACE_ADD_LISTENER_STATUS_OK | |
794 | Success. | |
795 | @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR | |
796 | Out of memory. | |
797 | ||
798 | @bt_pre_not_null{trace} | |
799 | @bt_pre_not_null{user_func} | |
800 | ||
801 | @sa bt_trace_remove_destruction_listener() — | |
802 | Removes a destruction listener from a trace. | |
803 | */ | |
804 | extern bt_trace_add_listener_status bt_trace_add_destruction_listener( | |
805 | const bt_trace *trace, | |
806 | bt_trace_destruction_listener_func user_func, | |
807 | void *user_data, bt_listener_id *listener_id); | |
808 | ||
809 | /*! | |
810 | @brief | |
811 | Status codes for bt_trace_remove_destruction_listener(). | |
812 | */ | |
813 | typedef enum bt_trace_remove_listener_status { | |
814 | /*! | |
815 | @brief | |
816 | Success. | |
817 | */ | |
818 | BT_TRACE_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, | |
819 | ||
820 | /*! | |
821 | @brief | |
822 | Out of memory. | |
823 | */ | |
824 | BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
825 | } bt_trace_remove_listener_status; | |
826 | ||
827 | /*! | |
828 | @brief | |
829 | Removes the destruction listener having the ID \bt_p{listener_id} | |
830 | from the trace \bt_p{trace}. | |
831 | ||
832 | The destruction listener to remove from \bt_p{trace} was | |
833 | previously added with bt_trace_add_destruction_listener(). | |
834 | ||
835 | You can call this function when \bt_p{trace} is | |
836 | \ref api-fund-freezing "frozen". | |
837 | ||
838 | @param[in] trace | |
839 | Trace from which to remove the destruction listener having | |
840 | the ID \bt_p{listener_id}. | |
841 | @param[in] listener_id | |
842 | ID of the destruction listener to remove from \bt_p{trace}. | |
843 | ||
844 | @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK | |
845 | Success. | |
846 | @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR | |
847 | Out of memory. | |
848 | ||
849 | @bt_pre_not_null{trace} | |
850 | @pre | |
851 | \bt_p{listener_id} is the ID of an existing destruction listener | |
852 | in \bt_p{trace}. | |
853 | ||
854 | @sa bt_trace_add_destruction_listener() — | |
855 | Adds a destruction listener to a trace. | |
856 | */ | |
857 | extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener( | |
858 | const bt_trace *trace, bt_listener_id listener_id); | |
859 | ||
860 | /*! @} */ | |
861 | ||
862 | /*! | |
863 | @name Reference count | |
864 | @{ | |
865 | */ | |
866 | ||
867 | /*! | |
868 | @brief | |
869 | Increments the \ref api-fund-shared-object "reference count" of | |
870 | the trace \bt_p{trace}. | |
871 | ||
872 | @param[in] trace | |
873 | @parblock | |
874 | Trace of which to increment the reference count. | |
875 | ||
876 | Can be \c NULL. | |
877 | @endparblock | |
878 | ||
879 | @sa bt_trace_put_ref() — | |
880 | Decrements the reference count of a trace. | |
881 | */ | |
882 | extern void bt_trace_get_ref(const bt_trace *trace); | |
883 | ||
884 | /*! | |
885 | @brief | |
886 | Decrements the \ref api-fund-shared-object "reference count" of | |
887 | the trace \bt_p{trace}. | |
888 | ||
889 | @param[in] trace | |
890 | @parblock | |
891 | Trace of which to decrement the reference count. | |
892 | ||
893 | Can be \c NULL. | |
894 | @endparblock | |
895 | ||
896 | @sa bt_trace_get_ref() — | |
897 | Increments the reference count of a trace. | |
898 | */ | |
899 | extern void bt_trace_put_ref(const bt_trace *trace); | |
900 | ||
901 | /*! | |
902 | @brief | |
903 | Decrements the reference count of the trace | |
904 | \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL. | |
905 | ||
906 | @param _trace | |
907 | @parblock | |
908 | Trace of which to decrement the reference count. | |
909 | ||
910 | Can contain \c NULL. | |
911 | @endparblock | |
912 | ||
913 | @bt_pre_assign_expr{_trace} | |
914 | */ | |
915 | #define BT_TRACE_PUT_REF_AND_RESET(_trace) \ | |
916 | do { \ | |
917 | bt_trace_put_ref(_trace); \ | |
918 | (_trace) = NULL; \ | |
919 | } while (0) | |
920 | ||
921 | /*! | |
922 | @brief | |
923 | Decrements the reference count of the trace \bt_p{_dst}, sets | |
924 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
925 | ||
926 | This macro effectively moves a trace reference from the expression | |
927 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
928 | \bt_p{_dst} reference. | |
929 | ||
930 | @param _dst | |
931 | @parblock | |
932 | Destination expression. | |
933 | ||
934 | Can contain \c NULL. | |
935 | @endparblock | |
936 | @param _src | |
937 | @parblock | |
938 | Source expression. | |
939 | ||
940 | Can contain \c NULL. | |
941 | @endparblock | |
942 | ||
943 | @bt_pre_assign_expr{_dst} | |
944 | @bt_pre_assign_expr{_src} | |
945 | */ | |
946 | #define BT_TRACE_MOVE_REF(_dst, _src) \ | |
947 | do { \ | |
948 | bt_trace_put_ref(_dst); \ | |
949 | (_dst) = (_src); \ | |
950 | (_src) = NULL; \ | |
951 | } while (0) | |
952 | ||
953 | /*! @} */ | |
954 | ||
955 | /*! @} */ | |
56e18c4c | 956 | |
56e18c4c PP |
957 | #ifdef __cplusplus |
958 | } | |
959 | #endif | |
960 | ||
924dc299 | 961 | #endif /* BABELTRACE2_TRACE_IR_TRACE_H */ |