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