1 #ifndef BABELTRACE2_ERROR_REPORTING_H
2 #define BABELTRACE2_ERROR_REPORTING_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
33 #include <babeltrace2/graph/component-class.h>
40 @defgroup api-error Error reporting
43 Error reporting functions and macros.
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.
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.
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
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.
66 Functions append error causes to the current thread's error. Having one
67 error object per thread makes this API thread-safe.
69 Here's a visual, step-by-step example:
71 @image html error-reporting-steps-1234.png
73 -# The trace processing \bt_graph user calls bt_graph_run().
75 -# bt_graph_run() calls the
76 \ref api-comp-cls-dev-meth-consume "consuming method" of the
79 -# The sink \bt_comp calls bt_message_iterator_next() on its upstream
82 -# bt_message_iterator_next() calls the source message iterator's
83 \link api-msg-iter-cls-meth-next "next" method\endlink.
85 @image html error-reporting-step-5.png
89 An error occurs within the "next" method of the source message
90 iterator: the function cannot read a file because permission was
94 @image html error-reporting-step-6.png
98 The source message iterator's "next" method appends the error
99 cause <em>"Cannot read file /some/file: permission denied"</em>
101 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR.
104 @image html error-reporting-step-7.png
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.
114 @image html error-reporting-steps-89.png
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.
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.
128 At this point, the current thread's error contains four causes:
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>
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).
138 Both error (#bt_error) and error cause (#bt_error_cause) objects are
139 \ref api-fund-unique-object "unique objects":
141 - An error belongs to either
142 the library or you (see \ref api-error-handle "Handle an error").
144 - An error cause belongs to the error which contains it.
146 <h1>\anchor api-error-append-cause Append an error cause</h1>
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:
158 Append an error cause from a \bt_comp method.
160 Use bt_current_thread_error_append_cause_from_component() or
161 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT().
164 <dt>Message iterator</dt>
166 Append an error cause from a \bt_msg_iter method.
168 Use bt_current_thread_error_append_cause_from_message_iterator() or
169 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR().
172 <dt>Component class</dt>
174 Append an error cause from a \bt_comp_cls method
177 Use bt_current_thread_error_append_cause_from_component_class() or
178 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
183 Append an error cause from any other function, for example
184 a \bt_graph listener or a function of your user application).
186 Use bt_current_thread_error_append_cause_from_unknown() or
187 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN().
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.
196 <h1>\anchor api-error-handle Handle an error</h1>
198 If any libbabeltrace2 function you call returns an error status code, do
201 - Return an error status code too.
203 In that case, you \em can
204 \ref api-error-append-cause "append an error cause" to the current
207 - \em Take the current thread's error with
208 bt_current_thread_take_error().
210 This function moves the ownership of the error object from the library
213 At this point, you can inspect its causes with
214 bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and
217 - Call bt_error_release() to free the error object.
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.
222 - Call bt_current_thread_move_error() to move back the error object's
223 ownership to the library.
225 In object-oriented programming terms, this corresponds to catching
226 an exception and rethrowing it.
228 bt_current_thread_clear_error() is a helper which is the equivalent of:
231 bt_error_release(bt_current_thread_take_error());
236 All error causes have the type #bt_error_cause.
238 There are four types of error cause actors:
245 Get the type enumerator of an error cause's actor with
246 bt_error_cause_get_actor_type().
248 An error cause has the following common properties:
253 Description of the error cause.
255 Use bt_error_cause_get_message().
260 Name of the module causing the error.
262 For example, libbabeltrace2 uses "libbabeltrace2" and the \bt_cli
263 CLI tool uses "Babeltrace CLI".
265 Use bt_error_cause_get_module_name().
270 Name of the source file causing the error.
272 Use bt_error_cause_get_file_name().
277 Line number of the statement causing the error.
279 Use bt_error_cause_get_line_number().
283 <h2>Error cause with a component actor</h2>
285 An error cause with a \bt_comp actor has the following specific
289 <dt>Component name</dt>
291 Name of the component.
293 Use bt_error_cause_component_actor_get_component_name().
296 <dt>Component class name</dt>
298 Name of the component's \ref api-comp-cls "class".
300 Use bt_error_cause_component_actor_get_component_class_type().
303 <dt>Component class type</dt>
305 Type of the component's class.
307 Use bt_error_cause_component_actor_get_component_class_name().
310 <dt>\bt_dt_opt Plugin name</dt>
312 Name of the \bt_plugin which provides the component's class, if any.
314 Use bt_error_cause_component_actor_get_plugin_name().
318 <h2>Error cause with a message iterator actor</h2>
320 An error cause with a \bt_msg_iter actor has the following specific
324 <dt>Component output port name</dt>
326 Name of the \bt_comp \bt_oport from which the message iterator
329 Use bt_error_cause_component_actor_get_component_name().
332 <dt>Component name</dt>
334 Name of the component.
336 Use bt_error_cause_component_actor_get_component_name().
339 bt_error_cause_message_iterator_actor_get_component_output_port_name
341 <dt>Component class name</dt>
343 Name of the component's \ref api-comp-cls "class".
345 Use bt_error_cause_component_actor_get_component_class_type().
348 <dt>Component class type</dt>
350 Type of the component's class.
352 Use bt_error_cause_component_actor_get_component_class_name().
355 <dt>\bt_dt_opt Plugin name</dt>
357 Name of the \bt_plugin which provides the component's class, if any.
359 Use bt_error_cause_component_actor_get_plugin_name().
363 <h2>Error cause with a component class actor</h2>
365 An error cause with a \bt_comp_cls actor has the following specific
369 <dt>Component class name</dt>
371 Name of the component class.
373 Use bt_error_cause_component_class_actor_get_component_class_type().
376 <dt>Component class type</dt>
378 Type of the component class.
380 Use bt_error_cause_component_class_actor_get_component_class_name().
383 <dt>\bt_dt_opt Plugin name</dt>
385 Name of the \bt_plugin which provides the component class, if any.
387 Use bt_error_cause_component_class_actor_get_plugin_name().
398 @typedef struct bt_error bt_error;
404 @typedef struct bt_error_cause bt_error_cause;
413 @name Current thread's error
419 \em Takes the current thread's error, that is, moves its ownership
420 from the library to the caller.
422 This function can return \c NULL if the current thread has no error.
424 Once you are done with the returned error, do one of:
426 - Call bt_error_release() to free the error object.
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.
431 - Call bt_current_thread_move_error() to move back the error object's
432 ownership to the library.
434 In object-oriented programming terms, this corresponds to catching
435 an exception and rethrowing it.
438 Unique reference of the current thread's error, or \c NULL if the
439 current thread has no error.
442 <strong>If this function does not return <code>NULL</code></strong>,
443 the caller owns the returned error.
445 @sa bt_error_release() —
446 Releases (frees) an error.
447 @sa bt_current_thread_move_error() —
448 Moves an error's ownership to the library.
451 const bt_error
*bt_current_thread_take_error(void);
455 Moves the ownership of the error \bt_p{error} from the caller to
458 After you call this function, you don't own \bt_p{error} anymore.
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.
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.
469 Error of which to move the ownership from you to the library.
471 @bt_pre_not_null{error}
473 The caller owns \bt_p{error}.
476 The library owns \bt_p{error}.
478 @sa bt_error_release() —
479 Releases (frees) an error.
480 @sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() —
481 Calls this function and assigns \c NULL to the expression.
484 void bt_current_thread_move_error(const bt_error
*error
);
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.
492 Error of which to move the ownership from you to the library.
494 @bt_pre_not_null{_error}
495 @bt_pre_assign_expr{_error}
497 The caller owns \bt_p{_error}.
500 The library owns \bt_p{_error}.
502 @sa bt_current_thread_move_error() —
503 Moves an error's ownership to the library.
505 #define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error) \
507 bt_current_thread_move_error(_error); \
513 Releases the current thread's error, if any.
515 This function is equivalent to:
518 bt_error_release(bt_current_thread_take_error());
522 The current thread has no error.
524 @sa bt_error_release() —
525 Releases (frees) an error.
526 @sa bt_current_thread_take_error —
527 Takes the current thread's error, moving its ownership from the
528 library to the caller.
531 void bt_current_thread_clear_error(void);
536 @name Error cause appending
543 <code>bt_current_thread_error_append_cause_from_*()</code>
546 typedef enum bt_current_thread_error_append_cause_status
{
551 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
557 BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
558 } bt_current_thread_error_append_cause_status
;
562 Appends an error cause to the current thread's error from a
565 This this a <code>printf()</code>-like function starting from the
566 format string parameter \bt_p{message_format}.
568 On success, the appended error cause's module name
569 (see bt_error_cause_get_module_name()) is:
572 NAME: CC-TYPE.PLUGIN-NAME.CC-NAME
578 NAME: CC-TYPE.CC-NAME
581 if no \bt_plugin provides the class of \bt_p{self_component}, with:
585 <dd>Name of \bt_p{self_component}.</dd>
589 Type of the \ref api-comp-cls "class" of \bt_p{self_component}
590 (\c src, \c flt, or \c sink).
593 <dt>\c PLUGIN-NAME</dt>
595 Name of the plugin which provides the class of
596 \bt_p{self_component}.
600 <dd>Name of the class of \bt_p{self_component}.</dd>
603 @param[in] self_component
604 Self component of the appending method.
606 Name of the source file containing the method which appends the
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>).
614 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
616 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
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}
625 <strong>On success</strong>, the number of error causes in the
626 current thread's error is incremented.
628 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() —
629 Calls this function with \c __FILE__ and \c __LINE__ as the
630 \bt_p{file_name} and \bt_p{line_number} parameters.
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
, ...);
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.
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.
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__)
654 Appends an error cause to the current thread's error from a
657 This this a <code>printf()</code>-like function starting from the
658 format string parameter \bt_p{message_format}.
660 On success, the appended error cause's module name
661 (see bt_error_cause_get_module_name()) is:
664 COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME
670 COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME
673 if no \bt_plugin provides the component class of
674 \bt_p{self_message_iterator}, with:
677 <dt>\c COMP-NAME</dt>
678 <dd>Name of the \bt_comp of \bt_p{self_message_iterator}.</dd>
680 <dt>\c OUT-PORT-NAME</dt>
682 Name of the \bt_oport from which \bt_p{self_message_iterator}.
688 Type of the \bt_comp_cls of \bt_p{self_message_iterator}
689 (\c src, \c flt, or \c sink).
692 <dt>\c PLUGIN-NAME</dt>
694 Name of the plugin which provides the component class of
695 \bt_p{self_message_iterator}.
699 <dd>Name of the component class of \bt_p{self_message_iterator}.</dd>
702 @param[in] self_message_iterator
703 Self message iterator of the appending method.
705 Name of the source file containing the method which appends the
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>).
713 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
715 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
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}
724 <strong>On success</strong>, the number of error causes in the
725 current thread's error is incremented.
727 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() —
728 Calls this function with \c __FILE__ and \c __LINE__ as the
729 \bt_p{file_name} and \bt_p{line_number} parameters.
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
, ...);
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.
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.
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__)
755 Appends an error cause to the current thread's error from a
758 This this a <code>printf()</code>-like function starting from the
759 format string parameter \bt_p{message_format}.
761 As of \bt_name_version_min_maj, the only component class method is the
762 \ref api-qexec "query" method.
764 On success, the appended error cause's module name
765 (see bt_error_cause_get_module_name()) is:
768 CC-TYPE.PLUGIN-NAME.CC-NAME
777 if no \bt_plugin provides \bt_p{self_component_class}, with:
782 Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink).
785 <dt>\c PLUGIN-NAME</dt>
787 Name of the plugin which provides \bt_p{self_component_class}.
791 <dd>Name of \bt_p{self_component_class}.</dd>
794 @param[in] self_component_class
795 Self component class of the appending method.
797 Name of the source file containing the method which appends the
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>).
805 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
807 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
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}
816 <strong>On success</strong>, the number of error causes in the
817 current thread's error is incremented.
819 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() —
820 Calls this function with \c __FILE__ and \c __LINE__ as the
821 \bt_p{file_name} and \bt_p{line_number} parameters.
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
, ...);
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.
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.
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__)
847 Appends an error cause to the current thread's error from any
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().
855 This this a <code>printf()</code>-like function starting from the
856 format string parameter \bt_p{message_format}.
858 @param[in] module_name
859 Module name of the error cause to append.
861 Name of the source file containing the method which appends the
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>).
869 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
871 @retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
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}
880 <strong>On success</strong>, the number of error causes in the
881 current thread's error is incremented.
883 @sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() —
884 Calls this function with \c __FILE__ and \c __LINE__ as the
885 \bt_p{file_name} and \bt_p{line_number} parameters.
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
, ...);
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.
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().
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.
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__)
921 Returns the number of error causes contained in the error
925 Error of which to get the number of contained error causes.
928 Number of contained error causes in \bt_p{error}.
930 @bt_pre_not_null{error}
933 uint64_t bt_error_get_cause_count(const bt_error
*error
);
937 Borrows the error cause at index \bt_p{index} from the
941 Error from which to borrow the error cause at index \bt_p{index}.
943 Index of the error cause to borrow from \bt_p{error}.
947 \em Borrowed reference of the error cause of
948 \bt_p{error} at index \bt_p{index}.
950 The returned pointer remains valid until \bt_p{error} is modified.
953 @bt_pre_not_null{error}
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()).
959 const bt_error_cause
*bt_error_borrow_cause_by_index(
960 const bt_error
*error
, uint64_t index
);
964 Releases (frees) the error \bt_p{error}.
966 After you call this function, \bt_p{error} does not exist.
968 Take the current thread's error with bt_current_thread_take_error().
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.
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.
980 Error to release (free).
982 @bt_pre_not_null{error}
985 \bt_p{error} does not exist.
987 @sa bt_current_thread_move_error() —
988 Moves an error's ownership to the library.
991 void bt_error_release(const bt_error
*error
);
996 @name Error cause: common
1002 Error cause actor type enumerators.
1004 typedef enum bt_error_cause_actor_type
{
1009 BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN
= 1 << 0,
1015 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT
= 1 << 1,
1019 Component class method.
1021 BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS
= 1 << 2,
1025 Message iterator method.
1027 BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR
= 1 << 3,
1028 } bt_error_cause_actor_type
;
1032 Returns the actor type enumerator of the error cause
1035 @param[in] error_cause
1036 Error cause of which to get the actor type enumerator.
1039 Actor type enumerator of \bt_p{error_cause}.
1041 @bt_pre_not_null{error_cause}
1044 bt_error_cause_actor_type
bt_error_cause_get_actor_type(
1045 const bt_error_cause
*error_cause
);
1049 Returns the message of the error cause \bt_p{error_cause}.
1051 @param[in] error_cause
1052 Error cause of which to get the message.
1056 Message of \bt_p{error_cause}.
1058 The returned pointer remains valid as long as the error which
1059 contains \bt_p{error_cause} exists.
1062 @bt_pre_not_null{error_cause}
1065 const char *bt_error_cause_get_message(const bt_error_cause
*error_cause
);
1069 Returns the module name of the error cause \bt_p{error_cause}.
1071 @param[in] error_cause
1072 Error cause of which to get the module name.
1076 Module name of \bt_p{error_cause}.
1078 The returned pointer remains valid as long as the error which
1079 contains \bt_p{error_cause} exists.
1082 @bt_pre_not_null{error_cause}
1085 const char *bt_error_cause_get_module_name(const bt_error_cause
*error_cause
);
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.
1093 @param[in] error_cause
1094 Error cause of which to get the source file name.
1098 Source file name of \bt_p{error_cause}.
1100 The returned pointer remains valid as long as the error which
1101 contains \bt_p{error_cause} exists.
1104 @bt_pre_not_null{error_cause}
1107 const char *bt_error_cause_get_file_name(const bt_error_cause
*error_cause
);
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.
1115 @param[in] error_cause
1116 Error cause of which to get the source statement's line number.
1119 Source statement's line number of \bt_p{error_cause}.
1121 @bt_pre_not_null{error_cause}
1124 uint64_t bt_error_cause_get_line_number(const bt_error_cause
*error_cause
);
1129 @name Error cause with a component actor
1135 Returns the name of the \bt_comp of which a method
1136 appended the error cause \bt_p{error_cause} to the current
1139 @param[in] error_cause
1140 Error cause of which to get the component name.
1144 Component name of \bt_p{error_cause}.
1146 The returned pointer remains valid as long as the error which
1147 contains \bt_p{error_cause} exists.
1150 @bt_pre_not_null{error_cause}
1152 The actor type of \bt_p{error_cause} is
1153 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1156 const char *bt_error_cause_component_actor_get_component_name(
1157 const bt_error_cause
*error_cause
);
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.
1165 @param[in] error_cause
1166 Error cause of which to get the component class type.
1169 Component class type of \bt_p{error_cause}.
1171 @bt_pre_not_null{error_cause}
1173 The actor type of \bt_p{error_cause} is
1174 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1177 bt_component_class_type
bt_error_cause_component_actor_get_component_class_type(
1178 const bt_error_cause
*error_cause
);
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.
1186 @param[in] error_cause
1187 Error cause of which to get the component class name.
1191 Component class name of \bt_p{error_cause}.
1193 The returned pointer remains valid as long as the error which
1194 contains \bt_p{error_cause} exists.
1197 @bt_pre_not_null{error_cause}
1199 The actor type of \bt_p{error_cause} is
1200 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1203 const char *bt_error_cause_component_actor_get_component_class_name(
1204 const bt_error_cause
*error_cause
);
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.
1213 This function returns \c NULL if no plugin provides the error cause's
1216 @param[in] error_cause
1217 Error cause of which to get the plugin name.
1221 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1222 provides the component class of \bt_p{error_cause}.
1224 The returned pointer remains valid as long as the error which
1225 contains \bt_p{error_cause} exists.
1228 @bt_pre_not_null{error_cause}
1230 The actor type of \bt_p{error_cause} is
1231 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
1234 const char *bt_error_cause_component_actor_get_plugin_name(
1235 const bt_error_cause
*error_cause
);
1240 @name Error cause with a message iterator actor
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
1251 @param[in] error_cause
1252 Error cause of which to get the output port name.
1256 Output port name of \bt_p{error_cause}.
1258 The returned pointer remains valid as long as the error which
1259 contains \bt_p{error_cause} exists.
1262 @bt_pre_not_null{error_cause}
1264 The actor type of \bt_p{error_cause} is
1265 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1268 const char *bt_error_cause_message_iterator_actor_get_component_output_port_name(
1269 const bt_error_cause
*error_cause
);
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
1277 @param[in] error_cause
1278 Error cause of which to get the component name.
1282 Component name of \bt_p{error_cause}.
1284 The returned pointer remains valid as long as the error which
1285 contains \bt_p{error_cause} exists.
1288 @bt_pre_not_null{error_cause}
1290 The actor type of \bt_p{error_cause} is
1291 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1294 const char *bt_error_cause_message_iterator_actor_get_component_name(
1295 const bt_error_cause
*error_cause
);
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.
1303 @param[in] error_cause
1304 Error cause of which to get the component class type.
1307 Component class type of \bt_p{error_cause}.
1309 @bt_pre_not_null{error_cause}
1311 The actor type of \bt_p{error_cause} is
1312 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1315 bt_component_class_type
1316 bt_error_cause_message_iterator_actor_get_component_class_type(
1317 const bt_error_cause
*error_cause
);
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.
1325 @param[in] error_cause
1326 Error cause of which to get the component class name.
1330 Component class name of \bt_p{error_cause}.
1332 The returned pointer remains valid as long as the error which
1333 contains \bt_p{error_cause} exists.
1336 @bt_pre_not_null{error_cause}
1338 The actor type of \bt_p{error_cause} is
1339 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1342 const char *bt_error_cause_message_iterator_actor_get_component_class_name(
1343 const bt_error_cause
*error_cause
);
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.
1353 This function returns \c NULL if no plugin provides the error cause's
1356 @param[in] error_cause
1357 Error cause of which to get the plugin name.
1361 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1362 provides the component class of \bt_p{error_cause}.
1364 The returned pointer remains valid as long as the error which
1365 contains \bt_p{error_cause} exists.
1368 @bt_pre_not_null{error_cause}
1370 The actor type of \bt_p{error_cause} is
1371 #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
1374 const char *bt_error_cause_message_iterator_actor_get_plugin_name(
1375 const bt_error_cause
*error_cause
);
1380 @name Error cause with a component class actor
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.
1390 @param[in] error_cause
1391 Error cause of which to get the component class name.
1394 Component class name of \bt_p{error_cause}.
1396 @bt_pre_not_null{error_cause}
1398 The actor type of \bt_p{error_cause} is
1399 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1402 bt_component_class_type
1403 bt_error_cause_component_class_actor_get_component_class_type(
1404 const bt_error_cause
*error_cause
);
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.
1412 @param[in] error_cause
1413 Error cause of which to get the component class name.
1417 Component class name of \bt_p{error_cause}.
1419 The returned pointer remains valid as long as the error which
1420 contains \bt_p{error_cause} exists.
1423 @bt_pre_not_null{error_cause}
1425 The actor type of \bt_p{error_cause} is
1426 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1429 const char *bt_error_cause_component_class_actor_get_component_class_name(
1430 const bt_error_cause
*error_cause
);
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.
1439 This function returns \c NULL if no plugin provides the error cause's
1442 @param[in] error_cause
1443 Error cause of which to get the plugin name.
1447 Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
1448 provides the component class of \bt_p{error_cause}.
1450 The returned pointer remains valid as long as the error which
1451 contains \bt_p{error_cause} exists.
1454 @bt_pre_not_null{error_cause}
1456 The actor type of \bt_p{error_cause} is
1457 #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
1460 const char *bt_error_cause_component_class_actor_get_plugin_name(
1461 const bt_error_cause
*error_cause
);
1471 #endif /* BABELTRACE2_ERROR_REPORTING_H */