2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_ERROR_REPORTING_H
8 #define BABELTRACE2_ERROR_REPORTING_H
10 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
17 #include <babeltrace2/graph/component-class.h>
24 @defgroup api-error Error reporting
27 Error reporting functions and macros.
29 This module contains functions and macros to report rich errors from a
30 user function (a \bt_comp_cls method, a
31 \ref api-qexec "query operation", or a trace processing \bt_graph
32 listener, for example) to any function caller.
34 Because \bt_name orchestrates pieces written by different authors,
35 it is important that an error which occurs deep into the function call
36 stack can percolate up to its callers.
38 The very basic mechanism to report an error from a function is to
39 \ref api-fund-func-status "return an error status"
40 (a status code enumerator which contains the word
41 \c ERROR): each function caller can clean its own context and return an
42 error status code itself until one caller "catches" the status code and
43 reacts to it. For example, the reaction can be to show an error message
46 This error reporting API adds a layer so that each function which
47 returns an error status code can append a message which describes the
48 cause of the error within the function's context.
50 Functions append error causes to the current thread's error. Having one
51 error object per thread makes this API thread-safe.
53 Here's a visual, step-by-step example:
55 @image html error-reporting-steps-1234.png
57 -# The trace processing \bt_graph user calls bt_graph_run().
59 -# bt_graph_run() calls the
60 \ref api-comp-cls-dev-meth-consume "consuming method" of the
63 -# The sink \bt_comp calls bt_message_iterator_next() on its upstream
66 -# bt_message_iterator_next() calls the source message iterator's
67 \link api-msg-iter-cls-meth-next "next" method\endlink.
69 @image html error-reporting-step-5.png
73 An error occurs within the "next" method of the source message
74 iterator: the function cannot read a file because permission was
78 @image html error-reporting-step-6.png
82 The source message iterator's "next" method appends the error
83 cause <em>"Cannot read file /some/file: permission denied"</em>
85 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR.
88 @image html error-reporting-step-7.png
92 bt_message_iterator_next() appends
93 the error cause <em>"Message iterator's 'next' method failed"</em>
94 with details about the source component and
95 returns #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR.
98 @image html error-reporting-steps-89.png
102 The sink component's "consume" method appends the error
103 cause <em>"Cannot consume upstream message iterator's messages"</em>
104 and returns #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR.
107 bt_graph_run() appends the error cause <em>"Component's 'consume'
108 method failed"</em> with details about the sink component and
109 returns #BT_GRAPH_RUN_STATUS_ERROR.
112 At this point, the current thread's error contains four causes:
114 - <em>"Cannot read file /some/file: permission denied"</em>
115 - <em>"Message iterator's 'next' method failed"</em>
116 - <em>"Cannot consume upstream message iterator's messages"</em>
117 - <em>"Component's 'consume' method failed"</em>
119 This list of error causes is much richer for the end user than dealing
120 only with #BT_GRAPH_RUN_STATUS_ERROR (the last error status code).
122 Both error (#bt_error) and error cause (#bt_error_cause) objects are
123 \ref api-fund-unique-object "unique objects":
125 - An error belongs to either
126 the library or you (see \ref api-error-handle "Handle an error").
128 - An error cause belongs to the error which contains it.
130 <h1>\anchor api-error-append-cause Append an error cause</h1>
132 When your function returns an error status code, use one of the
133 <code>bt_current_thread_error_append_cause_from_*()</code>
134 functions or <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code>
135 macros to append an error cause to the
136 current thread's error. Use the appropriate function or macro
137 depending on your function's actor amongst:
142 Append an error cause from a \bt_comp method.
144 Use bt_current_thread_error_append_cause_from_component() or
145 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT().
148 <dt>Message iterator</dt>
150 Append an error cause from a \bt_msg_iter method.
152 Use bt_current_thread_error_append_cause_from_message_iterator() or
153 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR().
156 <dt>Component class</dt>
158 Append an error cause from a \bt_comp_cls method
161 Use bt_current_thread_error_append_cause_from_component_class() or
162 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
167 Append an error cause from any other function, for example
168 a \bt_graph listener or a function of your user application).
170 Use bt_current_thread_error_append_cause_from_unknown() or
171 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN().
175 The <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code> macros
176 uses \c __FILE__ and \c __LINE__ as the file name and line number
177 parameters of their corresponding
178 <code>bt_current_thread_error_append_cause_from_*()</code> function.
180 <h1>\anchor api-error-handle Handle an error</h1>
182 If any libbabeltrace2 function you call returns an error status code, do
185 - Return an error status code too.
187 In that case, you \em can
188 \ref api-error-append-cause "append an error cause" to the current
191 - \em Take the current thread's error with
192 bt_current_thread_take_error().
194 This function moves the ownership of the error object from the library
197 At this point, you can inspect its causes with
198 bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and
201 - Call bt_error_release() to free the error object.
203 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
204 terms, this corresponds to catching an exception and discarding it.
206 - Call bt_current_thread_move_error() to move back the error object's
207 ownership to the library.
209 In object-oriented programming terms, this corresponds to catching
210 an exception and rethrowing it.
212 bt_current_thread_clear_error() is a helper which is the equivalent of:
215 bt_error_release(bt_current_thread_take_error());
220 All error causes have the type #bt_error_cause.
222 There are four types of error cause actors:
229 Get the type enumerator of an error cause's actor with
230 bt_error_cause_get_actor_type().
232 An error cause has the following common properties:
237 Description of the error cause.
239 Use bt_error_cause_get_message().
244 Name of the module causing the error.
246 For example, libbabeltrace2 uses "libbabeltrace2" and the \bt_cli
247 CLI tool uses "Babeltrace CLI".
249 Use bt_error_cause_get_module_name().
254 Name of the source file causing the error.
256 Use bt_error_cause_get_file_name().
261 Line number of the statement causing the error.
263 Use bt_error_cause_get_line_number().
267 <h2>Error cause with a component actor</h2>
269 An error cause with a \bt_comp actor has the following specific
273 <dt>Component name</dt>
275 Name of the component.
277 Use bt_error_cause_component_actor_get_component_name().
280 <dt>Component class name</dt>
282 Name of the component's \ref api-comp-cls "class".
284 Use bt_error_cause_component_actor_get_component_class_type().
287 <dt>Component class type</dt>
289 Type of the component's class.
291 Use bt_error_cause_component_actor_get_component_class_name().
294 <dt>\bt_dt_opt Plugin name</dt>
296 Name of the \bt_plugin which provides the component's class, if any.
298 Use bt_error_cause_component_actor_get_plugin_name().
302 <h2>Error cause with a message iterator actor</h2>
304 An error cause with a \bt_msg_iter actor has the following specific
308 <dt>Component output port name</dt>
310 Name of the \bt_comp \bt_oport from which the message iterator
313 Use bt_error_cause_component_actor_get_component_name().
316 <dt>Component name</dt>
318 Name of the component.
320 Use bt_error_cause_component_actor_get_component_name().
323 bt_error_cause_message_iterator_actor_get_component_output_port_name
325 <dt>Component class name</dt>
327 Name of the component's \ref api-comp-cls "class".
329 Use bt_error_cause_component_actor_get_component_class_type().
332 <dt>Component class type</dt>
334 Type of the component's class.
336 Use bt_error_cause_component_actor_get_component_class_name().
339 <dt>\bt_dt_opt Plugin name</dt>
341 Name of the \bt_plugin which provides the component's class, if any.
343 Use bt_error_cause_component_actor_get_plugin_name().
347 <h2>Error cause with a component class actor</h2>
349 An error cause with a \bt_comp_cls actor has the following specific
353 <dt>Component class name</dt>
355 Name of the component class.
357 Use bt_error_cause_component_class_actor_get_component_class_type().
360 <dt>Component class type</dt>
362 Type of the component class.
364 Use bt_error_cause_component_class_actor_get_component_class_name().
367 <dt>\bt_dt_opt Plugin name</dt>
369 Name of the \bt_plugin which provides the component class, if any.
371 Use bt_error_cause_component_class_actor_get_plugin_name().
382 @typedef struct bt_error bt_error;
387 @typedef struct bt_error_cause bt_error_cause;
396 @name Current thread's error
402 \em Takes the current thread's error, that is, moves its ownership
403 from the library to the caller.
405 This function can return \c NULL if the current thread has no error.
407 Once you are done with the returned error, do one of:
409 - Call bt_error_release() to free the error object.
411 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
412 terms, this corresponds to catching an exception and discarding it.
414 - Call bt_current_thread_move_error() to move back the error object's
415 ownership to the library.
417 In object-oriented programming terms, this corresponds to catching
418 an exception and rethrowing it.
421 Unique reference of the current thread's error, or \c NULL if the
422 current thread has no error.
425 <strong>If this function does not return <code>NULL</code></strong>,
426 the caller owns the returned error.
428 @sa bt_error_release() —
429 Releases (frees) an error.
430 @sa bt_current_thread_move_error() —
431 Moves an error's ownership to the library.
434 const bt_error
*bt_current_thread_take_error(void);
438 Moves the ownership of the error \bt_p{error} from the caller to
441 After you call this function, you don't own \bt_p{error} anymore.
443 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
444 terms, calling this function corresponds to catching an
445 exception and rethrowing it.
447 You can instead release (free) the error with bt_error_release(), which,
448 in object-oriented programming terms,
449 corresponds to catching an exception and discarding it.
452 Error of which to move the ownership from you to the library.
454 @bt_pre_not_null{error}
456 The caller owns \bt_p{error}.
459 The library owns \bt_p{error}.
461 @sa bt_error_release() —
462 Releases (frees) an error.
463 @sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() —
464 Calls this function and assigns \c NULL to the expression.
467 void bt_current_thread_move_error(const bt_error
*error
);
471 Moves the ownership of the error \bt_p{_error} from the caller to
472 the library, and then sets \bt_p{_error} to \c NULL.
475 Error of which to move the ownership from you to the library.
477 @bt_pre_not_null{_error}
478 @bt_pre_assign_expr{_error}
480 The caller owns \bt_p{_error}.
483 The library owns \bt_p{_error}.
485 @sa bt_current_thread_move_error() —
486 Moves an error's ownership to the library.
488 #define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error) \
490 bt_current_thread_move_error(_error); \
496 Releases the current thread's error, if any.
498 This function is equivalent to:
501 bt_error_release(bt_current_thread_take_error());
505 The current thread has no error.
507 @sa bt_error_release() —
508 Releases (frees) an error.
509 @sa bt_current_thread_take_error —
510 Takes the current thread's error, moving its ownership from the
511 library to the caller.
514 void bt_current_thread_clear_error(void);
519 @name Error cause appending
526 <code>bt_current_thread_error_append_cause_from_*()</code>
529 typedef enum bt_current_thread_error_append_cause_status
{
534 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
540 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
541 } bt_current_thread_error_append_cause_status
;
545 Appends an error cause to the current thread's error from a
548 This this a <code>printf()</code>-like function starting from the
549 format string parameter \bt_p{message_format}.
551 On success, the appended error cause's module name
552 (see bt_error_cause_get_module_name()) is:
555 NAME: CC-TYPE.PLUGIN-NAME.CC-NAME
561 NAME: CC-TYPE.CC-NAME
564 if no \bt_plugin provides the class of \bt_p{self_component}, with:
568 <dd>Name of \bt_p{self_component}.</dd>
572 Type of the \ref api-comp-cls "class" of \bt_p{self_component}
573 (\c src, \c flt, or \c sink).
576 <dt>\c PLUGIN-NAME</dt>
578 Name of the plugin which provides the class of
579 \bt_p{self_component}.
583 <dd>Name of the class of \bt_p{self_component}.</dd>
586 @param[in] self_component
587 Self component of the appending method.
589 Name of the source file containing the method which appends the
591 @param[in] line_number
592 Line number of the statement which appends the error cause.
593 @param[in] message_format
594 Format string which specifies how the function converts the
595 subsequent arguments (like <code>printf()</code>).
597 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
599 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
602 @bt_pre_not_null{self_component}
603 @bt_pre_not_null{file_name}
604 @bt_pre_not_null{message_format}
605 @bt_pre_valid_fmt{message_format}
608 <strong>On success</strong>, the number of error causes in the
609 current thread's error is incremented.
611 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() —
612 Calls this function with \c __FILE__ and \c __LINE__ as the
613 \bt_p{file_name} and \bt_p{line_number} parameters.
615 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
616 bt_current_thread_error_append_cause_status
617 bt_current_thread_error_append_cause_from_component(
618 bt_self_component
*self_component
, const char *file_name
,
619 uint64_t line_number
, const char *message_format
, ...);
623 Appends an error cause to the current thread's error from a
624 \bt_comp method using \c __FILE__ and \c __LINE__ as the source
625 file name and line number.
627 This macro calls bt_current_thread_error_append_cause_from_component()
628 with \c __FILE__ and \c __LINE__ as its
629 \bt_p{file_name} and \bt_p{line_number} parameters.
631 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_component, _message_format, ...) \
632 bt_current_thread_error_append_cause_from_component( \
633 (_self_component), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
637 Appends an error cause to the current thread's error from a
640 This this a <code>printf()</code>-like function starting from the
641 format string parameter \bt_p{message_format}.
643 On success, the appended error cause's module name
644 (see bt_error_cause_get_module_name()) is:
647 COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME
653 COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME
656 if no \bt_plugin provides the component class of
657 \bt_p{self_message_iterator}, with:
660 <dt>\c COMP-NAME</dt>
661 <dd>Name of the \bt_comp of \bt_p{self_message_iterator}.</dd>
663 <dt>\c OUT-PORT-NAME</dt>
665 Name of the \bt_oport from which \bt_p{self_message_iterator}.
671 Type of the \bt_comp_cls of \bt_p{self_message_iterator}
672 (\c src, \c flt, or \c sink).
675 <dt>\c PLUGIN-NAME</dt>
677 Name of the plugin which provides the component class of
678 \bt_p{self_message_iterator}.
682 <dd>Name of the component class of \bt_p{self_message_iterator}.</dd>
685 @param[in] self_message_iterator
686 Self message iterator of the appending method.
688 Name of the source file containing the method which appends the
690 @param[in] line_number
691 Line number of the statement which appends the error cause.
692 @param[in] message_format
693 Format string which specifies how the function converts the
694 subsequent arguments (like <code>printf()</code>).
696 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
698 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
701 @bt_pre_not_null{self_message_iterator}
702 @bt_pre_not_null{file_name}
703 @bt_pre_not_null{message_format}
704 @bt_pre_valid_fmt{message_format}
707 <strong>On success</strong>, the number of error causes in the
708 current thread's error is incremented.
710 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() —
711 Calls this function with \c __FILE__ and \c __LINE__ as the
712 \bt_p{file_name} and \bt_p{line_number} parameters.
714 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
715 bt_current_thread_error_append_cause_status
716 bt_current_thread_error_append_cause_from_message_iterator(
717 bt_self_message_iterator
*self_message_iterator
,
718 const char *file_name
, uint64_t line_number
,
719 const char *message_format
, ...);
723 Appends an error cause to the current thread's error from a
724 \bt_msg_iter method using \c __FILE__ and \c __LINE__ as the source file
725 name and line number.
728 bt_current_thread_error_append_cause_from_message_iterator() with
729 \c __FILE__ and \c __LINE__ as its
730 \bt_p{file_name} and \bt_p{line_number} parameters.
732 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_message_iterator, _message_format, ...) \
733 bt_current_thread_error_append_cause_from_message_iterator( \
734 (_self_message_iterator), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
738 Appends an error cause to the current thread's error from a
741 This this a <code>printf()</code>-like function starting from the
742 format string parameter \bt_p{message_format}.
744 As of \bt_name_version_min_maj, the only component class method is the
745 \ref api-qexec "query" method.
747 On success, the appended error cause's module name
748 (see bt_error_cause_get_module_name()) is:
751 CC-TYPE.PLUGIN-NAME.CC-NAME
760 if no \bt_plugin provides \bt_p{self_component_class}, with:
765 Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink).
768 <dt>\c PLUGIN-NAME</dt>
770 Name of the plugin which provides \bt_p{self_component_class}.
774 <dd>Name of \bt_p{self_component_class}.</dd>
777 @param[in] self_component_class
778 Self component class of the appending method.
780 Name of the source file containing the method which appends the
782 @param[in] line_number
783 Line number of the statement which appends the error cause.
784 @param[in] message_format
785 Format string which specifies how the function converts the
786 subsequent arguments (like <code>printf()</code>).
788 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
790 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
793 @bt_pre_not_null{self_component_class}
794 @bt_pre_not_null{file_name}
795 @bt_pre_not_null{message_format}
796 @bt_pre_valid_fmt{message_format}
799 <strong>On success</strong>, the number of error causes in the
800 current thread's error is incremented.
802 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() —
803 Calls this function with \c __FILE__ and \c __LINE__ as the
804 \bt_p{file_name} and \bt_p{line_number} parameters.
806 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
807 bt_current_thread_error_append_cause_status
808 bt_current_thread_error_append_cause_from_component_class(
809 bt_self_component_class
*self_component_class
,
810 const char *file_name
, uint64_t line_number
,
811 const char *message_format
, ...);
815 Appends an error cause to the current thread's error from a
816 component class method using \c __FILE__ and \c __LINE__ as the
817 source file name and line number.
820 bt_current_thread_error_append_cause_from_component_class()
821 with \c __FILE__ and \c __LINE__ as its
822 \bt_p{file_name} and \bt_p{line_number} parameters.
824 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_component_class, _message_format, ...) \
825 bt_current_thread_error_append_cause_from_component_class( \
826 (_self_component_class), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
830 Appends an error cause to the current thread's error from any
833 Use this function when you cannot use
834 bt_current_thread_error_append_cause_from_component(),
835 bt_current_thread_error_append_cause_from_message_iterator(),
836 or bt_current_thread_error_append_cause_from_component_class().
838 This this a <code>printf()</code>-like function starting from the
839 format string parameter \bt_p{message_format}.
841 @param[in] module_name
842 Module name of the error cause to append.
844 Name of the source file containing the method which appends the
846 @param[in] line_number
847 Line number of the statement which appends the error cause.
848 @param[in] message_format
849 Format string which specifies how the function converts the
850 subsequent arguments (like <code>printf()</code>).
852 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
854 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
857 @bt_pre_not_null{module_name}
858 @bt_pre_not_null{file_name}
859 @bt_pre_not_null{message_format}
860 @bt_pre_valid_fmt{message_format}
863 <strong>On success</strong>, the number of error causes in the
864 current thread's error is incremented.
866 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() —
867 Calls this function with \c __FILE__ and \c __LINE__ as the
868 \bt_p{file_name} and \bt_p{line_number} parameters.
870 extern __BT_ATTR_FORMAT_PRINTF(4, 5)
871 bt_current_thread_error_append_cause_status
872 bt_current_thread_error_append_cause_from_unknown(
873 const char *module_name
, const char *file_name
,
874 uint64_t line_number
, const char *message_format
, ...);
878 Appends an error cause to the current thread's error from any
879 function using \c __FILE__ and \c __LINE__ as the source
880 file name and line number.
882 Use this function when you cannot use
883 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(),
884 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(),
885 or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
887 This macro calls bt_current_thread_error_append_cause_from_unknown()
888 with \c __FILE__ and \c __LINE__ as its
889 \bt_p{file_name} and \bt_p{line_number} parameters.
891 #define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _message_format, ...) \
892 bt_current_thread_error_append_cause_from_unknown( \
893 (_module_name), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
904 Returns the number of error causes contained in the error
908 Error of which to get the number of contained error causes.
911 Number of contained error causes in \bt_p{error}.
913 @bt_pre_not_null{error}
916 uint64_t bt_error_get_cause_count(const bt_error
*error
);
920 Borrows the error cause at index \bt_p{index} from the
924 Error from which to borrow the error cause at index \bt_p{index}.
926 Index of the error cause to borrow from \bt_p{error}.
930 \em Borrowed reference of the error cause of
931 \bt_p{error} at index \bt_p{index}.
933 The returned pointer remains valid until \bt_p{error} is modified.
936 @bt_pre_not_null{error}
938 \bt_p{index} is less than the number of error causes in
939 \bt_p{error} (as returned by bt_error_get_cause_count()).
942 const bt_error_cause
*bt_error_borrow_cause_by_index(
943 const bt_error
*error
, uint64_t index
);
947 Releases (frees) the error \bt_p{error}.
949 After you call this function, \bt_p{error} does not exist.
951 Take the current thread's error with bt_current_thread_take_error().
953 In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
954 terms, calling this function corresponds to catching an
955 exception and discarding it.
957 You can instead move the ownership of \bt_p{error} to the library with
958 bt_current_thread_move_error(), which,
959 in object-oriented programming terms,
960 corresponds to catching an exception and rethrowing it.
963 Error to release (free).
965 @bt_pre_not_null{error}
968 \bt_p{error} does not exist.
970 @sa bt_current_thread_move_error() —
971 Moves an error's ownership to the library.
974 void bt_error_release(const bt_error
*error
);
979 @name Error cause: common
985 Error cause actor type enumerators.
987 typedef enum bt_error_cause_actor_type
{
992 BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN
= 1 << 0,
998 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT
= 1 << 1,
1002 Component class method.
1004 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS
= 1 << 2,
1008 Message iterator method.
1010 BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR
= 1 << 3,
1011 } bt_error_cause_actor_type
;
1015 Returns the actor type enumerator of the error cause
1018 @param[in] error_cause
1019 Error cause of which to get the actor type enumerator.
1022 Actor type enumerator of \bt_p{error_cause}.
1024 @bt_pre_not_null{error_cause}
1027 bt_error_cause_actor_type
bt_error_cause_get_actor_type(
1028 const bt_error_cause
*error_cause
);
1032 Returns the message of the error cause \bt_p{error_cause}.
1034 @param[in] error_cause
1035 Error cause of which to get the message.
1039 Message of \bt_p{error_cause}.
1041 The returned pointer remains valid as long as the error which
1042 contains \bt_p{error_cause} exists.
1045 @bt_pre_not_null{error_cause}
1048 const char *bt_error_cause_get_message(const bt_error_cause
*error_cause
);
1052 Returns the module name of the error cause \bt_p{error_cause}.
1054 @param[in] error_cause
1055 Error cause of which to get the module name.
1059 Module name of \bt_p{error_cause}.
1061 The returned pointer remains valid as long as the error which
1062 contains \bt_p{error_cause} exists.
1065 @bt_pre_not_null{error_cause}
1068 const char *bt_error_cause_get_module_name(const bt_error_cause
*error_cause
);
1072 Returns the name of the source file which contains the function
1073 which appended the error cause \bt_p{error_cause} to the
1074 current thread's error.
1076 @param[in] error_cause
1077 Error cause of which to get the source file name.
1081 Source file name of \bt_p{error_cause}.
1083 The returned pointer remains valid as long as the error which
1084 contains \bt_p{error_cause} exists.
1087 @bt_pre_not_null{error_cause}
1090 const char *bt_error_cause_get_file_name(const bt_error_cause
*error_cause
);
1094 Returns the line number of the statement
1095 which appended the error cause \bt_p{error_cause} to the
1096 current thread's error.
1098 @param[in] error_cause
1099 Error cause of which to get the source statement's line number.
1102 Source statement's line number of \bt_p{error_cause}.
1104 @bt_pre_not_null{error_cause}
1107 uint64_t bt_error_cause_get_line_number(const bt_error_cause
*error_cause
);
1112 @name Error cause with a component actor
1118 Returns the name of the \bt_comp of which a method
1119 appended the error cause \bt_p{error_cause} to the current
1122 @param[in] error_cause
1123 Error cause of which to get the component name.
1127 Component name of \bt_p{error_cause}.
1129 The returned pointer remains valid as long as the error which
1130 contains \bt_p{error_cause} exists.
1133 @bt_pre_not_null{error_cause}
1135 The actor type of \bt_p{error_cause} is
1136 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1139 const char *bt_error_cause_component_actor_get_component_name(
1140 const bt_error_cause
*error_cause
);
1144 Returns the \ref api-comp-cls "class" type of the
1145 \bt_comp of which a method appended the error cause
1146 \bt_p{error_cause} to the current thread's error.
1148 @param[in] error_cause
1149 Error cause of which to get the component class type.
1152 Component class type of \bt_p{error_cause}.
1154 @bt_pre_not_null{error_cause}
1156 The actor type of \bt_p{error_cause} is
1157 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1160 bt_component_class_type
bt_error_cause_component_actor_get_component_class_type(
1161 const bt_error_cause
*error_cause
);
1165 Returns the \ref api-comp-cls "class" name of the
1166 \bt_comp of which a method appended the error cause
1167 \bt_p{error_cause} to the current thread's error.
1169 @param[in] error_cause
1170 Error cause of which to get the component class name.
1174 Component class name of \bt_p{error_cause}.
1176 The returned pointer remains valid as long as the error which
1177 contains \bt_p{error_cause} exists.
1180 @bt_pre_not_null{error_cause}
1182 The actor type of \bt_p{error_cause} is
1183 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1186 const char *bt_error_cause_component_actor_get_component_class_name(
1187 const bt_error_cause
*error_cause
);
1191 Returns the name of the \bt_plugin which provides the
1192 \ref api-comp-cls "class" of the \bt_comp of which a method
1193 appended the error cause \bt_p{error_cause} to the
1194 current thread's error.
1196 This function returns \c NULL if no plugin provides the error cause's
1199 @param[in] error_cause
1200 Error cause of which to get the plugin name.
1204 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1205 provides the component class of \bt_p{error_cause}.
1207 The returned pointer remains valid as long as the error which
1208 contains \bt_p{error_cause} exists.
1211 @bt_pre_not_null{error_cause}
1213 The actor type of \bt_p{error_cause} is
1214 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1217 const char *bt_error_cause_component_actor_get_plugin_name(
1218 const bt_error_cause
*error_cause
);
1223 @name Error cause with a message iterator actor
1229 Returns the name of the \bt_oport from which was created
1230 the message iterator of which the method
1231 appended the error cause \bt_p{error_cause} to the current
1234 @param[in] error_cause
1235 Error cause of which to get the output port name.
1239 Output port name of \bt_p{error_cause}.
1241 The returned pointer remains valid as long as the error which
1242 contains \bt_p{error_cause} exists.
1245 @bt_pre_not_null{error_cause}
1247 The actor type of \bt_p{error_cause} is
1248 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1251 const char *bt_error_cause_message_iterator_actor_get_component_output_port_name(
1252 const bt_error_cause
*error_cause
);
1256 Returns the name of the \bt_comp of which a message iterator method
1257 appended the error cause \bt_p{error_cause} to the current
1260 @param[in] error_cause
1261 Error cause of which to get the component name.
1265 Component name of \bt_p{error_cause}.
1267 The returned pointer remains valid as long as the error which
1268 contains \bt_p{error_cause} exists.
1271 @bt_pre_not_null{error_cause}
1273 The actor type of \bt_p{error_cause} is
1274 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1277 const char *bt_error_cause_message_iterator_actor_get_component_name(
1278 const bt_error_cause
*error_cause
);
1282 Returns the \ref api-comp-cls "class" type of the
1283 \bt_comp of which a message iterator method appended the error cause
1284 \bt_p{error_cause} to the current thread's error.
1286 @param[in] error_cause
1287 Error cause of which to get the component class type.
1290 Component class type of \bt_p{error_cause}.
1292 @bt_pre_not_null{error_cause}
1294 The actor type of \bt_p{error_cause} is
1295 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1298 bt_component_class_type
1299 bt_error_cause_message_iterator_actor_get_component_class_type(
1300 const bt_error_cause
*error_cause
);
1304 Returns the \ref api-comp-cls "class" name of the
1305 \bt_comp of which a message iterator method appended the error cause
1306 \bt_p{error_cause} to the current thread's error.
1308 @param[in] error_cause
1309 Error cause of which to get the component class name.
1313 Component class name of \bt_p{error_cause}.
1315 The returned pointer remains valid as long as the error which
1316 contains \bt_p{error_cause} exists.
1319 @bt_pre_not_null{error_cause}
1321 The actor type of \bt_p{error_cause} is
1322 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1325 const char *bt_error_cause_message_iterator_actor_get_component_class_name(
1326 const bt_error_cause
*error_cause
);
1330 Returns the name of the \bt_plugin which provides the
1331 \ref api-comp-cls "class" of the \bt_comp of which a
1332 message iterator method
1333 appended the error cause \bt_p{error_cause} to the
1334 current thread's error.
1336 This function returns \c NULL if no plugin provides the error cause's
1339 @param[in] error_cause
1340 Error cause of which to get the plugin name.
1344 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1345 provides the component class of \bt_p{error_cause}.
1347 The returned pointer remains valid as long as the error which
1348 contains \bt_p{error_cause} exists.
1351 @bt_pre_not_null{error_cause}
1353 The actor type of \bt_p{error_cause} is
1354 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1357 const char *bt_error_cause_message_iterator_actor_get_plugin_name(
1358 const bt_error_cause
*error_cause
);
1363 @name Error cause with a component class actor
1369 Returns the name of the \bt_comp_cls
1370 of which a method appended the error cause
1371 \bt_p{error_cause} to the current thread's error.
1373 @param[in] error_cause
1374 Error cause of which to get the component class name.
1377 Component class name of \bt_p{error_cause}.
1379 @bt_pre_not_null{error_cause}
1381 The actor type of \bt_p{error_cause} is
1382 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1385 bt_component_class_type
1386 bt_error_cause_component_class_actor_get_component_class_type(
1387 const bt_error_cause
*error_cause
);
1391 Returns the name of the \bt_comp_cls
1392 of which a method appended the error cause
1393 \bt_p{error_cause} to the current thread's error.
1395 @param[in] error_cause
1396 Error cause of which to get the component class name.
1400 Component class name of \bt_p{error_cause}.
1402 The returned pointer remains valid as long as the error which
1403 contains \bt_p{error_cause} exists.
1406 @bt_pre_not_null{error_cause}
1408 The actor type of \bt_p{error_cause} is
1409 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1412 const char *bt_error_cause_component_class_actor_get_component_class_name(
1413 const bt_error_cause
*error_cause
);
1417 Returns the name of the \bt_plugin which provides the
1418 \bt_comp_cls of which a method
1419 appended the error cause \bt_p{error_cause} to the
1420 current thread's error.
1422 This function returns \c NULL if no plugin provides the error cause's
1425 @param[in] error_cause
1426 Error cause of which to get the plugin name.
1430 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1431 provides the component class of \bt_p{error_cause}.
1433 The returned pointer remains valid as long as the error which
1434 contains \bt_p{error_cause} exists.
1437 @bt_pre_not_null{error_cause}
1439 The actor type of \bt_p{error_cause} is
1440 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1443 const char *bt_error_cause_component_class_actor_get_plugin_name(
1444 const bt_error_cause
*error_cause
);
1454 #endif /* BABELTRACE2_ERROR_REPORTING_H */