Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / error-reporting.h
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() &mdash;
446 Releases (frees) an error.
447 @sa bt_current_thread_move_error() &mdash;
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() &mdash;
479 Releases (frees) an error.
480 @sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() &mdash;
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() &mdash;
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() &mdash;
525 Releases (frees) an error.
526 @sa bt_current_thread_take_error &mdash;
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() &mdash;
629 Calls this function with \c __FILE__ and \c __LINE__ as the
630 \bt_p{file_name} and \bt_p{line_number} parameters.
631 */
632 extern
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() &mdash;
728 Calls this function with \c __FILE__ and \c __LINE__ as the
729 \bt_p{file_name} and \bt_p{line_number} parameters.
730 */
731 extern
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() &mdash;
820 Calls this function with \c __FILE__ and \c __LINE__ as the
821 \bt_p{file_name} and \bt_p{line_number} parameters.
822 */
823 extern
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() &mdash;
884 Calls this function with \c __FILE__ and \c __LINE__ as the
885 \bt_p{file_name} and \bt_p{line_number} parameters.
886 */
887 extern
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() &mdash;
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 */
This page took 0.062705 seconds and 4 git commands to generate.