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