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 | */ | |
4c81a2b7 | 191 | extern bt_trace *bt_trace_create(bt_trace_class *trace_class) __BT_NOEXCEPT; |
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 | */ | |
4c81a2b7 | 216 | extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
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( | |
4c81a2b7 | 226 | const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
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 | */ | |
4c81a2b7 | 248 | extern uint64_t bt_trace_get_stream_count(const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
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, | |
4c81a2b7 | 282 | uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
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( | |
4c81a2b7 | 292 | const bt_trace *trace, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
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, | |
4c81a2b7 | 324 | uint64_t id) __BT_NOEXCEPT; |
43c59509 PP |
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( | |
4c81a2b7 | 334 | const bt_trace *trace, uint64_t id) __BT_NOEXCEPT; |
43c59509 PP |
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, |
4c81a2b7 | 385 | const char *name) __BT_NOEXCEPT; |
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 | */ | |
4c81a2b7 | 411 | extern const char *bt_trace_get_name(const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
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 | */ | |
4c81a2b7 | 433 | extern void bt_trace_set_uuid(bt_trace *trace, bt_uuid uuid) __BT_NOEXCEPT; |
335a2da5 | 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 | */ | |
4c81a2b7 | 459 | extern bt_uuid bt_trace_get_uuid(const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
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, | |
4c81a2b7 | 512 | int64_t value) __BT_NOEXCEPT; |
335a2da5 | 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, | |
4c81a2b7 | 548 | const char *value) __BT_NOEXCEPT; |
335a2da5 | 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 | */ | |
4c81a2b7 PP |
565 | extern uint64_t bt_trace_get_environment_entry_count( |
566 | const bt_trace *trace) __BT_NOEXCEPT; | |
43c59509 PP |
567 | |
568 | /*! | |
569 | @brief | |
570 | Borrows the environment entry at index \bt_p{index} from the | |
571 | trace \bt_p{trace}, setting \bt_p{*name} to its name and | |
572 | \bt_p{*value} to its value. | |
573 | ||
574 | See the \ref api-tir-trace-prop-env "environment" property. | |
575 | ||
576 | @param[in] trace | |
577 | Trace from which to borrow the environment entry at index | |
578 | \bt_p{index}. | |
579 | @param[in] index | |
580 | Index of the environment entry to borrow from \bt_p{trace}. | |
581 | @param[in] name | |
582 | @parblock | |
583 | <strong>On success</strong>, \bt_p{*name} is the name of the | |
584 | environment entry at index \bt_p{index} in \bt_p{trace}. | |
585 | ||
586 | The returned pointer remains valid as long as \bt_p{trace} | |
587 | is not modified. | |
588 | @endparblock | |
589 | @param[in] value | |
590 | @parblock | |
591 | <strong>On success</strong>, \bt_p{*value} is a \em borrowed | |
592 | reference of the environment entry at index \bt_p{index} in | |
593 | \bt_p{trace}. | |
594 | ||
595 | \bt_p{*value} is either a \bt_sint_val | |
596 | (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val | |
597 | (#BT_VALUE_TYPE_STRING). | |
598 | ||
599 | The returned pointer remains valid as long as \bt_p{trace} | |
600 | is not modified. | |
601 | @endparblock | |
602 | ||
603 | @bt_pre_not_null{trace} | |
604 | @pre | |
605 | \bt_p{index} is less than the number of environment entries in | |
606 | \bt_p{trace} (as returned by | |
607 | bt_trace_get_environment_entry_count()). | |
608 | @bt_pre_not_null{name} | |
609 | @bt_pre_not_null{value} | |
610 | ||
611 | @sa bt_trace_get_environment_entry_count() — | |
612 | Returns the number of environment entries contained in a trace. | |
613 | */ | |
614 | extern void bt_trace_borrow_environment_entry_by_index_const( | |
615 | const bt_trace *trace, uint64_t index, | |
4c81a2b7 | 616 | const char **name, const bt_value **value) __BT_NOEXCEPT; |
43c59509 PP |
617 | |
618 | /*! | |
619 | @brief | |
620 | Borrows the value of the environment entry named \bt_p{name} | |
621 | in the trace \bt_p{trace}. | |
622 | ||
623 | See the \ref api-tir-trace-prop-env "environment" property. | |
624 | ||
625 | If there's no environment entry named \bt_p{name} in \bt_p{trace}, this | |
626 | function returns \c NULL. | |
627 | ||
628 | @param[in] trace | |
629 | Trace from which to borrow the value of the environment entry | |
630 | named \bt_p{name}. | |
631 | @param[in] name | |
632 | Name of the environment entry to borrow from \bt_p{trace}. | |
633 | ||
634 | @returns | |
635 | @parblock | |
636 | \em Borrowed reference of the value of the environment entry named | |
637 | \bt_p{name} in \bt_p{trace}. | |
638 | ||
639 | The returned value is either a \bt_sint_val | |
640 | (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val | |
641 | (#BT_VALUE_TYPE_STRING). | |
642 | ||
643 | The returned pointer remains valid as long as \bt_p{trace} | |
644 | is not modified. | |
645 | @endparblock | |
646 | ||
647 | @bt_pre_not_null{trace} | |
648 | @bt_pre_not_null{name} | |
649 | */ | |
650 | extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const( | |
4c81a2b7 | 651 | const bt_trace *trace, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
652 | |
653 | /*! | |
654 | @brief | |
655 | Sets the user attributes of the trace \bt_p{trace} to | |
656 | \bt_p{user_attributes}. | |
657 | ||
658 | See the \ref api-tir-trace-prop-user-attrs "user attributes" | |
659 | property. | |
660 | ||
661 | @note | |
662 | When you create a default trace with bt_trace_create(), the trace's | |
663 | initial user attributes is an empty \bt_map_val. Therefore you can | |
664 | borrow it with bt_trace_borrow_user_attributes() and fill it | |
665 | directly instead of setting a new one with this function. | |
666 | ||
667 | @param[in] trace | |
668 | Trace of which to set the user attributes to \bt_p{user_attributes}. | |
669 | @param[in] user_attributes | |
670 | New user attributes of \bt_p{trace}. | |
671 | ||
672 | @bt_pre_not_null{trace} | |
673 | @bt_pre_hot{trace} | |
674 | @bt_pre_not_null{user_attributes} | |
675 | @bt_pre_is_map_val{user_attributes} | |
676 | ||
677 | @sa bt_trace_borrow_user_attributes() — | |
678 | Borrows the user attributes of a trace. | |
679 | */ | |
680 | extern void bt_trace_set_user_attributes( | |
4c81a2b7 | 681 | bt_trace *trace, const bt_value *user_attributes) __BT_NOEXCEPT; |
43c59509 PP |
682 | |
683 | /*! | |
684 | @brief | |
685 | Borrows the user attributes of the trace \bt_p{trace}. | |
686 | ||
687 | See the \ref api-tir-trace-prop-user-attrs "user attributes" | |
688 | property. | |
689 | ||
690 | @note | |
691 | When you create a default trace with bt_trace_create(), the trace's | |
692 | initial user attributes is an empty \bt_map_val. | |
693 | ||
694 | @param[in] trace | |
695 | Trace from which to borrow the user attributes. | |
696 | ||
697 | @returns | |
698 | User attributes of \bt_p{trace} (a \bt_map_val). | |
699 | ||
700 | @bt_pre_not_null{trace} | |
701 | ||
702 | @sa bt_trace_set_user_attributes() — | |
703 | Sets the user attributes of a trace. | |
704 | @sa bt_trace_borrow_user_attributes_const() — | |
705 | \c const version of this function. | |
706 | */ | |
4c81a2b7 | 707 | extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
708 | |
709 | /*! | |
710 | @brief | |
711 | Borrows the user attributes of the trace \bt_p{trace} | |
712 | (\c const version). | |
713 | ||
714 | See bt_trace_borrow_user_attributes(). | |
715 | */ | |
716 | extern const bt_value *bt_trace_borrow_user_attributes_const( | |
4c81a2b7 | 717 | const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
718 | |
719 | /*! @} */ | |
720 | ||
721 | /*! | |
722 | @name Listeners | |
723 | @{ | |
724 | */ | |
725 | ||
726 | /*! | |
727 | @brief | |
728 | User function for bt_trace_add_destruction_listener(). | |
729 | ||
730 | This is the user function type for a trace destruction listener. | |
731 | ||
732 | @param[in] trace | |
733 | Trace being destroyed (\ref api-fund-freezing "frozen"). | |
734 | @param[in] user_data | |
735 | User data, as passed as the \bt_p{user_data} parameter of | |
736 | bt_trace_add_destruction_listener(). | |
737 | ||
738 | @bt_pre_not_null{trace} | |
739 | ||
740 | @post | |
741 | The reference count of \bt_p{trace} is not changed. | |
742 | @bt_post_no_error | |
743 | ||
744 | @sa bt_trace_add_destruction_listener() — | |
745 | Adds a destruction listener to a trace. | |
746 | */ | |
747 | typedef void (* bt_trace_destruction_listener_func)( | |
748 | const bt_trace *trace, void *user_data); | |
749 | ||
750 | /*! | |
751 | @brief | |
752 | Status codes for bt_trace_add_destruction_listener(). | |
753 | */ | |
754 | typedef enum bt_trace_add_listener_status { | |
755 | /*! | |
756 | @brief | |
757 | Success. | |
758 | */ | |
759 | BT_TRACE_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, | |
760 | ||
761 | /*! | |
762 | @brief | |
763 | Out of memory. | |
764 | */ | |
765 | BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
766 | } bt_trace_add_listener_status; | |
767 | ||
768 | /*! | |
769 | @brief | |
770 | Adds a destruction listener having the function \bt_p{user_func} | |
771 | to the trace \bt_p{trace}. | |
772 | ||
773 | All the destruction listener user functions of a trace are called | |
774 | when it's being destroyed. | |
775 | ||
776 | If \bt_p{listener_id} is not \c NULL, then this function, on success, | |
777 | sets \bt_p{*listener_id} to the ID of the added destruction listener | |
778 | within \bt_p{trace}. You can then use this ID to remove the | |
779 | added destruction listener with bt_trace_remove_destruction_listener(). | |
780 | ||
781 | @param[in] trace | |
782 | Trace to add the destruction listener to. | |
783 | @param[in] user_func | |
784 | User function of the destruction listener to add to | |
785 | \bt_p{trace}. | |
786 | @param[in] user_data | |
787 | User data to pass as the \bt_p{user_data} parameter of | |
788 | \bt_p{user_func}. | |
789 | @param[out] listener_id | |
790 | <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id} | |
791 | is the ID of the added destruction listener within | |
792 | \bt_p{trace}. | |
793 | ||
794 | @retval #BT_TRACE_ADD_LISTENER_STATUS_OK | |
795 | Success. | |
796 | @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR | |
797 | Out of memory. | |
798 | ||
799 | @bt_pre_not_null{trace} | |
800 | @bt_pre_not_null{user_func} | |
801 | ||
802 | @sa bt_trace_remove_destruction_listener() — | |
803 | Removes a destruction listener from a trace. | |
804 | */ | |
805 | extern bt_trace_add_listener_status bt_trace_add_destruction_listener( | |
806 | const bt_trace *trace, | |
807 | bt_trace_destruction_listener_func user_func, | |
4c81a2b7 | 808 | void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT; |
43c59509 PP |
809 | |
810 | /*! | |
811 | @brief | |
812 | Status codes for bt_trace_remove_destruction_listener(). | |
813 | */ | |
814 | typedef enum bt_trace_remove_listener_status { | |
815 | /*! | |
816 | @brief | |
817 | Success. | |
818 | */ | |
819 | BT_TRACE_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, | |
820 | ||
821 | /*! | |
822 | @brief | |
823 | Out of memory. | |
824 | */ | |
825 | BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
826 | } bt_trace_remove_listener_status; | |
827 | ||
828 | /*! | |
829 | @brief | |
830 | Removes the destruction listener having the ID \bt_p{listener_id} | |
831 | from the trace \bt_p{trace}. | |
832 | ||
833 | The destruction listener to remove from \bt_p{trace} was | |
834 | previously added with bt_trace_add_destruction_listener(). | |
835 | ||
836 | You can call this function when \bt_p{trace} is | |
837 | \ref api-fund-freezing "frozen". | |
838 | ||
839 | @param[in] trace | |
840 | Trace from which to remove the destruction listener having | |
841 | the ID \bt_p{listener_id}. | |
842 | @param[in] listener_id | |
843 | ID of the destruction listener to remove from \bt_p{trace}. | |
844 | ||
845 | @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK | |
846 | Success. | |
847 | @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR | |
848 | Out of memory. | |
849 | ||
850 | @bt_pre_not_null{trace} | |
851 | @pre | |
852 | \bt_p{listener_id} is the ID of an existing destruction listener | |
853 | in \bt_p{trace}. | |
854 | ||
855 | @sa bt_trace_add_destruction_listener() — | |
856 | Adds a destruction listener to a trace. | |
857 | */ | |
858 | extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener( | |
4c81a2b7 PP |
859 | const bt_trace *trace, bt_listener_id listener_id) |
860 | __BT_NOEXCEPT; | |
43c59509 PP |
861 | |
862 | /*! @} */ | |
863 | ||
864 | /*! | |
865 | @name Reference count | |
866 | @{ | |
867 | */ | |
868 | ||
869 | /*! | |
870 | @brief | |
871 | Increments the \ref api-fund-shared-object "reference count" of | |
872 | the trace \bt_p{trace}. | |
873 | ||
874 | @param[in] trace | |
875 | @parblock | |
876 | Trace of which to increment the reference count. | |
877 | ||
878 | Can be \c NULL. | |
879 | @endparblock | |
880 | ||
881 | @sa bt_trace_put_ref() — | |
882 | Decrements the reference count of a trace. | |
883 | */ | |
4c81a2b7 | 884 | extern void bt_trace_get_ref(const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
885 | |
886 | /*! | |
887 | @brief | |
888 | Decrements the \ref api-fund-shared-object "reference count" of | |
889 | the trace \bt_p{trace}. | |
890 | ||
891 | @param[in] trace | |
892 | @parblock | |
893 | Trace of which to decrement the reference count. | |
894 | ||
895 | Can be \c NULL. | |
896 | @endparblock | |
897 | ||
898 | @sa bt_trace_get_ref() — | |
899 | Increments the reference count of a trace. | |
900 | */ | |
4c81a2b7 | 901 | extern void bt_trace_put_ref(const bt_trace *trace) __BT_NOEXCEPT; |
43c59509 PP |
902 | |
903 | /*! | |
904 | @brief | |
905 | Decrements the reference count of the trace | |
906 | \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL. | |
907 | ||
908 | @param _trace | |
909 | @parblock | |
910 | Trace of which to decrement the reference count. | |
911 | ||
912 | Can contain \c NULL. | |
913 | @endparblock | |
914 | ||
915 | @bt_pre_assign_expr{_trace} | |
916 | */ | |
917 | #define BT_TRACE_PUT_REF_AND_RESET(_trace) \ | |
918 | do { \ | |
919 | bt_trace_put_ref(_trace); \ | |
920 | (_trace) = NULL; \ | |
921 | } while (0) | |
922 | ||
923 | /*! | |
924 | @brief | |
925 | Decrements the reference count of the trace \bt_p{_dst}, sets | |
926 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
927 | ||
928 | This macro effectively moves a trace reference from the expression | |
929 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
930 | \bt_p{_dst} reference. | |
931 | ||
932 | @param _dst | |
933 | @parblock | |
934 | Destination expression. | |
935 | ||
936 | Can contain \c NULL. | |
937 | @endparblock | |
938 | @param _src | |
939 | @parblock | |
940 | Source expression. | |
941 | ||
942 | Can contain \c NULL. | |
943 | @endparblock | |
944 | ||
945 | @bt_pre_assign_expr{_dst} | |
946 | @bt_pre_assign_expr{_src} | |
947 | */ | |
948 | #define BT_TRACE_MOVE_REF(_dst, _src) \ | |
949 | do { \ | |
950 | bt_trace_put_ref(_dst); \ | |
951 | (_dst) = (_src); \ | |
952 | (_src) = NULL; \ | |
953 | } while (0) | |
954 | ||
955 | /*! @} */ | |
956 | ||
957 | /*! @} */ | |
56e18c4c | 958 | |
56e18c4c PP |
959 | #ifdef __cplusplus |
960 | } | |
961 | #endif | |
962 | ||
924dc299 | 963 | #endif /* BABELTRACE2_TRACE_IR_TRACE_H */ |