Commit | Line | Data |
---|---|---|
43c59509 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
43c59509 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
43c59509 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_ERROR_REPORTING_H |
8 | #define BABELTRACE2_ERROR_REPORTING_H | |
9 | ||
43c59509 PP |
10 | #ifndef __BT_IN_BABELTRACE_H |
11 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
12 | #endif | |
13 | ||
14 | #include <stdarg.h> | |
15 | ||
16 | #include <babeltrace2/types.h> | |
17 | #include <babeltrace2/graph/component-class.h> | |
18 | ||
19 | #ifdef __cplusplus | |
20 | extern "C" { | |
21 | #endif | |
22 | ||
23 | /*! | |
24 | @defgroup api-error Error reporting | |
25 | ||
26 | @brief | |
27 | Error reporting functions and macros. | |
28 | ||
29 | This module contains functions and macros to report rich errors from a | |
30 | user function (a \bt_comp_cls method, a | |
31 | \ref api-qexec "query operation", or a trace processing \bt_graph | |
32 | listener, for example) to any function caller. | |
33 | ||
34 | Because \bt_name orchestrates pieces written by different authors, | |
35 | it is important that an error which occurs deep into the function call | |
36 | stack can percolate up to its callers. | |
37 | ||
38 | The very basic mechanism to report an error from a function is to | |
39 | \ref api-fund-func-status "return an error status" | |
40 | (a status code enumerator which contains the word | |
41 | \c ERROR): each function caller can clean its own context and return an | |
42 | error status code itself until one caller "catches" the status code and | |
43 | reacts to it. For example, the reaction can be to show an error message | |
44 | to the end user. | |
45 | ||
46 | This error reporting API adds a layer so that each function which | |
47 | returns an error status code can append a message which describes the | |
48 | cause of the error within the function's context. | |
49 | ||
50 | Functions append error causes to the current thread's error. Having one | |
51 | error object per thread makes this API thread-safe. | |
52 | ||
53 | Here's a visual, step-by-step example: | |
54 | ||
55 | @image html error-reporting-steps-1234.png | |
56 | ||
57 | -# The trace processing \bt_graph user calls bt_graph_run(). | |
58 | ||
59 | -# bt_graph_run() calls the | |
60 | \ref api-comp-cls-dev-meth-consume "consuming method" of the | |
61 | \bt_sink_comp. | |
62 | ||
63 | -# The sink \bt_comp calls bt_message_iterator_next() on its upstream | |
64 | source \bt_msg_iter. | |
65 | ||
66 | -# bt_message_iterator_next() calls the source message iterator's | |
67 | \link api-msg-iter-cls-meth-next "next" method\endlink. | |
68 | ||
69 | @image html error-reporting-step-5.png | |
70 | ||
71 | <ol start="5"> | |
72 | <li> | |
73 | An error occurs within the "next" method of the source message | |
74 | iterator: the function cannot read a file because permission was | |
75 | denied. | |
76 | </ol> | |
77 | ||
78 | @image html error-reporting-step-6.png | |
79 | ||
80 | <ol start="6"> | |
81 | <li> | |
82 | The source message iterator's "next" method appends the error | |
83 | cause <em>"Cannot read file /some/file: permission denied"</em> | |
84 | and returns | |
85 | #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR. | |
86 | </ol> | |
87 | ||
88 | @image html error-reporting-step-7.png | |
89 | ||
90 | <ol start="7"> | |
91 | <li> | |
92 | bt_message_iterator_next() appends | |
93 | the error cause <em>"Message iterator's 'next' method failed"</em> | |
94 | with details about the source component and | |
95 | returns #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR. | |
96 | </ol> | |
97 | ||
98 | @image html error-reporting-steps-89.png | |
99 | ||
100 | <ol start="8"> | |
101 | <li> | |
102 | The sink component's "consume" method appends the error | |
103 | cause <em>"Cannot consume upstream message iterator's messages"</em> | |
104 | and returns #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR. | |
105 | ||
106 | <li> | |
107 | bt_graph_run() appends the error cause <em>"Component's 'consume' | |
108 | method failed"</em> with details about the sink component and | |
109 | returns #BT_GRAPH_RUN_STATUS_ERROR. | |
110 | </ol> | |
111 | ||
112 | At this point, the current thread's error contains four causes: | |
113 | ||
114 | - <em>"Cannot read file /some/file: permission denied"</em> | |
115 | - <em>"Message iterator's 'next' method failed"</em> | |
116 | - <em>"Cannot consume upstream message iterator's messages"</em> | |
117 | - <em>"Component's 'consume' method failed"</em> | |
118 | ||
119 | This list of error causes is much richer for the end user than dealing | |
120 | only with #BT_GRAPH_RUN_STATUS_ERROR (the last error status code). | |
121 | ||
122 | Both error (#bt_error) and error cause (#bt_error_cause) objects are | |
123 | \ref api-fund-unique-object "unique objects": | |
124 | ||
125 | - An error belongs to either | |
126 | the library or you (see \ref api-error-handle "Handle an error"). | |
127 | ||
128 | - An error cause belongs to the error which contains it. | |
129 | ||
130 | <h1>\anchor api-error-append-cause Append an error cause</h1> | |
131 | ||
132 | When your function returns an error status code, use one of the | |
133 | <code>bt_current_thread_error_append_cause_from_*()</code> | |
134 | functions or <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code> | |
135 | macros to append an error cause to the | |
136 | current thread's error. Use the appropriate function or macro | |
137 | depending on your function's actor amongst: | |
138 | ||
139 | <dl> | |
140 | <dt>Component</dt> | |
141 | <dd> | |
142 | Append an error cause from a \bt_comp method. | |
143 | ||
144 | Use bt_current_thread_error_append_cause_from_component() or | |
145 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(). | |
146 | </dd> | |
147 | ||
148 | <dt>Message iterator</dt> | |
149 | <dd> | |
150 | Append an error cause from a \bt_msg_iter method. | |
151 | ||
152 | Use bt_current_thread_error_append_cause_from_message_iterator() or | |
153 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(). | |
154 | </dd> | |
155 | ||
156 | <dt>Component class</dt> | |
157 | <dd> | |
158 | Append an error cause from a \bt_comp_cls method | |
159 | ("query" method). | |
160 | ||
161 | Use bt_current_thread_error_append_cause_from_component_class() or | |
162 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(). | |
163 | </dd> | |
164 | ||
165 | <dt>Unknown</dt> | |
166 | <dd> | |
167 | Append an error cause from any other function, for example | |
168 | a \bt_graph listener or a function of your user application). | |
169 | ||
170 | Use bt_current_thread_error_append_cause_from_unknown() or | |
171 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(). | |
172 | </dd> | |
173 | </dl> | |
174 | ||
175 | The <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code> macros | |
176 | uses \c __FILE__ and \c __LINE__ as the file name and line number | |
177 | parameters of their corresponding | |
178 | <code>bt_current_thread_error_append_cause_from_*()</code> function. | |
179 | ||
180 | <h1>\anchor api-error-handle Handle an error</h1> | |
181 | ||
182 | If any libbabeltrace2 function you call returns an error status code, do | |
183 | one of: | |
184 | ||
185 | - Return an error status code too. | |
186 | ||
187 | In that case, you \em can | |
188 | \ref api-error-append-cause "append an error cause" to the current | |
189 | thread's error. | |
190 | ||
191 | - \em Take the current thread's error with | |
192 | bt_current_thread_take_error(). | |
193 | ||
194 | This function moves the ownership of the error object from the library | |
195 | to you. | |
196 | ||
197 | At this point, you can inspect its causes with | |
198 | bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and | |
199 | then do one of: | |
200 | ||
201 | - Call bt_error_release() to free the error object. | |
202 | ||
203 | In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a> | |
204 | terms, this corresponds to catching an exception and discarding it. | |
205 | ||
206 | - Call bt_current_thread_move_error() to move back the error object's | |
207 | ownership to the library. | |
208 | ||
209 | In object-oriented programming terms, this corresponds to catching | |
210 | an exception and rethrowing it. | |
211 | ||
212 | bt_current_thread_clear_error() is a helper which is the equivalent of: | |
213 | ||
214 | @code | |
215 | bt_error_release(bt_current_thread_take_error()); | |
216 | @endcode | |
217 | ||
218 | <h1>Error cause</h1> | |
219 | ||
220 | All error causes have the type #bt_error_cause. | |
221 | ||
222 | There are four types of error cause actors: | |
223 | ||
224 | - \bt_c_comp | |
225 | - \bt_c_msg_iter | |
226 | - \bt_c_comp_cls | |
227 | - Unknown | |
228 | ||
229 | Get the type enumerator of an error cause's actor with | |
230 | bt_error_cause_get_actor_type(). | |
231 | ||
232 | An error cause has the following common properties: | |
233 | ||
234 | <dl> | |
235 | <dt>Message</dt> | |
236 | <dd> | |
237 | Description of the error cause. | |
238 | ||
239 | Use bt_error_cause_get_message(). | |
240 | </dd> | |
241 | ||
242 | <dt>Module name</dt> | |
243 | <dd> | |
244 | Name of the module causing the error. | |
245 | ||
246 | For example, libbabeltrace2 uses "libbabeltrace2" and the \bt_cli | |
247 | CLI tool uses "Babeltrace CLI". | |
248 | ||
249 | Use bt_error_cause_get_module_name(). | |
250 | </dd> | |
251 | ||
252 | <dt>File name</dt> | |
253 | <dd> | |
254 | Name of the source file causing the error. | |
255 | ||
256 | Use bt_error_cause_get_file_name(). | |
257 | </dd> | |
258 | ||
259 | <dt>Line number</dt> | |
260 | <dd> | |
261 | Line number of the statement causing the error. | |
262 | ||
263 | Use bt_error_cause_get_line_number(). | |
264 | </dd> | |
265 | </dl> | |
266 | ||
267 | <h2>Error cause with a component actor</h2> | |
268 | ||
269 | An error cause with a \bt_comp actor has the following specific | |
270 | properties: | |
271 | ||
272 | <dl> | |
273 | <dt>Component name</dt> | |
274 | <dd> | |
275 | Name of the component. | |
276 | ||
277 | Use bt_error_cause_component_actor_get_component_name(). | |
278 | </dd> | |
279 | ||
280 | <dt>Component class name</dt> | |
281 | <dd> | |
282 | Name of the component's \ref api-comp-cls "class". | |
283 | ||
284 | Use bt_error_cause_component_actor_get_component_class_type(). | |
285 | </dd> | |
286 | ||
287 | <dt>Component class type</dt> | |
288 | <dd> | |
289 | Type of the component's class. | |
290 | ||
291 | Use bt_error_cause_component_actor_get_component_class_name(). | |
292 | </dd> | |
293 | ||
294 | <dt>\bt_dt_opt Plugin name</dt> | |
295 | <dd> | |
296 | Name of the \bt_plugin which provides the component's class, if any. | |
297 | ||
298 | Use bt_error_cause_component_actor_get_plugin_name(). | |
299 | </dd> | |
300 | </dl> | |
301 | ||
302 | <h2>Error cause with a message iterator actor</h2> | |
303 | ||
304 | An error cause with a \bt_msg_iter actor has the following specific | |
305 | properties: | |
306 | ||
307 | <dl> | |
308 | <dt>Component output port name</dt> | |
309 | <dd> | |
310 | Name of the \bt_comp \bt_oport from which the message iterator | |
311 | was created. | |
312 | ||
313 | Use bt_error_cause_component_actor_get_component_name(). | |
314 | </dd> | |
315 | ||
316 | <dt>Component name</dt> | |
317 | <dd> | |
318 | Name of the component. | |
319 | ||
320 | Use bt_error_cause_component_actor_get_component_name(). | |
321 | </dd> | |
322 | ||
323 | bt_error_cause_message_iterator_actor_get_component_output_port_name | |
324 | ||
325 | <dt>Component class name</dt> | |
326 | <dd> | |
327 | Name of the component's \ref api-comp-cls "class". | |
328 | ||
329 | Use bt_error_cause_component_actor_get_component_class_type(). | |
330 | </dd> | |
331 | ||
332 | <dt>Component class type</dt> | |
333 | <dd> | |
334 | Type of the component's class. | |
335 | ||
336 | Use bt_error_cause_component_actor_get_component_class_name(). | |
337 | </dd> | |
338 | ||
339 | <dt>\bt_dt_opt Plugin name</dt> | |
340 | <dd> | |
341 | Name of the \bt_plugin which provides the component's class, if any. | |
342 | ||
343 | Use bt_error_cause_component_actor_get_plugin_name(). | |
344 | </dd> | |
345 | </dl> | |
346 | ||
347 | <h2>Error cause with a component class actor</h2> | |
348 | ||
349 | An error cause with a \bt_comp_cls actor has the following specific | |
350 | properties: | |
351 | ||
352 | <dl> | |
353 | <dt>Component class name</dt> | |
354 | <dd> | |
355 | Name of the component class. | |
356 | ||
357 | Use bt_error_cause_component_class_actor_get_component_class_type(). | |
358 | </dd> | |
359 | ||
360 | <dt>Component class type</dt> | |
361 | <dd> | |
362 | Type of the component class. | |
363 | ||
364 | Use bt_error_cause_component_class_actor_get_component_class_name(). | |
365 | </dd> | |
366 | ||
367 | <dt>\bt_dt_opt Plugin name</dt> | |
368 | <dd> | |
369 | Name of the \bt_plugin which provides the component class, if any. | |
370 | ||
371 | Use bt_error_cause_component_class_actor_get_plugin_name(). | |
372 | </dd> | |
373 | </dl> | |
374 | */ | |
375 | ||
376 | /*! @{ */ | |
377 | ||
378 | /*! | |
379 | @name Types | |
380 | @{ | |
381 | ||
382 | @typedef struct bt_error bt_error; | |
383 | ||
384 | @brief | |
385 | Error. | |
386 | ||
43c59509 PP |
387 | @typedef struct bt_error_cause bt_error_cause; |
388 | ||
389 | @brief | |
390 | Error cause. | |
391 | ||
392 | @} | |
393 | */ | |
394 | ||
395 | /*! | |
396 | @name Current thread's error | |
397 | @{ | |
398 | */ | |
399 | ||
400 | /*! | |
401 | @brief | |
402 | \em Takes the current thread's error, that is, moves its ownership | |
403 | from the library to the caller. | |
404 | ||
405 | This function can return \c NULL if the current thread has no error. | |
406 | ||
407 | Once you are done with the returned error, do one of: | |
408 | ||
409 | - Call bt_error_release() to free the error object. | |
410 | ||
411 | In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a> | |
412 | terms, this corresponds to catching an exception and discarding it. | |
413 | ||
414 | - Call bt_current_thread_move_error() to move back the error object's | |
415 | ownership to the library. | |
416 | ||
417 | In object-oriented programming terms, this corresponds to catching | |
418 | an exception and rethrowing it. | |
419 | ||
420 | @returns | |
421 | Unique reference of the current thread's error, or \c NULL if the | |
422 | current thread has no error. | |
423 | ||
424 | @post | |
425 | <strong>If this function does not return <code>NULL</code></strong>, | |
426 | the caller owns the returned error. | |
427 | ||
428 | @sa bt_error_release() — | |
429 | Releases (frees) an error. | |
430 | @sa bt_current_thread_move_error() — | |
431 | Moves an error's ownership to the library. | |
432 | */ | |
433 | extern | |
434 | const bt_error *bt_current_thread_take_error(void); | |
435 | ||
436 | /*! | |
437 | @brief | |
438 | Moves the ownership of the error \bt_p{error} from the caller to | |
439 | the library. | |
440 | ||
441 | After you call this function, you don't own \bt_p{error} anymore. | |
442 | ||
443 | In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a> | |
444 | terms, calling this function corresponds to catching an | |
445 | exception and rethrowing it. | |
446 | ||
447 | You can instead release (free) the error with bt_error_release(), which, | |
448 | in object-oriented programming terms, | |
449 | corresponds to catching an exception and discarding it. | |
450 | ||
451 | @param[in] error | |
452 | Error of which to move the ownership from you to the library. | |
453 | ||
454 | @bt_pre_not_null{error} | |
455 | @pre | |
456 | The caller owns \bt_p{error}. | |
457 | ||
458 | @post | |
459 | The library owns \bt_p{error}. | |
460 | ||
461 | @sa bt_error_release() — | |
462 | Releases (frees) an error. | |
463 | @sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() — | |
464 | Calls this function and assigns \c NULL to the expression. | |
465 | */ | |
466 | extern | |
467 | void bt_current_thread_move_error(const bt_error *error); | |
468 | ||
469 | /*! | |
470 | @brief | |
471 | Moves the ownership of the error \bt_p{_error} from the caller to | |
472 | the library, and then sets \bt_p{_error} to \c NULL. | |
473 | ||
474 | @param[in] _error | |
475 | Error of which to move the ownership from you to the library. | |
476 | ||
477 | @bt_pre_not_null{_error} | |
478 | @bt_pre_assign_expr{_error} | |
479 | @pre | |
480 | The caller owns \bt_p{_error}. | |
481 | ||
482 | @post | |
483 | The library owns \bt_p{_error}. | |
484 | ||
485 | @sa bt_current_thread_move_error() — | |
486 | Moves an error's ownership to the library. | |
487 | */ | |
488 | #define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error) \ | |
489 | do { \ | |
490 | bt_current_thread_move_error(_error); \ | |
491 | (_error) = NULL; \ | |
492 | } while (0) | |
493 | ||
494 | /*! | |
495 | @brief | |
496 | Releases the current thread's error, if any. | |
497 | ||
498 | This function is equivalent to: | |
499 | ||
500 | @code | |
501 | bt_error_release(bt_current_thread_take_error()); | |
502 | @endcode | |
503 | ||
504 | @post | |
505 | The current thread has no error. | |
506 | ||
507 | @sa bt_error_release() — | |
508 | Releases (frees) an error. | |
509 | @sa bt_current_thread_take_error — | |
510 | Takes the current thread's error, moving its ownership from the | |
511 | library to the caller. | |
512 | */ | |
513 | extern | |
514 | void bt_current_thread_clear_error(void); | |
515 | ||
516 | /*! @} */ | |
517 | ||
518 | /*! | |
519 | @name Error cause appending | |
520 | @{ | |
521 | */ | |
522 | ||
523 | /*! | |
524 | @brief | |
525 | Status codes for the | |
526 | <code>bt_current_thread_error_append_cause_from_*()</code> | |
527 | functions. | |
528 | */ | |
529 | typedef enum bt_current_thread_error_append_cause_status { | |
530 | /*! | |
531 | @brief | |
532 | Success. | |
533 | */ | |
534 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK = __BT_FUNC_STATUS_OK, | |
535 | ||
536 | /*! | |
537 | @brief | |
538 | Out of memory. | |
539 | */ | |
540 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
541 | } bt_current_thread_error_append_cause_status; | |
542 | ||
543 | /*! | |
544 | @brief | |
545 | Appends an error cause to the current thread's error from a | |
546 | \bt_comp method. | |
547 | ||
548 | This this a <code>printf()</code>-like function starting from the | |
549 | format string parameter \bt_p{message_format}. | |
550 | ||
551 | On success, the appended error cause's module name | |
552 | (see bt_error_cause_get_module_name()) is: | |
553 | ||
554 | @code{.unparsed} | |
555 | NAME: CC-TYPE.PLUGIN-NAME.CC-NAME | |
556 | @endcode | |
557 | ||
558 | or | |
559 | ||
560 | @code{.unparsed} | |
561 | NAME: CC-TYPE.CC-NAME | |
562 | @endcode | |
563 | ||
564 | if no \bt_plugin provides the class of \bt_p{self_component}, with: | |
565 | ||
566 | <dl> | |
567 | <dt>\c NAME</dt> | |
568 | <dd>Name of \bt_p{self_component}.</dd> | |
569 | ||
570 | <dt>\c CC-TYPE</dt> | |
571 | <dd> | |
572 | Type of the \ref api-comp-cls "class" of \bt_p{self_component} | |
573 | (\c src, \c flt, or \c sink). | |
574 | </dd> | |
575 | ||
576 | <dt>\c PLUGIN-NAME</dt> | |
577 | <dd> | |
578 | Name of the plugin which provides the class of | |
579 | \bt_p{self_component}. | |
580 | </dd> | |
581 | ||
582 | <dt>\c CC-NAME</dt> | |
583 | <dd>Name of the class of \bt_p{self_component}.</dd> | |
584 | </dl> | |
585 | ||
586 | @param[in] self_component | |
587 | Self component of the appending method. | |
588 | @param[in] file_name | |
589 | Name of the source file containing the method which appends the | |
590 | error cause. | |
591 | @param[in] line_number | |
592 | Line number of the statement which appends the error cause. | |
593 | @param[in] message_format | |
594 | Format string which specifies how the function converts the | |
595 | subsequent arguments (like <code>printf()</code>). | |
596 | ||
597 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK | |
598 | Success. | |
599 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR | |
600 | Out of memory. | |
601 | ||
602 | @bt_pre_not_null{self_component} | |
603 | @bt_pre_not_null{file_name} | |
604 | @bt_pre_not_null{message_format} | |
605 | @bt_pre_valid_fmt{message_format} | |
606 | ||
607 | @post | |
608 | <strong>On success</strong>, the number of error causes in the | |
609 | current thread's error is incremented. | |
610 | ||
611 | @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() — | |
612 | Calls this function with \c __FILE__ and \c __LINE__ as the | |
613 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
614 | */ | |
8b305066 | 615 | extern __BT_ATTR_FORMAT_PRINTF(4, 5) |
43c59509 PP |
616 | bt_current_thread_error_append_cause_status |
617 | bt_current_thread_error_append_cause_from_component( | |
618 | bt_self_component *self_component, const char *file_name, | |
619 | uint64_t line_number, const char *message_format, ...); | |
620 | ||
621 | /*! | |
622 | @brief | |
623 | Appends an error cause to the current thread's error from a | |
624 | \bt_comp method using \c __FILE__ and \c __LINE__ as the source | |
625 | file name and line number. | |
626 | ||
627 | This macro calls bt_current_thread_error_append_cause_from_component() | |
628 | with \c __FILE__ and \c __LINE__ as its | |
629 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
630 | */ | |
631 | #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_component, _message_format, ...) \ | |
632 | bt_current_thread_error_append_cause_from_component( \ | |
633 | (_self_component), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__) | |
634 | ||
635 | /*! | |
636 | @brief | |
637 | Appends an error cause to the current thread's error from a | |
638 | \bt_msg_iter method. | |
639 | ||
640 | This this a <code>printf()</code>-like function starting from the | |
641 | format string parameter \bt_p{message_format}. | |
642 | ||
643 | On success, the appended error cause's module name | |
644 | (see bt_error_cause_get_module_name()) is: | |
645 | ||
646 | @code{.unparsed} | |
647 | COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME | |
648 | @endcode | |
649 | ||
650 | or | |
651 | ||
652 | @code{.unparsed} | |
653 | COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME | |
654 | @endcode | |
655 | ||
656 | if no \bt_plugin provides the component class of | |
657 | \bt_p{self_message_iterator}, with: | |
658 | ||
659 | <dl> | |
660 | <dt>\c COMP-NAME</dt> | |
661 | <dd>Name of the \bt_comp of \bt_p{self_message_iterator}.</dd> | |
662 | ||
663 | <dt>\c OUT-PORT-NAME</dt> | |
664 | <dd> | |
665 | Name of the \bt_oport from which \bt_p{self_message_iterator}. | |
666 | was created. | |
667 | </dd> | |
668 | ||
669 | <dt>\c CC-TYPE</dt> | |
670 | <dd> | |
671 | Type of the \bt_comp_cls of \bt_p{self_message_iterator} | |
672 | (\c src, \c flt, or \c sink). | |
673 | </dd> | |
674 | ||
675 | <dt>\c PLUGIN-NAME</dt> | |
676 | <dd> | |
677 | Name of the plugin which provides the component class of | |
678 | \bt_p{self_message_iterator}. | |
679 | </dd> | |
680 | ||
681 | <dt>\c CC-NAME</dt> | |
682 | <dd>Name of the component class of \bt_p{self_message_iterator}.</dd> | |
683 | </dl> | |
684 | ||
685 | @param[in] self_message_iterator | |
686 | Self message iterator of the appending method. | |
687 | @param[in] file_name | |
688 | Name of the source file containing the method which appends the | |
689 | error cause. | |
690 | @param[in] line_number | |
691 | Line number of the statement which appends the error cause. | |
692 | @param[in] message_format | |
693 | Format string which specifies how the function converts the | |
694 | subsequent arguments (like <code>printf()</code>). | |
695 | ||
696 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK | |
697 | Success. | |
698 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR | |
699 | Out of memory. | |
700 | ||
701 | @bt_pre_not_null{self_message_iterator} | |
702 | @bt_pre_not_null{file_name} | |
703 | @bt_pre_not_null{message_format} | |
704 | @bt_pre_valid_fmt{message_format} | |
705 | ||
706 | @post | |
707 | <strong>On success</strong>, the number of error causes in the | |
708 | current thread's error is incremented. | |
709 | ||
710 | @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() — | |
711 | Calls this function with \c __FILE__ and \c __LINE__ as the | |
712 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
713 | */ | |
8b305066 | 714 | extern __BT_ATTR_FORMAT_PRINTF(4, 5) |
43c59509 PP |
715 | bt_current_thread_error_append_cause_status |
716 | bt_current_thread_error_append_cause_from_message_iterator( | |
717 | bt_self_message_iterator *self_message_iterator, | |
718 | const char *file_name, uint64_t line_number, | |
719 | const char *message_format, ...); | |
720 | ||
721 | /*! | |
722 | @brief | |
723 | Appends an error cause to the current thread's error from a | |
724 | \bt_msg_iter method using \c __FILE__ and \c __LINE__ as the source file | |
725 | name and line number. | |
726 | ||
727 | This macro calls | |
728 | bt_current_thread_error_append_cause_from_message_iterator() with | |
729 | \c __FILE__ and \c __LINE__ as its | |
730 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
731 | */ | |
732 | #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_message_iterator, _message_format, ...) \ | |
733 | bt_current_thread_error_append_cause_from_message_iterator( \ | |
734 | (_self_message_iterator), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__) | |
735 | ||
736 | /*! | |
737 | @brief | |
738 | Appends an error cause to the current thread's error from a | |
739 | \bt_comp_cls method. | |
740 | ||
741 | This this a <code>printf()</code>-like function starting from the | |
742 | format string parameter \bt_p{message_format}. | |
743 | ||
744 | As of \bt_name_version_min_maj, the only component class method is the | |
745 | \ref api-qexec "query" method. | |
746 | ||
747 | On success, the appended error cause's module name | |
748 | (see bt_error_cause_get_module_name()) is: | |
749 | ||
750 | @code{.unparsed} | |
751 | CC-TYPE.PLUGIN-NAME.CC-NAME | |
752 | @endcode | |
753 | ||
754 | or | |
755 | ||
756 | @code{.unparsed} | |
757 | CC-TYPE.CC-NAME | |
758 | @endcode | |
759 | ||
760 | if no \bt_plugin provides \bt_p{self_component_class}, with: | |
761 | ||
762 | <dl> | |
763 | <dt>\c CC-TYPE</dt> | |
764 | <dd> | |
765 | Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink). | |
766 | </dd> | |
767 | ||
768 | <dt>\c PLUGIN-NAME</dt> | |
769 | <dd> | |
770 | Name of the plugin which provides \bt_p{self_component_class}. | |
771 | </dd> | |
772 | ||
773 | <dt>\c CC-NAME</dt> | |
774 | <dd>Name of \bt_p{self_component_class}.</dd> | |
775 | </dl> | |
776 | ||
777 | @param[in] self_component_class | |
778 | Self component class of the appending method. | |
779 | @param[in] file_name | |
780 | Name of the source file containing the method which appends the | |
781 | error cause. | |
782 | @param[in] line_number | |
783 | Line number of the statement which appends the error cause. | |
784 | @param[in] message_format | |
785 | Format string which specifies how the function converts the | |
786 | subsequent arguments (like <code>printf()</code>). | |
787 | ||
788 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK | |
789 | Success. | |
790 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR | |
791 | Out of memory. | |
792 | ||
793 | @bt_pre_not_null{self_component_class} | |
794 | @bt_pre_not_null{file_name} | |
795 | @bt_pre_not_null{message_format} | |
796 | @bt_pre_valid_fmt{message_format} | |
797 | ||
798 | @post | |
799 | <strong>On success</strong>, the number of error causes in the | |
800 | current thread's error is incremented. | |
801 | ||
802 | @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() — | |
803 | Calls this function with \c __FILE__ and \c __LINE__ as the | |
804 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
805 | */ | |
8b305066 | 806 | extern __BT_ATTR_FORMAT_PRINTF(4, 5) |
43c59509 PP |
807 | bt_current_thread_error_append_cause_status |
808 | bt_current_thread_error_append_cause_from_component_class( | |
809 | bt_self_component_class *self_component_class, | |
810 | const char *file_name, uint64_t line_number, | |
811 | const char *message_format, ...); | |
812 | ||
813 | /*! | |
814 | @brief | |
815 | Appends an error cause to the current thread's error from a | |
816 | component class method using \c __FILE__ and \c __LINE__ as the | |
817 | source file name and line number. | |
818 | ||
819 | This macro calls | |
820 | bt_current_thread_error_append_cause_from_component_class() | |
821 | with \c __FILE__ and \c __LINE__ as its | |
822 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
823 | */ | |
824 | #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_component_class, _message_format, ...) \ | |
825 | bt_current_thread_error_append_cause_from_component_class( \ | |
826 | (_self_component_class), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__) | |
827 | ||
828 | /*! | |
829 | @brief | |
830 | Appends an error cause to the current thread's error from any | |
831 | function. | |
832 | ||
833 | Use this function when you cannot use | |
834 | bt_current_thread_error_append_cause_from_component(), | |
835 | bt_current_thread_error_append_cause_from_message_iterator(), | |
836 | or bt_current_thread_error_append_cause_from_component_class(). | |
837 | ||
838 | This this a <code>printf()</code>-like function starting from the | |
839 | format string parameter \bt_p{message_format}. | |
840 | ||
841 | @param[in] module_name | |
842 | Module name of the error cause to append. | |
843 | @param[in] file_name | |
844 | Name of the source file containing the method which appends the | |
845 | error cause. | |
846 | @param[in] line_number | |
847 | Line number of the statement which appends the error cause. | |
848 | @param[in] message_format | |
849 | Format string which specifies how the function converts the | |
850 | subsequent arguments (like <code>printf()</code>). | |
851 | ||
852 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK | |
853 | Success. | |
854 | @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR | |
855 | Out of memory. | |
856 | ||
857 | @bt_pre_not_null{module_name} | |
858 | @bt_pre_not_null{file_name} | |
859 | @bt_pre_not_null{message_format} | |
860 | @bt_pre_valid_fmt{message_format} | |
861 | ||
862 | @post | |
863 | <strong>On success</strong>, the number of error causes in the | |
864 | current thread's error is incremented. | |
865 | ||
866 | @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() — | |
867 | Calls this function with \c __FILE__ and \c __LINE__ as the | |
868 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
869 | */ | |
8b305066 | 870 | extern __BT_ATTR_FORMAT_PRINTF(4, 5) |
43c59509 PP |
871 | bt_current_thread_error_append_cause_status |
872 | bt_current_thread_error_append_cause_from_unknown( | |
873 | const char *module_name, const char *file_name, | |
874 | uint64_t line_number, const char *message_format, ...); | |
875 | ||
876 | /*! | |
877 | @brief | |
878 | Appends an error cause to the current thread's error from any | |
879 | function using \c __FILE__ and \c __LINE__ as the source | |
880 | file name and line number. | |
881 | ||
882 | Use this function when you cannot use | |
883 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(), | |
884 | BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(), | |
885 | or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(). | |
886 | ||
887 | This macro calls bt_current_thread_error_append_cause_from_unknown() | |
888 | with \c __FILE__ and \c __LINE__ as its | |
889 | \bt_p{file_name} and \bt_p{line_number} parameters. | |
890 | */ | |
891 | #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _message_format, ...) \ | |
892 | bt_current_thread_error_append_cause_from_unknown( \ | |
893 | (_module_name), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__) | |
894 | ||
895 | /*! @} */ | |
896 | ||
897 | /*! | |
898 | @name Error | |
899 | @{ | |
900 | */ | |
901 | ||
902 | /*! | |
903 | @brief | |
904 | Returns the number of error causes contained in the error | |
905 | \bt_p{error}. | |
906 | ||
907 | @param[in] error | |
908 | Error of which to get the number of contained error causes. | |
909 | ||
910 | @returns | |
911 | Number of contained error causes in \bt_p{error}. | |
912 | ||
913 | @bt_pre_not_null{error} | |
914 | */ | |
915 | extern | |
916 | uint64_t bt_error_get_cause_count(const bt_error *error); | |
917 | ||
918 | /*! | |
919 | @brief | |
920 | Borrows the error cause at index \bt_p{index} from the | |
921 | error \bt_p{error}. | |
922 | ||
923 | @param[in] error | |
924 | Error from which to borrow the error cause at index \bt_p{index}. | |
925 | @param[in] index | |
926 | Index of the error cause to borrow from \bt_p{error}. | |
927 | ||
928 | @returns | |
929 | @parblock | |
930 | \em Borrowed reference of the error cause of | |
931 | \bt_p{error} at index \bt_p{index}. | |
932 | ||
933 | The returned pointer remains valid until \bt_p{error} is modified. | |
934 | @endparblock | |
935 | ||
936 | @bt_pre_not_null{error} | |
937 | @pre | |
938 | \bt_p{index} is less than the number of error causes in | |
939 | \bt_p{error} (as returned by bt_error_get_cause_count()). | |
940 | */ | |
941 | extern | |
942 | const bt_error_cause *bt_error_borrow_cause_by_index( | |
943 | const bt_error *error, uint64_t index); | |
944 | ||
945 | /*! | |
946 | @brief | |
947 | Releases (frees) the error \bt_p{error}. | |
948 | ||
949 | After you call this function, \bt_p{error} does not exist. | |
950 | ||
951 | Take the current thread's error with bt_current_thread_take_error(). | |
952 | ||
953 | In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a> | |
954 | terms, calling this function corresponds to catching an | |
955 | exception and discarding it. | |
956 | ||
957 | You can instead move the ownership of \bt_p{error} to the library with | |
958 | bt_current_thread_move_error(), which, | |
959 | in object-oriented programming terms, | |
960 | corresponds to catching an exception and rethrowing it. | |
961 | ||
962 | @param[in] error | |
963 | Error to release (free). | |
964 | ||
965 | @bt_pre_not_null{error} | |
966 | ||
967 | @post | |
968 | \bt_p{error} does not exist. | |
969 | ||
970 | @sa bt_current_thread_move_error() — | |
971 | Moves an error's ownership to the library. | |
972 | */ | |
973 | extern | |
974 | void bt_error_release(const bt_error *error); | |
975 | ||
976 | /*! @} */ | |
977 | ||
978 | /*! | |
979 | @name Error cause: common | |
980 | @{ | |
981 | */ | |
982 | ||
983 | /*! | |
984 | @brief | |
985 | Error cause actor type enumerators. | |
986 | */ | |
987 | typedef enum bt_error_cause_actor_type { | |
988 | /*! | |
989 | @brief | |
990 | Any function. | |
991 | */ | |
992 | BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN = 1 << 0, | |
993 | ||
994 | /*! | |
995 | @brief | |
996 | Component method. | |
997 | */ | |
998 | BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT = 1 << 1, | |
999 | ||
1000 | /*! | |
1001 | @brief | |
1002 | Component class method. | |
1003 | */ | |
1004 | BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS = 1 << 2, | |
1005 | ||
1006 | /*! | |
1007 | @brief | |
1008 | Message iterator method. | |
1009 | */ | |
1010 | BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR = 1 << 3, | |
1011 | } bt_error_cause_actor_type; | |
1012 | ||
1013 | /*! | |
1014 | @brief | |
1015 | Returns the actor type enumerator of the error cause | |
1016 | \bt_p{error_cause}. | |
1017 | ||
1018 | @param[in] error_cause | |
1019 | Error cause of which to get the actor type enumerator. | |
1020 | ||
1021 | @returns | |
1022 | Actor type enumerator of \bt_p{error_cause}. | |
1023 | ||
1024 | @bt_pre_not_null{error_cause} | |
1025 | */ | |
1026 | extern | |
1027 | bt_error_cause_actor_type bt_error_cause_get_actor_type( | |
1028 | const bt_error_cause *error_cause); | |
1029 | ||
1030 | /*! | |
1031 | @brief | |
1032 | Returns the message of the error cause \bt_p{error_cause}. | |
1033 | ||
1034 | @param[in] error_cause | |
1035 | Error cause of which to get the message. | |
1036 | ||
1037 | @returns | |
1038 | @parblock | |
1039 | Message of \bt_p{error_cause}. | |
1040 | ||
1041 | The returned pointer remains valid as long as the error which | |
1042 | contains \bt_p{error_cause} exists. | |
1043 | @endparblock | |
1044 | ||
1045 | @bt_pre_not_null{error_cause} | |
1046 | */ | |
1047 | extern | |
1048 | const char *bt_error_cause_get_message(const bt_error_cause *error_cause); | |
1049 | ||
1050 | /*! | |
1051 | @brief | |
1052 | Returns the module name of the error cause \bt_p{error_cause}. | |
1053 | ||
1054 | @param[in] error_cause | |
1055 | Error cause of which to get the module name. | |
1056 | ||
1057 | @returns | |
1058 | @parblock | |
1059 | Module name of \bt_p{error_cause}. | |
1060 | ||
1061 | The returned pointer remains valid as long as the error which | |
1062 | contains \bt_p{error_cause} exists. | |
1063 | @endparblock | |
1064 | ||
1065 | @bt_pre_not_null{error_cause} | |
1066 | */ | |
1067 | extern | |
1068 | const char *bt_error_cause_get_module_name(const bt_error_cause *error_cause); | |
1069 | ||
1070 | /*! | |
1071 | @brief | |
1072 | Returns the name of the source file which contains the function | |
1073 | which appended the error cause \bt_p{error_cause} to the | |
1074 | current thread's error. | |
1075 | ||
1076 | @param[in] error_cause | |
1077 | Error cause of which to get the source file name. | |
1078 | ||
1079 | @returns | |
1080 | @parblock | |
1081 | Source file name of \bt_p{error_cause}. | |
1082 | ||
1083 | The returned pointer remains valid as long as the error which | |
1084 | contains \bt_p{error_cause} exists. | |
1085 | @endparblock | |
1086 | ||
1087 | @bt_pre_not_null{error_cause} | |
1088 | */ | |
1089 | extern | |
1090 | const char *bt_error_cause_get_file_name(const bt_error_cause *error_cause); | |
1091 | ||
1092 | /*! | |
1093 | @brief | |
1094 | Returns the line number of the statement | |
1095 | which appended the error cause \bt_p{error_cause} to the | |
1096 | current thread's error. | |
1097 | ||
1098 | @param[in] error_cause | |
1099 | Error cause of which to get the source statement's line number. | |
1100 | ||
1101 | @returns | |
1102 | Source statement's line number of \bt_p{error_cause}. | |
1103 | ||
1104 | @bt_pre_not_null{error_cause} | |
1105 | */ | |
1106 | extern | |
1107 | uint64_t bt_error_cause_get_line_number(const bt_error_cause *error_cause); | |
1108 | ||
1109 | /*! @} */ | |
1110 | ||
1111 | /*! | |
1112 | @name Error cause with a component actor | |
1113 | @{ | |
1114 | */ | |
1115 | ||
1116 | /*! | |
1117 | @brief | |
1118 | Returns the name of the \bt_comp of which a method | |
1119 | appended the error cause \bt_p{error_cause} to the current | |
1120 | thread's error. | |
1121 | ||
1122 | @param[in] error_cause | |
1123 | Error cause of which to get the component name. | |
1124 | ||
1125 | @returns | |
1126 | @parblock | |
1127 | Component name of \bt_p{error_cause}. | |
1128 | ||
1129 | The returned pointer remains valid as long as the error which | |
1130 | contains \bt_p{error_cause} exists. | |
1131 | @endparblock | |
1132 | ||
1133 | @bt_pre_not_null{error_cause} | |
1134 | @pre | |
1135 | The actor type of \bt_p{error_cause} is | |
1136 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT. | |
1137 | */ | |
1138 | extern | |
1139 | const char *bt_error_cause_component_actor_get_component_name( | |
1140 | const bt_error_cause *error_cause); | |
1141 | ||
1142 | /*! | |
1143 | @brief | |
1144 | Returns the \ref api-comp-cls "class" type of the | |
1145 | \bt_comp of which a method appended the error cause | |
1146 | \bt_p{error_cause} to the current thread's error. | |
1147 | ||
1148 | @param[in] error_cause | |
1149 | Error cause of which to get the component class type. | |
1150 | ||
1151 | @returns | |
1152 | Component class type of \bt_p{error_cause}. | |
1153 | ||
1154 | @bt_pre_not_null{error_cause} | |
1155 | @pre | |
1156 | The actor type of \bt_p{error_cause} is | |
1157 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT. | |
1158 | */ | |
1159 | extern | |
1160 | bt_component_class_type bt_error_cause_component_actor_get_component_class_type( | |
1161 | const bt_error_cause *error_cause); | |
1162 | ||
1163 | /*! | |
1164 | @brief | |
1165 | Returns the \ref api-comp-cls "class" name of the | |
1166 | \bt_comp of which a method appended the error cause | |
1167 | \bt_p{error_cause} to the current thread's error. | |
1168 | ||
1169 | @param[in] error_cause | |
1170 | Error cause of which to get the component class name. | |
1171 | ||
1172 | @returns | |
1173 | @parblock | |
1174 | Component class name of \bt_p{error_cause}. | |
1175 | ||
1176 | The returned pointer remains valid as long as the error which | |
1177 | contains \bt_p{error_cause} exists. | |
1178 | @endparblock | |
1179 | ||
1180 | @bt_pre_not_null{error_cause} | |
1181 | @pre | |
1182 | The actor type of \bt_p{error_cause} is | |
1183 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT. | |
1184 | */ | |
1185 | extern | |
1186 | const char *bt_error_cause_component_actor_get_component_class_name( | |
1187 | const bt_error_cause *error_cause); | |
1188 | ||
1189 | /*! | |
1190 | @brief | |
1191 | Returns the name of the \bt_plugin which provides the | |
1192 | \ref api-comp-cls "class" of the \bt_comp of which a method | |
1193 | appended the error cause \bt_p{error_cause} to the | |
1194 | current thread's error. | |
1195 | ||
1196 | This function returns \c NULL if no plugin provides the error cause's | |
1197 | component class. | |
1198 | ||
1199 | @param[in] error_cause | |
1200 | Error cause of which to get the plugin name. | |
1201 | ||
1202 | @returns | |
1203 | @parblock | |
1204 | Plugin name of \bt_p{error_cause}, or \c NULL if no plugin | |
1205 | provides the component class of \bt_p{error_cause}. | |
1206 | ||
1207 | The returned pointer remains valid as long as the error which | |
1208 | contains \bt_p{error_cause} exists. | |
1209 | @endparblock | |
1210 | ||
1211 | @bt_pre_not_null{error_cause} | |
1212 | @pre | |
1213 | The actor type of \bt_p{error_cause} is | |
1214 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT. | |
1215 | */ | |
1216 | extern | |
1217 | const char *bt_error_cause_component_actor_get_plugin_name( | |
1218 | const bt_error_cause *error_cause); | |
1219 | ||
1220 | /*! @} */ | |
1221 | ||
1222 | /*! | |
1223 | @name Error cause with a message iterator actor | |
1224 | @{ | |
1225 | */ | |
1226 | ||
1227 | /*! | |
1228 | @brief | |
1229 | Returns the name of the \bt_oport from which was created | |
1230 | the message iterator of which the method | |
1231 | appended the error cause \bt_p{error_cause} to the current | |
1232 | thread's error. | |
1233 | ||
1234 | @param[in] error_cause | |
1235 | Error cause of which to get the output port name. | |
1236 | ||
1237 | @returns | |
1238 | @parblock | |
1239 | Output port name of \bt_p{error_cause}. | |
1240 | ||
1241 | The returned pointer remains valid as long as the error which | |
1242 | contains \bt_p{error_cause} exists. | |
1243 | @endparblock | |
1244 | ||
1245 | @bt_pre_not_null{error_cause} | |
1246 | @pre | |
1247 | The actor type of \bt_p{error_cause} is | |
1248 | #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR. | |
1249 | */ | |
1250 | extern | |
1251 | const char *bt_error_cause_message_iterator_actor_get_component_output_port_name( | |
1252 | const bt_error_cause *error_cause); | |
1253 | ||
1254 | /*! | |
1255 | @brief | |
1256 | Returns the name of the \bt_comp of which a message iterator method | |
1257 | appended the error cause \bt_p{error_cause} to the current | |
1258 | thread's error. | |
1259 | ||
1260 | @param[in] error_cause | |
1261 | Error cause of which to get the component name. | |
1262 | ||
1263 | @returns | |
1264 | @parblock | |
1265 | Component name of \bt_p{error_cause}. | |
1266 | ||
1267 | The returned pointer remains valid as long as the error which | |
1268 | contains \bt_p{error_cause} exists. | |
1269 | @endparblock | |
1270 | ||
1271 | @bt_pre_not_null{error_cause} | |
1272 | @pre | |
1273 | The actor type of \bt_p{error_cause} is | |
1274 | #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR. | |
1275 | */ | |
1276 | extern | |
1277 | const char *bt_error_cause_message_iterator_actor_get_component_name( | |
1278 | const bt_error_cause *error_cause); | |
1279 | ||
1280 | /*! | |
1281 | @brief | |
1282 | Returns the \ref api-comp-cls "class" type of the | |
1283 | \bt_comp of which a message iterator method appended the error cause | |
1284 | \bt_p{error_cause} to the current thread's error. | |
1285 | ||
1286 | @param[in] error_cause | |
1287 | Error cause of which to get the component class type. | |
1288 | ||
1289 | @returns | |
1290 | Component class type of \bt_p{error_cause}. | |
1291 | ||
1292 | @bt_pre_not_null{error_cause} | |
1293 | @pre | |
1294 | The actor type of \bt_p{error_cause} is | |
1295 | #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR. | |
1296 | */ | |
1297 | extern | |
1298 | bt_component_class_type | |
1299 | bt_error_cause_message_iterator_actor_get_component_class_type( | |
1300 | const bt_error_cause *error_cause); | |
1301 | ||
1302 | /*! | |
1303 | @brief | |
1304 | Returns the \ref api-comp-cls "class" name of the | |
1305 | \bt_comp of which a message iterator method appended the error cause | |
1306 | \bt_p{error_cause} to the current thread's error. | |
1307 | ||
1308 | @param[in] error_cause | |
1309 | Error cause of which to get the component class name. | |
1310 | ||
1311 | @returns | |
1312 | @parblock | |
1313 | Component class name of \bt_p{error_cause}. | |
1314 | ||
1315 | The returned pointer remains valid as long as the error which | |
1316 | contains \bt_p{error_cause} exists. | |
1317 | @endparblock | |
1318 | ||
1319 | @bt_pre_not_null{error_cause} | |
1320 | @pre | |
1321 | The actor type of \bt_p{error_cause} is | |
1322 | #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR. | |
1323 | */ | |
1324 | extern | |
1325 | const char *bt_error_cause_message_iterator_actor_get_component_class_name( | |
1326 | const bt_error_cause *error_cause); | |
1327 | ||
1328 | /*! | |
1329 | @brief | |
1330 | Returns the name of the \bt_plugin which provides the | |
1331 | \ref api-comp-cls "class" of the \bt_comp of which a | |
1332 | message iterator method | |
1333 | appended the error cause \bt_p{error_cause} to the | |
1334 | current thread's error. | |
1335 | ||
1336 | This function returns \c NULL if no plugin provides the error cause's | |
1337 | component class. | |
1338 | ||
1339 | @param[in] error_cause | |
1340 | Error cause of which to get the plugin name. | |
1341 | ||
1342 | @returns | |
1343 | @parblock | |
1344 | Plugin name of \bt_p{error_cause}, or \c NULL if no plugin | |
1345 | provides the component class of \bt_p{error_cause}. | |
1346 | ||
1347 | The returned pointer remains valid as long as the error which | |
1348 | contains \bt_p{error_cause} exists. | |
1349 | @endparblock | |
1350 | ||
1351 | @bt_pre_not_null{error_cause} | |
1352 | @pre | |
1353 | The actor type of \bt_p{error_cause} is | |
1354 | #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR. | |
1355 | */ | |
1356 | extern | |
1357 | const char *bt_error_cause_message_iterator_actor_get_plugin_name( | |
1358 | const bt_error_cause *error_cause); | |
1359 | ||
1360 | /*! @} */ | |
1361 | ||
1362 | /*! | |
1363 | @name Error cause with a component class actor | |
1364 | @{ | |
1365 | */ | |
1366 | ||
1367 | /*! | |
1368 | @brief | |
1369 | Returns the name of the \bt_comp_cls | |
1370 | of which a method appended the error cause | |
1371 | \bt_p{error_cause} to the current thread's error. | |
1372 | ||
1373 | @param[in] error_cause | |
1374 | Error cause of which to get the component class name. | |
1375 | ||
1376 | @returns | |
1377 | Component class name of \bt_p{error_cause}. | |
1378 | ||
1379 | @bt_pre_not_null{error_cause} | |
1380 | @pre | |
1381 | The actor type of \bt_p{error_cause} is | |
1382 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS. | |
1383 | */ | |
1384 | extern | |
1385 | bt_component_class_type | |
1386 | bt_error_cause_component_class_actor_get_component_class_type( | |
1387 | const bt_error_cause *error_cause); | |
1388 | ||
1389 | /*! | |
1390 | @brief | |
1391 | Returns the name of the \bt_comp_cls | |
1392 | of which a method appended the error cause | |
1393 | \bt_p{error_cause} to the current thread's error. | |
1394 | ||
1395 | @param[in] error_cause | |
1396 | Error cause of which to get the component class name. | |
1397 | ||
1398 | @returns | |
1399 | @parblock | |
1400 | Component class name of \bt_p{error_cause}. | |
1401 | ||
1402 | The returned pointer remains valid as long as the error which | |
1403 | contains \bt_p{error_cause} exists. | |
1404 | @endparblock | |
1405 | ||
1406 | @bt_pre_not_null{error_cause} | |
1407 | @pre | |
1408 | The actor type of \bt_p{error_cause} is | |
1409 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS. | |
1410 | */ | |
1411 | extern | |
1412 | const char *bt_error_cause_component_class_actor_get_component_class_name( | |
1413 | const bt_error_cause *error_cause); | |
1414 | ||
1415 | /*! | |
1416 | @brief | |
1417 | Returns the name of the \bt_plugin which provides the | |
1418 | \bt_comp_cls of which a method | |
1419 | appended the error cause \bt_p{error_cause} to the | |
1420 | current thread's error. | |
1421 | ||
1422 | This function returns \c NULL if no plugin provides the error cause's | |
1423 | component class. | |
1424 | ||
1425 | @param[in] error_cause | |
1426 | Error cause of which to get the plugin name. | |
1427 | ||
1428 | @returns | |
1429 | @parblock | |
1430 | Plugin name of \bt_p{error_cause}, or \c NULL if no plugin | |
1431 | provides the component class of \bt_p{error_cause}. | |
1432 | ||
1433 | The returned pointer remains valid as long as the error which | |
1434 | contains \bt_p{error_cause} exists. | |
1435 | @endparblock | |
1436 | ||
1437 | @bt_pre_not_null{error_cause} | |
1438 | @pre | |
1439 | The actor type of \bt_p{error_cause} is | |
1440 | #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS. | |
1441 | */ | |
1442 | extern | |
1443 | const char *bt_error_cause_component_class_actor_get_plugin_name( | |
1444 | const bt_error_cause *error_cause); | |
1445 | ||
1446 | /*! @} */ | |
1447 | ||
1448 | /*! @} */ | |
1449 | ||
1450 | #ifdef __cplusplus | |
1451 | } | |
1452 | #endif | |
1453 | ||
1454 | #endif /* BABELTRACE2_ERROR_REPORTING_H */ |