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