2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
9 #ifndef BABELTRACE2_ERROR_REPORTING_H
10 #define BABELTRACE2_ERROR_REPORTING_H
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
19 #include <babeltrace2/graph/component-class.h>
26 @defgroup api-error Error reporting
29 Error reporting functions and macros.
31 This module contains functions and macros to report rich errors from a
32 user function (a \bt_comp_cls method, a
33 \ref api-qexec "query operation", or a trace processing \bt_graph
34 listener, for example) to any function caller.
36 Because \bt_name orchestrates pieces written by different authors,
37 it is important that an error which occurs deep into the function call
38 stack can percolate up to its callers.
40 The very basic mechanism to report an error from a function is to
41 \ref api-fund-func-status "return an error status"
42 (a status code enumerator which contains the word
43 \c ERROR): each function caller can clean its own context and return an
44 error status code itself until one caller "catches" the status code and
45 reacts to it. For example, the reaction can be to show an error message
48 This error reporting API adds a layer so that each function which
49 returns an error status code can append a message which describes the
50 cause of the error within the function's context.
52 Functions append error causes to the current thread's error. Having one
53 error object per thread makes this API thread-safe.
55 Here's a visual, step-by-step example:
57 @image html error-reporting-steps-1234.png
59 -# The trace processing \bt_graph user calls bt_graph_run().
61 -# bt_graph_run() calls the
62 \ref api-comp-cls-dev-meth-consume "consuming method" of the
65 -# The sink \bt_comp calls bt_message_iterator_next() on its upstream
68 -# bt_message_iterator_next() calls the source message iterator's
69 \link api-msg-iter-cls-meth-next "next" method\endlink.
71 @image html error-reporting-step-5.png
75 An error occurs within the "next" method of the source message
76 iterator: the function cannot read a file because permission was
80 @image html error-reporting-step-6.png
84 The source message iterator's "next" method appends the error
85 cause <em>"Cannot read file /some/file: permission denied"</em>
87 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR.
90 @image html error-reporting-step-7.png
94 bt_message_iterator_next() appends
95 the error cause <em>"Message iterator's 'next' method failed"</em>
96 with details about the source component and
97 returns #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR.
100 @image html error-reporting-steps-89.png
104 The sink component's "consume" method appends the error
105 cause <em>"Cannot consume upstream message iterator's messages"</em>
106 and returns #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR.
109 bt_graph_run() appends the error cause <em>"Component's 'consume'
110 method failed"</em> with details about the sink component and
111 returns #BT_GRAPH_RUN_STATUS_ERROR.
114 At this point, the current thread's error contains four causes:
116 - <em>"Cannot read file /some/file: permission denied"</em>
117 - <em>"Message iterator's 'next' method failed"</em>
118 - <em>"Cannot consume upstream message iterator's messages"</em>
119 - <em>"Component's 'consume' method failed"</em>
121 This list of error causes is much richer for the end user than dealing
122 only with #BT_GRAPH_RUN_STATUS_ERROR (the last error status code).
124 Both error (#bt_error) and error cause (#bt_error_cause) objects are
125 \ref api-fund-unique-object "unique objects":
127 - An error belongs to either
128 the library or you (see \ref api-error-handle "Handle an error").
130 - An error cause belongs to the error which contains it.
132 <h1>\anchor api-error-append-cause Append an error cause</h1>
134 When your function returns an error status code, use one of the
135 <code>bt_current_thread_error_append_cause_from_*()</code>
136 functions or <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code>
137 macros to append an error cause to the
138 current thread's error. Use the appropriate function or macro
139 depending on your function's actor amongst:
144 Append an error cause from a \bt_comp method.
146 Use bt_current_thread_error_append_cause_from_component() or
147 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT().
150 <dt>Message iterator</dt>
152 Append an error cause from a \bt_msg_iter method.
154 Use bt_current_thread_error_append_cause_from_message_iterator() or
155 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR().
158 <dt>Component class</dt>
160 Append an error cause from a \bt_comp_cls method
163 Use bt_current_thread_error_append_cause_from_component_class() or
164 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
169 Append an error cause from any other function, for example
170 a \bt_graph listener or a function of your user application).
172 Use bt_current_thread_error_append_cause_from_unknown() or
173 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN().
177 The <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code> macros
178 uses \c __FILE__ and \c __LINE__ as the file name and line number
179 parameters of their corresponding
180 <code>bt_current_thread_error_append_cause_from_*()</code> function.
182 <h1>\anchor api-error-handle Handle an error</h1>
184 If any libbabeltrace2 function you call returns an error status code, do
187 - Return an error status code too.
189 In that case, you \em can
190 \ref api-error-append-cause "append an error cause" to the current
193 - \em Take the current thread's error with
194 bt_current_thread_take_error().
196 This function moves the ownership of the error object from the library
199 At this point, you can inspect its causes with
200 bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and
203 - Call bt_error_release() to free the error object.
205 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
206 terms, this corresponds to catching an exception and discarding it.
208 - Call bt_current_thread_move_error() to move back the error object's
209 ownership to the library.
211 In object-oriented programming terms, this corresponds to catching
212 an exception and rethrowing it.
214 bt_current_thread_clear_error() is a helper which is the equivalent of:
217 bt_error_release(bt_current_thread_take_error());
222 All error causes have the type #bt_error_cause.
224 There are four types of error cause actors:
231 Get the type enumerator of an error cause's actor with
232 bt_error_cause_get_actor_type().
234 An error cause has the following common properties:
239 Description of the error cause.
241 Use bt_error_cause_get_message().
246 Name of the module causing the error.
248 For example, libbabeltrace2 uses "libbabeltrace2" and the \bt_cli
249 CLI tool uses "Babeltrace CLI".
251 Use bt_error_cause_get_module_name().
256 Name of the source file causing the error.
258 Use bt_error_cause_get_file_name().
263 Line number of the statement causing the error.
265 Use bt_error_cause_get_line_number().
269 <h2>Error cause with a component actor</h2>
271 An error cause with a \bt_comp actor has the following specific
275 <dt>Component name</dt>
277 Name of the component.
279 Use bt_error_cause_component_actor_get_component_name().
282 <dt>Component class name</dt>
284 Name of the component's \ref api-comp-cls "class".
286 Use bt_error_cause_component_actor_get_component_class_type().
289 <dt>Component class type</dt>
291 Type of the component's class.
293 Use bt_error_cause_component_actor_get_component_class_name().
296 <dt>\bt_dt_opt Plugin name</dt>
298 Name of the \bt_plugin which provides the component's class, if any.
300 Use bt_error_cause_component_actor_get_plugin_name().
304 <h2>Error cause with a message iterator actor</h2>
306 An error cause with a \bt_msg_iter actor has the following specific
310 <dt>Component output port name</dt>
312 Name of the \bt_comp \bt_oport from which the message iterator
315 Use bt_error_cause_component_actor_get_component_name().
318 <dt>Component name</dt>
320 Name of the component.
322 Use bt_error_cause_component_actor_get_component_name().
325 bt_error_cause_message_iterator_actor_get_component_output_port_name
327 <dt>Component class name</dt>
329 Name of the component's \ref api-comp-cls "class".
331 Use bt_error_cause_component_actor_get_component_class_type().
334 <dt>Component class type</dt>
336 Type of the component's class.
338 Use bt_error_cause_component_actor_get_component_class_name().
341 <dt>\bt_dt_opt Plugin name</dt>
343 Name of the \bt_plugin which provides the component's class, if any.
345 Use bt_error_cause_component_actor_get_plugin_name().
349 <h2>Error cause with a component class actor</h2>
351 An error cause with a \bt_comp_cls actor has the following specific
355 <dt>Component class name</dt>
357 Name of the component class.
359 Use bt_error_cause_component_class_actor_get_component_class_type().
362 <dt>Component class type</dt>
364 Type of the component class.
366 Use bt_error_cause_component_class_actor_get_component_class_name().
369 <dt>\bt_dt_opt Plugin name</dt>
371 Name of the \bt_plugin which provides the component class, if any.
373 Use bt_error_cause_component_class_actor_get_plugin_name().
384 @typedef struct bt_error bt_error;
389 @typedef struct bt_error_cause bt_error_cause;
398 @name Current thread's error
404 \em Takes the current thread's error, that is, moves its ownership
405 from the library to the caller.
407 This function can return \c NULL if the current thread has no error.
409 Once you are done with the returned error, do one of:
411 - Call bt_error_release() to free the error object.
413 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
414 terms, this corresponds to catching an exception and discarding it.
416 - Call bt_current_thread_move_error() to move back the error object's
417 ownership to the library.
419 In object-oriented programming terms, this corresponds to catching
420 an exception and rethrowing it.
423 Unique reference of the current thread's error, or \c NULL if the
424 current thread has no error.
427 <strong>If this function does not return <code>NULL</code></strong>,
428 the caller owns the returned error.
430 @sa bt_error_release() —
431 Releases (frees) an error.
432 @sa bt_current_thread_move_error() —
433 Moves an error's ownership to the library.
436 const bt_error
*bt_current_thread_take_error(void);
440 Moves the ownership of the error \bt_p{error} from the caller to
443 After you call this function, you don't own \bt_p{error} anymore.
445 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
446 terms, calling this function corresponds to catching an
447 exception and rethrowing it.
449 You can instead release (free) the error with bt_error_release(), which,
450 in object-oriented programming terms,
451 corresponds to catching an exception and discarding it.
454 Error of which to move the ownership from you to the library.
456 @bt_pre_not_null{error}
458 The caller owns \bt_p{error}.
461 The library owns \bt_p{error}.
463 @sa bt_error_release() —
464 Releases (frees) an error.
465 @sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() —
466 Calls this function and assigns \c NULL to the expression.
469 void bt_current_thread_move_error(const bt_error
*error
);
473 Moves the ownership of the error \bt_p{_error} from the caller to
474 the library, and then sets \bt_p{_error} to \c NULL.
477 Error of which to move the ownership from you to the library.
479 @bt_pre_not_null{_error}
480 @bt_pre_assign_expr{_error}
482 The caller owns \bt_p{_error}.
485 The library owns \bt_p{_error}.
487 @sa bt_current_thread_move_error() —
488 Moves an error's ownership to the library.
490 #define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error) \
492 bt_current_thread_move_error(_error); \
498 Releases the current thread's error, if any.
500 This function is equivalent to:
503 bt_error_release(bt_current_thread_take_error());
507 The current thread has no error.
509 @sa bt_error_release() —
510 Releases (frees) an error.
511 @sa bt_current_thread_take_error —
512 Takes the current thread's error, moving its ownership from the
513 library to the caller.
516 void bt_current_thread_clear_error(void);
521 @name Error cause appending
528 <code>bt_current_thread_error_append_cause_from_*()</code>
531 typedef enum bt_current_thread_error_append_cause_status
{
536 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
542 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
543 } bt_current_thread_error_append_cause_status
;
547 Appends an error cause to the current thread's error from a
550 This this a <code>printf()</code>-like function starting from the
551 format string parameter \bt_p{message_format}.
553 On success, the appended error cause's module name
554 (see bt_error_cause_get_module_name()) is:
557 NAME: CC-TYPE.PLUGIN-NAME.CC-NAME
563 NAME: CC-TYPE.CC-NAME
566 if no \bt_plugin provides the class of \bt_p{self_component}, with:
570 <dd>Name of \bt_p{self_component}.</dd>
574 Type of the \ref api-comp-cls "class" of \bt_p{self_component}
575 (\c src, \c flt, or \c sink).
578 <dt>\c PLUGIN-NAME</dt>
580 Name of the plugin which provides the class of
581 \bt_p{self_component}.
585 <dd>Name of the class of \bt_p{self_component}.</dd>
588 @param[in] self_component
589 Self component of the appending method.
591 Name of the source file containing the method which appends the
593 @param[in] line_number
594 Line number of the statement which appends the error cause.
595 @param[in] message_format
596 Format string which specifies how the function converts the
597 subsequent arguments (like <code>printf()</code>).
599 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
601 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
604 @bt_pre_not_null{self_component}
605 @bt_pre_not_null{file_name}
606 @bt_pre_not_null{message_format}
607 @bt_pre_valid_fmt{message_format}
610 <strong>On success</strong>, the number of error causes in the
611 current thread's error is incremented.
613 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() —
614 Calls this function with \c __FILE__ and \c __LINE__ as the
615 \bt_p{file_name} and \bt_p{line_number} parameters.
617 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
618 bt_current_thread_error_append_cause_status
619 bt_current_thread_error_append_cause_from_component(
620 bt_self_component
*self_component
, const char *file_name
,
621 uint64_t line_number
, const char *message_format
, ...);
625 Appends an error cause to the current thread's error from a
626 \bt_comp method using \c __FILE__ and \c __LINE__ as the source
627 file name and line number.
629 This macro calls bt_current_thread_error_append_cause_from_component()
630 with \c __FILE__ and \c __LINE__ as its
631 \bt_p{file_name} and \bt_p{line_number} parameters.
633 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_component, _message_format, ...) \
634 bt_current_thread_error_append_cause_from_component( \
635 (_self_component), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
639 Appends an error cause to the current thread's error from a
642 This this a <code>printf()</code>-like function starting from the
643 format string parameter \bt_p{message_format}.
645 On success, the appended error cause's module name
646 (see bt_error_cause_get_module_name()) is:
649 COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME
655 COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME
658 if no \bt_plugin provides the component class of
659 \bt_p{self_message_iterator}, with:
662 <dt>\c COMP-NAME</dt>
663 <dd>Name of the \bt_comp of \bt_p{self_message_iterator}.</dd>
665 <dt>\c OUT-PORT-NAME</dt>
667 Name of the \bt_oport from which \bt_p{self_message_iterator}.
673 Type of the \bt_comp_cls of \bt_p{self_message_iterator}
674 (\c src, \c flt, or \c sink).
677 <dt>\c PLUGIN-NAME</dt>
679 Name of the plugin which provides the component class of
680 \bt_p{self_message_iterator}.
684 <dd>Name of the component class of \bt_p{self_message_iterator}.</dd>
687 @param[in] self_message_iterator
688 Self message iterator of the appending method.
690 Name of the source file containing the method which appends the
692 @param[in] line_number
693 Line number of the statement which appends the error cause.
694 @param[in] message_format
695 Format string which specifies how the function converts the
696 subsequent arguments (like <code>printf()</code>).
698 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
700 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
703 @bt_pre_not_null{self_message_iterator}
704 @bt_pre_not_null{file_name}
705 @bt_pre_not_null{message_format}
706 @bt_pre_valid_fmt{message_format}
709 <strong>On success</strong>, the number of error causes in the
710 current thread's error is incremented.
712 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() —
713 Calls this function with \c __FILE__ and \c __LINE__ as the
714 \bt_p{file_name} and \bt_p{line_number} parameters.
716 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
717 bt_current_thread_error_append_cause_status
718 bt_current_thread_error_append_cause_from_message_iterator(
719 bt_self_message_iterator
*self_message_iterator
,
720 const char *file_name
, uint64_t line_number
,
721 const char *message_format
, ...);
725 Appends an error cause to the current thread's error from a
726 \bt_msg_iter method using \c __FILE__ and \c __LINE__ as the source file
727 name and line number.
730 bt_current_thread_error_append_cause_from_message_iterator() with
731 \c __FILE__ and \c __LINE__ as its
732 \bt_p{file_name} and \bt_p{line_number} parameters.
734 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_message_iterator, _message_format, ...) \
735 bt_current_thread_error_append_cause_from_message_iterator( \
736 (_self_message_iterator), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
740 Appends an error cause to the current thread's error from a
743 This this a <code>printf()</code>-like function starting from the
744 format string parameter \bt_p{message_format}.
746 As of \bt_name_version_min_maj, the only component class method is the
747 \ref api-qexec "query" method.
749 On success, the appended error cause's module name
750 (see bt_error_cause_get_module_name()) is:
753 CC-TYPE.PLUGIN-NAME.CC-NAME
762 if no \bt_plugin provides \bt_p{self_component_class}, with:
767 Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink).
770 <dt>\c PLUGIN-NAME</dt>
772 Name of the plugin which provides \bt_p{self_component_class}.
776 <dd>Name of \bt_p{self_component_class}.</dd>
779 @param[in] self_component_class
780 Self component class of the appending method.
782 Name of the source file containing the method which appends the
784 @param[in] line_number
785 Line number of the statement which appends the error cause.
786 @param[in] message_format
787 Format string which specifies how the function converts the
788 subsequent arguments (like <code>printf()</code>).
790 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
792 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
795 @bt_pre_not_null{self_component_class}
796 @bt_pre_not_null{file_name}
797 @bt_pre_not_null{message_format}
798 @bt_pre_valid_fmt{message_format}
801 <strong>On success</strong>, the number of error causes in the
802 current thread's error is incremented.
804 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() —
805 Calls this function with \c __FILE__ and \c __LINE__ as the
806 \bt_p{file_name} and \bt_p{line_number} parameters.
808 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
809 bt_current_thread_error_append_cause_status
810 bt_current_thread_error_append_cause_from_component_class(
811 bt_self_component_class
*self_component_class
,
812 const char *file_name
, uint64_t line_number
,
813 const char *message_format
, ...);
817 Appends an error cause to the current thread's error from a
818 component class method using \c __FILE__ and \c __LINE__ as the
819 source file name and line number.
822 bt_current_thread_error_append_cause_from_component_class()
823 with \c __FILE__ and \c __LINE__ as its
824 \bt_p{file_name} and \bt_p{line_number} parameters.
826 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_component_class, _message_format, ...) \
827 bt_current_thread_error_append_cause_from_component_class( \
828 (_self_component_class), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
832 Appends an error cause to the current thread's error from any
835 Use this function when you cannot use
836 bt_current_thread_error_append_cause_from_component(),
837 bt_current_thread_error_append_cause_from_message_iterator(),
838 or bt_current_thread_error_append_cause_from_component_class().
840 This this a <code>printf()</code>-like function starting from the
841 format string parameter \bt_p{message_format}.
843 @param[in] module_name
844 Module name of the error cause to append.
846 Name of the source file containing the method which appends the
848 @param[in] line_number
849 Line number of the statement which appends the error cause.
850 @param[in] message_format
851 Format string which specifies how the function converts the
852 subsequent arguments (like <code>printf()</code>).
854 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
856 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
859 @bt_pre_not_null{module_name}
860 @bt_pre_not_null{file_name}
861 @bt_pre_not_null{message_format}
862 @bt_pre_valid_fmt{message_format}
865 <strong>On success</strong>, the number of error causes in the
866 current thread's error is incremented.
868 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() —
869 Calls this function with \c __FILE__ and \c __LINE__ as the
870 \bt_p{file_name} and \bt_p{line_number} parameters.
872 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
873 bt_current_thread_error_append_cause_status
874 bt_current_thread_error_append_cause_from_unknown(
875 const char *module_name
, const char *file_name
,
876 uint64_t line_number
, const char *message_format
, ...);
880 Appends an error cause to the current thread's error from any
881 function using \c __FILE__ and \c __LINE__ as the source
882 file name and line number.
884 Use this function when you cannot use
885 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(),
886 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(),
887 or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
889 This macro calls bt_current_thread_error_append_cause_from_unknown()
890 with \c __FILE__ and \c __LINE__ as its
891 \bt_p{file_name} and \bt_p{line_number} parameters.
893 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _message_format, ...) \
894 bt_current_thread_error_append_cause_from_unknown( \
895 (_module_name), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
906 Returns the number of error causes contained in the error
910 Error of which to get the number of contained error causes.
913 Number of contained error causes in \bt_p{error}.
915 @bt_pre_not_null{error}
918 uint64_t bt_error_get_cause_count(const bt_error
*error
);
922 Borrows the error cause at index \bt_p{index} from the
926 Error from which to borrow the error cause at index \bt_p{index}.
928 Index of the error cause to borrow from \bt_p{error}.
932 \em Borrowed reference of the error cause of
933 \bt_p{error} at index \bt_p{index}.
935 The returned pointer remains valid until \bt_p{error} is modified.
938 @bt_pre_not_null{error}
940 \bt_p{index} is less than the number of error causes in
941 \bt_p{error} (as returned by bt_error_get_cause_count()).
944 const bt_error_cause
*bt_error_borrow_cause_by_index(
945 const bt_error
*error
, uint64_t index
);
949 Releases (frees) the error \bt_p{error}.
951 After you call this function, \bt_p{error} does not exist.
953 Take the current thread's error with bt_current_thread_take_error().
955 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
956 terms, calling this function corresponds to catching an
957 exception and discarding it.
959 You can instead move the ownership of \bt_p{error} to the library with
960 bt_current_thread_move_error(), which,
961 in object-oriented programming terms,
962 corresponds to catching an exception and rethrowing it.
965 Error to release (free).
967 @bt_pre_not_null{error}
970 \bt_p{error} does not exist.
972 @sa bt_current_thread_move_error() —
973 Moves an error's ownership to the library.
976 void bt_error_release(const bt_error
*error
);
981 @name Error cause: common
987 Error cause actor type enumerators.
989 typedef enum bt_error_cause_actor_type
{
994 BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN
= 1 << 0,
1000 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT
= 1 << 1,
1004 Component class method.
1006 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS
= 1 << 2,
1010 Message iterator method.
1012 BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR
= 1 << 3,
1013 } bt_error_cause_actor_type
;
1017 Returns the actor type enumerator of the error cause
1020 @param[in] error_cause
1021 Error cause of which to get the actor type enumerator.
1024 Actor type enumerator of \bt_p{error_cause}.
1026 @bt_pre_not_null{error_cause}
1029 bt_error_cause_actor_type
bt_error_cause_get_actor_type(
1030 const bt_error_cause
*error_cause
);
1034 Returns the message of the error cause \bt_p{error_cause}.
1036 @param[in] error_cause
1037 Error cause of which to get the message.
1041 Message of \bt_p{error_cause}.
1043 The returned pointer remains valid as long as the error which
1044 contains \bt_p{error_cause} exists.
1047 @bt_pre_not_null{error_cause}
1050 const char *bt_error_cause_get_message(const bt_error_cause
*error_cause
);
1054 Returns the module name of the error cause \bt_p{error_cause}.
1056 @param[in] error_cause
1057 Error cause of which to get the module name.
1061 Module name of \bt_p{error_cause}.
1063 The returned pointer remains valid as long as the error which
1064 contains \bt_p{error_cause} exists.
1067 @bt_pre_not_null{error_cause}
1070 const char *bt_error_cause_get_module_name(const bt_error_cause
*error_cause
);
1074 Returns the name of the source file which contains the function
1075 which appended the error cause \bt_p{error_cause} to the
1076 current thread's error.
1078 @param[in] error_cause
1079 Error cause of which to get the source file name.
1083 Source file name of \bt_p{error_cause}.
1085 The returned pointer remains valid as long as the error which
1086 contains \bt_p{error_cause} exists.
1089 @bt_pre_not_null{error_cause}
1092 const char *bt_error_cause_get_file_name(const bt_error_cause
*error_cause
);
1096 Returns the line number of the statement
1097 which appended the error cause \bt_p{error_cause} to the
1098 current thread's error.
1100 @param[in] error_cause
1101 Error cause of which to get the source statement's line number.
1104 Source statement's line number of \bt_p{error_cause}.
1106 @bt_pre_not_null{error_cause}
1109 uint64_t bt_error_cause_get_line_number(const bt_error_cause
*error_cause
);
1114 @name Error cause with a component actor
1120 Returns the name of the \bt_comp of which a method
1121 appended the error cause \bt_p{error_cause} to the current
1124 @param[in] error_cause
1125 Error cause of which to get the component name.
1129 Component name of \bt_p{error_cause}.
1131 The returned pointer remains valid as long as the error which
1132 contains \bt_p{error_cause} exists.
1135 @bt_pre_not_null{error_cause}
1137 The actor type of \bt_p{error_cause} is
1138 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1141 const char *bt_error_cause_component_actor_get_component_name(
1142 const bt_error_cause
*error_cause
);
1146 Returns the \ref api-comp-cls "class" type of the
1147 \bt_comp of which a method appended the error cause
1148 \bt_p{error_cause} to the current thread's error.
1150 @param[in] error_cause
1151 Error cause of which to get the component class type.
1154 Component class type of \bt_p{error_cause}.
1156 @bt_pre_not_null{error_cause}
1158 The actor type of \bt_p{error_cause} is
1159 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1162 bt_component_class_type
bt_error_cause_component_actor_get_component_class_type(
1163 const bt_error_cause
*error_cause
);
1167 Returns the \ref api-comp-cls "class" name of the
1168 \bt_comp of which a method appended the error cause
1169 \bt_p{error_cause} to the current thread's error.
1171 @param[in] error_cause
1172 Error cause of which to get the component class name.
1176 Component class name of \bt_p{error_cause}.
1178 The returned pointer remains valid as long as the error which
1179 contains \bt_p{error_cause} exists.
1182 @bt_pre_not_null{error_cause}
1184 The actor type of \bt_p{error_cause} is
1185 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1188 const char *bt_error_cause_component_actor_get_component_class_name(
1189 const bt_error_cause
*error_cause
);
1193 Returns the name of the \bt_plugin which provides the
1194 \ref api-comp-cls "class" of the \bt_comp of which a method
1195 appended the error cause \bt_p{error_cause} to the
1196 current thread's error.
1198 This function returns \c NULL if no plugin provides the error cause's
1201 @param[in] error_cause
1202 Error cause of which to get the plugin name.
1206 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1207 provides the component class of \bt_p{error_cause}.
1209 The returned pointer remains valid as long as the error which
1210 contains \bt_p{error_cause} exists.
1213 @bt_pre_not_null{error_cause}
1215 The actor type of \bt_p{error_cause} is
1216 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1219 const char *bt_error_cause_component_actor_get_plugin_name(
1220 const bt_error_cause
*error_cause
);
1225 @name Error cause with a message iterator actor
1231 Returns the name of the \bt_oport from which was created
1232 the message iterator of which the method
1233 appended the error cause \bt_p{error_cause} to the current
1236 @param[in] error_cause
1237 Error cause of which to get the output port name.
1241 Output port name of \bt_p{error_cause}.
1243 The returned pointer remains valid as long as the error which
1244 contains \bt_p{error_cause} exists.
1247 @bt_pre_not_null{error_cause}
1249 The actor type of \bt_p{error_cause} is
1250 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1253 const char *bt_error_cause_message_iterator_actor_get_component_output_port_name(
1254 const bt_error_cause
*error_cause
);
1258 Returns the name of the \bt_comp of which a message iterator method
1259 appended the error cause \bt_p{error_cause} to the current
1262 @param[in] error_cause
1263 Error cause of which to get the component name.
1267 Component name of \bt_p{error_cause}.
1269 The returned pointer remains valid as long as the error which
1270 contains \bt_p{error_cause} exists.
1273 @bt_pre_not_null{error_cause}
1275 The actor type of \bt_p{error_cause} is
1276 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1279 const char *bt_error_cause_message_iterator_actor_get_component_name(
1280 const bt_error_cause
*error_cause
);
1284 Returns the \ref api-comp-cls "class" type of the
1285 \bt_comp of which a message iterator method appended the error cause
1286 \bt_p{error_cause} to the current thread's error.
1288 @param[in] error_cause
1289 Error cause of which to get the component class type.
1292 Component class type of \bt_p{error_cause}.
1294 @bt_pre_not_null{error_cause}
1296 The actor type of \bt_p{error_cause} is
1297 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1300 bt_component_class_type
1301 bt_error_cause_message_iterator_actor_get_component_class_type(
1302 const bt_error_cause
*error_cause
);
1306 Returns the \ref api-comp-cls "class" name of the
1307 \bt_comp of which a message iterator method appended the error cause
1308 \bt_p{error_cause} to the current thread's error.
1310 @param[in] error_cause
1311 Error cause of which to get the component class name.
1315 Component class name of \bt_p{error_cause}.
1317 The returned pointer remains valid as long as the error which
1318 contains \bt_p{error_cause} exists.
1321 @bt_pre_not_null{error_cause}
1323 The actor type of \bt_p{error_cause} is
1324 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1327 const char *bt_error_cause_message_iterator_actor_get_component_class_name(
1328 const bt_error_cause
*error_cause
);
1332 Returns the name of the \bt_plugin which provides the
1333 \ref api-comp-cls "class" of the \bt_comp of which a
1334 message iterator method
1335 appended the error cause \bt_p{error_cause} to the
1336 current thread's error.
1338 This function returns \c NULL if no plugin provides the error cause's
1341 @param[in] error_cause
1342 Error cause of which to get the plugin name.
1346 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1347 provides the component class of \bt_p{error_cause}.
1349 The returned pointer remains valid as long as the error which
1350 contains \bt_p{error_cause} exists.
1353 @bt_pre_not_null{error_cause}
1355 The actor type of \bt_p{error_cause} is
1356 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1359 const char *bt_error_cause_message_iterator_actor_get_plugin_name(
1360 const bt_error_cause
*error_cause
);
1365 @name Error cause with a component class actor
1371 Returns the name of the \bt_comp_cls
1372 of which a method appended the error cause
1373 \bt_p{error_cause} to the current thread's error.
1375 @param[in] error_cause
1376 Error cause of which to get the component class name.
1379 Component class name of \bt_p{error_cause}.
1381 @bt_pre_not_null{error_cause}
1383 The actor type of \bt_p{error_cause} is
1384 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1387 bt_component_class_type
1388 bt_error_cause_component_class_actor_get_component_class_type(
1389 const bt_error_cause
*error_cause
);
1393 Returns the name of the \bt_comp_cls
1394 of which a method appended the error cause
1395 \bt_p{error_cause} to the current thread's error.
1397 @param[in] error_cause
1398 Error cause of which to get the component class name.
1402 Component class name of \bt_p{error_cause}.
1404 The returned pointer remains valid as long as the error which
1405 contains \bt_p{error_cause} exists.
1408 @bt_pre_not_null{error_cause}
1410 The actor type of \bt_p{error_cause} is
1411 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1414 const char *bt_error_cause_component_class_actor_get_component_class_name(
1415 const bt_error_cause
*error_cause
);
1419 Returns the name of the \bt_plugin which provides the
1420 \bt_comp_cls of which a method
1421 appended the error cause \bt_p{error_cause} to the
1422 current thread's error.
1424 This function returns \c NULL if no plugin provides the error cause's
1427 @param[in] error_cause
1428 Error cause of which to get the plugin name.
1432 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1433 provides the component class of \bt_p{error_cause}.
1435 The returned pointer remains valid as long as the error which
1436 contains \bt_p{error_cause} exists.
1439 @bt_pre_not_null{error_cause}
1441 The actor type of \bt_p{error_cause} is
1442 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1445 const char *bt_error_cause_component_class_actor_get_plugin_name(
1446 const bt_error_cause
*error_cause
);
1456 #endif /* BABELTRACE2_ERROR_REPORTING_H */