Detailed Description

Error reporting functions and macros.

This module contains functions and macros to report rich errors from a user function (a component class method, a query operation, or a trace processing graph listener, for example) to any function caller.

Because Babeltrace 2 orchestrates pieces written by different authors, it is important that an error which occurs deep into the function call stack can percolate up to its callers.

The very basic mechanism to report an error from a function is to return an error status (a status code enumerator which contains the word ERROR): each function caller can clean its own context and return an error status code itself until one caller "catches" the status code and reacts to it. For example, the reaction can be to show an error message to the end user.

This error reporting API adds a layer so that each function which returns an error status code can append a message which describes the cause of the error within the function's context.

Functions append error causes to the current thread's error. Having one error object per thread makes this API thread-safe.

Here's a visual, step-by-step example:

The trace processing graph user calls bt_graph_run().
bt_graph_run() calls the consuming method of the sink component.
The sink component calls bt_message_iterator_next() on its upstream source message iterator.
bt_message_iterator_next() calls the source message iterator's "next" method.

An error occurs within the "next" method of the source message iterator: the function cannot read a file because permission was denied.

The source message iterator's "next" method appends the error cause "Cannot read file /some/file: permission denied" and returns BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR.

bt_message_iterator_next() appends the error cause "Message iterator's 'next' method failed" with details about the source component and returns BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR.

The sink component's "consume" method appends the error cause "Cannot consume upstream message iterator's messages" and returns BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR.
bt_graph_run() appends the error cause "Component's 'consume' method failed" with details about the sink component and returns BT_GRAPH_RUN_STATUS_ERROR.

At this point, the current thread's error contains four causes:

"Cannot read file /some/file: permission denied"
"Message iterator's 'next' method failed"
"Cannot consume upstream message iterator's messages"
"Component's 'consume' method failed"

This list of error causes is much richer for the end user than dealing only with BT_GRAPH_RUN_STATUS_ERROR (the last error status code).

Both error (bt_error) and error cause (bt_error_cause) objects are unique objects:

An error belongs to either the library or you (see Handle an error).
An error cause belongs to the error which contains it.

Append an error cause

When your function returns an error status code, use one of the bt_current_thread_error_append_cause_from_*() functions or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*() macros to append an error cause to the current thread's error. Use the appropriate function or macro depending on your function's actor amongst:

Component

Append an error cause from a component method.

Use bt_current_thread_error_append_cause_from_component() or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT().

Message iterator

Append an error cause from a message iterator method.

Use bt_current_thread_error_append_cause_from_message_iterator() or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR().

Component class

Append an error cause from a component class method ("query" method).

Use bt_current_thread_error_append_cause_from_component_class() or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().

Unknown

Append an error cause from any other function, for example a graph listener or a function of your user application).

Use bt_current_thread_error_append_cause_from_unknown() or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN().

The BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*() macros uses __FILE__ and __LINE__ as the file name and line number parameters of their corresponding bt_current_thread_error_append_cause_from_*() function.

Handle an error

If any libbabeltrace2 function you call returns an error status code, do one of:

Return an error status code too.

In that case, you can append an error cause to the current thread's error.
Take the current thread's error with bt_current_thread_take_error().

This function moves the ownership of the error object from the library to you.

At this point, you can inspect its causes with bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and then do one of:
- Call bt_error_release() to free the error object.
  
  In object-oriented programming terms, this corresponds to catching an exception and discarding it.
- Call bt_current_thread_move_error() to move back the error object's ownership to the library.
  
  In object-oriented programming terms, this corresponds to catching an exception and rethrowing it.

bt_current_thread_clear_error() is a helper which is the equivalent of:

bt_error_release(bt_current_thread_take_error());

Error cause

All error causes have the type bt_error_cause.

There are four types of error cause actors:

Get the type enumerator of an error cause's actor with bt_error_cause_get_actor_type().

An error cause has the following common properties:

Message

Description of the error cause.

Use bt_error_cause_get_message().

Module name

Name of the module causing the error.

For example, libbabeltrace2 uses "libbabeltrace2" and the babeltrace2 CLI tool uses "Babeltrace CLI".

Use bt_error_cause_get_module_name().

File name

Name of the source file causing the error.

Use bt_error_cause_get_file_name().

Line number

Line number of the statement causing the error.

Use bt_error_cause_get_line_number().

Error cause with a component actor

An error cause with a component actor has the following specific properties:

Component name

Name of the component.

Use bt_error_cause_component_actor_get_component_name().

Component class name

Name of the component's class.

Use bt_error_cause_component_actor_get_component_class_type().

Component class type

Type of the component's class.

Use bt_error_cause_component_actor_get_component_class_name().

Optional: Plugin name

Name of the plugin which provides the component's class, if any.

Use bt_error_cause_component_actor_get_plugin_name().

Error cause with a message iterator actor

An error cause with a message iterator actor has the following specific properties:

Component output port name

Name of the component output port from which the message iterator was created.

Use bt_error_cause_component_actor_get_component_name().

Component name

Name of the component.

Use bt_error_cause_component_actor_get_component_name().

bt_error_cause_message_iterator_actor_get_component_output_port_name

Component class name

Name of the component's class.

Use bt_error_cause_component_actor_get_component_class_type().

Component class type

Type of the component's class.

Use bt_error_cause_component_actor_get_component_class_name().

Optional: Plugin name

Name of the plugin which provides the component's class, if any.

Use bt_error_cause_component_actor_get_plugin_name().

Error cause with a component class actor

An error cause with a component class actor has the following specific properties:

Component class name

Name of the component class.

Use bt_error_cause_component_class_actor_get_component_class_type().

Component class type

Type of the component class.

Use bt_error_cause_component_class_actor_get_component_class_name().

Optional: Plugin name

Name of the plugin which provides the component class, if any.

Use bt_error_cause_component_class_actor_get_plugin_name().

Types
typedef struct bt_error	bt_error
	Error.

typedef struct bt_error_cause	bt_error_cause
	Error cause.

Current thread's error
const bt_error *	bt_current_thread_take_error (void)
	Takes the current thread's error, that is, moves its ownership from the library to the caller. More...

void	bt_current_thread_move_error (const bt_error *error)
	Moves the ownership of the error error from the caller to the library. More...

void	bt_current_thread_clear_error (void)
	Releases the current thread's error, if any. More...

#define	BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error)
	Moves the ownership of the error _error from the caller to the library, and then sets _error to `NULL`. More...

Error cause appending
enum	bt_current_thread_error_append_cause_status { BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK, BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR }
	Status codes for the `bt_current_thread_error_append_cause_from_*()` functions. More...

typedef enum bt_current_thread_error_append_cause_status	bt_current_thread_error_append_cause_status
	Status codes for the `bt_current_thread_error_append_cause_from_*()` functions.

bt_current_thread_error_append_cause_status	bt_current_thread_error_append_cause_from_component (bt_self_component self_component, const char file_name, uint64_t line_number, const char *message_format,...)
	Appends an error cause to the current thread's error from a component method. More...

bt_current_thread_error_append_cause_status	bt_current_thread_error_append_cause_from_message_iterator (bt_self_message_iterator self_message_iterator, const char file_name, uint64_t line_number, const char *message_format,...)
	Appends an error cause to the current thread's error from a message iterator method. More...

bt_current_thread_error_append_cause_status	bt_current_thread_error_append_cause_from_component_class (bt_self_component_class self_component_class, const char file_name, uint64_t line_number, const char *message_format,...)
	Appends an error cause to the current thread's error from a component class method. More...

bt_current_thread_error_append_cause_status	bt_current_thread_error_append_cause_from_unknown (const char module_name, const char file_name, uint64_t line_number, const char *message_format,...)
	Appends an error cause to the current thread's error from any function. More...

#define	BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_component, _message_format, ...)
	Appends an error cause to the current thread's error from a component method using `__FILE__` and `__LINE__` as the source file name and line number. More...

#define	BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_message_iterator, _message_format, ...)
	Appends an error cause to the current thread's error from a message iterator method using `__FILE__` and `__LINE__` as the source file name and line number. More...

#define	BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_component_class, _message_format, ...)
	Appends an error cause to the current thread's error from a component class method using `__FILE__` and `__LINE__` as the source file name and line number. More...

#define	BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _message_format, ...)
	Appends an error cause to the current thread's error from any function using `__FILE__` and `__LINE__` as the source file name and line number. More...

Error
uint64_t	bt_error_get_cause_count (const bt_error *error)
	Returns the number of error causes contained in the error error. More...

const bt_error_cause *	bt_error_borrow_cause_by_index (const bt_error *error, uint64_t index)
	Borrows the error cause at index index from the error error. More...

void	bt_error_release (const bt_error *error)
	Releases (frees) the error error. More...

Error cause: common
enum	bt_error_cause_actor_type { BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN, BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT, BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS, BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR }
	Error cause actor type enumerators. More...

typedef enum bt_error_cause_actor_type	bt_error_cause_actor_type
	Error cause actor type enumerators.

bt_error_cause_actor_type	bt_error_cause_get_actor_type (const bt_error_cause *error_cause)
	Returns the actor type enumerator of the error cause error_cause. More...

const char *	bt_error_cause_get_message (const bt_error_cause *error_cause)
	Returns the message of the error cause error_cause. More...

const char *	bt_error_cause_get_module_name (const bt_error_cause *error_cause)
	Returns the module name of the error cause error_cause. More...

const char *	bt_error_cause_get_file_name (const bt_error_cause *error_cause)
	Returns the name of the source file which contains the function which appended the error cause error_cause to the current thread's error. More...

uint64_t	bt_error_cause_get_line_number (const bt_error_cause *error_cause)
	Returns the line number of the statement which appended the error cause error_cause to the current thread's error. More...

Error cause with a component actor
const char *	bt_error_cause_component_actor_get_component_name (const bt_error_cause *error_cause)
	Returns the name of the component of which a method appended the error cause error_cause to the current thread's error. More...

bt_component_class_type	bt_error_cause_component_actor_get_component_class_type (const bt_error_cause *error_cause)
	Returns the class type of the component of which a method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_component_actor_get_component_class_name (const bt_error_cause *error_cause)
	Returns the class name of the component of which a method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_component_actor_get_plugin_name (const bt_error_cause *error_cause)
	Returns the name of the plugin which provides the class of the component of which a method appended the error cause error_cause to the current thread's error. More...

Error cause with a message iterator actor
const char *	bt_error_cause_message_iterator_actor_get_component_output_port_name (const bt_error_cause *error_cause)
	Returns the name of the output port from which was created the message iterator of which the method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_message_iterator_actor_get_component_name (const bt_error_cause *error_cause)
	Returns the name of the component of which a message iterator method appended the error cause error_cause to the current thread's error. More...

bt_component_class_type	bt_error_cause_message_iterator_actor_get_component_class_type (const bt_error_cause *error_cause)
	Returns the class type of the component of which a message iterator method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_message_iterator_actor_get_component_class_name (const bt_error_cause *error_cause)
	Returns the class name of the component of which a message iterator method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_message_iterator_actor_get_plugin_name (const bt_error_cause *error_cause)
	Returns the name of the plugin which provides the class of the component of which a message iterator method appended the error cause error_cause to the current thread's error. More...

Error cause with a component class actor
bt_component_class_type	bt_error_cause_component_class_actor_get_component_class_type (const bt_error_cause *error_cause)
	Returns the name of the component class of which a method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_component_class_actor_get_component_class_name (const bt_error_cause *error_cause)
	Returns the name of the component class of which a method appended the error cause error_cause to the current thread's error. More...

const char *	bt_error_cause_component_class_actor_get_plugin_name (const bt_error_cause *error_cause)
	Returns the name of the plugin which provides the component class of which a method appended the error cause error_cause to the current thread's error. More...

Enumeration Type Documentation

◆ bt_current_thread_error_append_cause_status

enum bt_current_thread_error_append_cause_status

Status codes for the bt_current_thread_error_append_cause_from_*() functions.

Enumerator
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK	Success.
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR	Out of memory.

◆ bt_error_cause_actor_type

enum bt_error_cause_actor_type

Error cause actor type enumerators.

Enumerator
BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN	Any function.
BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT	Component method.
BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS	Component class method.
BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR	Message iterator method.

Macro Definition Documentation

◆ BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET

#define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET ( _error )

Moves the ownership of the error _error from the caller to the library, and then sets _error to NULL.

Parameters

[in] _error Error of which to move the ownership from you to the library.

Precondition: _error is not NULL.; _error is an assignable expression.; The caller owns _error.

Postcondition: The library owns _error.

See also: bt_current_thread_move_error() — Moves an error's ownership to the library.

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT

#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT	(	_self_component,
		_message_format,
		...
	)

Appends an error cause to the current thread's error from a component method using __FILE__ and __LINE__ as the source file name and line number.

This macro calls bt_current_thread_error_append_cause_from_component() with __FILE__ and __LINE__ as its file_name and line_number parameters.

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR

#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR	(	_self_message_iterator,
		_message_format,
		...
	)

Appends an error cause to the current thread's error from a message iterator method using __FILE__ and __LINE__ as the source file name and line number.

This macro calls bt_current_thread_error_append_cause_from_message_iterator() with __FILE__ and __LINE__ as its file_name and line_number parameters.

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS

#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS	(	_self_component_class,
		_message_format,
		...
	)

Appends an error cause to the current thread's error from a component class method using __FILE__ and __LINE__ as the source file name and line number.

This macro calls bt_current_thread_error_append_cause_from_component_class() with __FILE__ and __LINE__ as its file_name and line_number parameters.

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN

#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN	(	_module_name,
		_message_format,
		...
	)

Appends an error cause to the current thread's error from any function using __FILE__ and __LINE__ as the source file name and line number.

Use this function when you cannot use BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(), BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(), or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().

This macro calls bt_current_thread_error_append_cause_from_unknown() with __FILE__ and __LINE__ as its file_name and line_number parameters.

Function Documentation

◆ bt_current_thread_take_error()

const bt_error* bt_current_thread_take_error ( void )

Takes the current thread's error, that is, moves its ownership from the library to the caller.

This function can return NULL if the current thread has no error.

Once you are done with the returned error, do one of:

Call bt_error_release() to free the error object.

In object-oriented programming terms, this corresponds to catching an exception and discarding it.
Call bt_current_thread_move_error() to move back the error object's ownership to the library.

In object-oriented programming terms, this corresponds to catching an exception and rethrowing it.

Returns: Unique reference of the current thread's error, or NULL if the current thread has no error.

Postcondition: If this function does not return NULL, the caller owns the returned error.

See also: bt_error_release() — Releases (frees) an error.; bt_current_thread_move_error() — Moves an error's ownership to the library.

◆ bt_current_thread_move_error()

void bt_current_thread_move_error ( const bt_error * error )

Moves the ownership of the error error from the caller to the library.

After you call this function, you don't own error anymore.

In object-oriented programming terms, calling this function corresponds to catching an exception and rethrowing it.

You can instead release (free) the error with bt_error_release(), which, in object-oriented programming terms, corresponds to catching an exception and discarding it.

Parameters

[in] error Error of which to move the ownership from you to the library.

Precondition: error is not NULL.; The caller owns error.

Postcondition: The library owns error.

See also: bt_error_release() — Releases (frees) an error.; BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() — Calls this function and assigns NULL to the expression.

◆ bt_current_thread_clear_error()

void bt_current_thread_clear_error ( void )

Releases the current thread's error, if any.

This function is equivalent to:

bt_error_release(bt_current_thread_take_error());

Postcondition: The current thread has no error.

See also: bt_error_release() — Releases (frees) an error.; bt_current_thread_take_error — Takes the current thread's error, moving its ownership from the library to the caller.

◆ bt_current_thread_error_append_cause_from_component()

bt_current_thread_error_append_cause_status bt_current_thread_error_append_cause_from_component	(	bt_self_component *	self_component,
		const char *	file_name,
		uint64_t	line_number,
		const char *	message_format,
			...
	)

Appends an error cause to the current thread's error from a component method.

This this a printf()-like function starting from the format string parameter message_format.

On success, the appended error cause's module name (see bt_error_cause_get_module_name()) is:

NAME: CC-TYPE.PLUGIN-NAME.CC-NAME

or

NAME: CC-TYPE.CC-NAME

if no plugin provides the class of self_component, with:

NAME

Name of self_component.

CC-TYPE

Type of the class of self_component (src, flt, or sink).

PLUGIN-NAME

Name of the plugin which provides the class of self_component.

CC-NAME

Name of the class of self_component.

Parameters

[in]	self_component	Self component of the appending method.
[in]	file_name	Name of the source file containing the method which appends the error cause.
[in]	line_number	Line number of the statement which appends the error cause.
[in]	message_format	Format string which specifies how the function converts the subsequent arguments (like `printf()`).

Return values

BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK	Success.
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: self_component is not NULL.; file_name is not NULL.; message_format is not NULL.; message_format is a valid printf()-like format string.

Postcondition: On success, the number of error causes in the current thread's error is incremented.

See also: BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() — Calls this function with __FILE__ and __LINE__ as the file_name and line_number parameters.

◆ bt_current_thread_error_append_cause_from_message_iterator()

bt_current_thread_error_append_cause_status bt_current_thread_error_append_cause_from_message_iterator	(	bt_self_message_iterator *	self_message_iterator,
		const char *	file_name,
		uint64_t	line_number,
		const char *	message_format,
			...
	)

Appends an error cause to the current thread's error from a message iterator method.

This this a printf()-like function starting from the format string parameter message_format.

On success, the appended error cause's module name (see bt_error_cause_get_module_name()) is:

COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME

or

COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME

if no plugin provides the component class of self_message_iterator, with:

COMP-NAME

Name of the component of self_message_iterator.

OUT-PORT-NAME

Name of the output port from which self_message_iterator. was created.

CC-TYPE

Type of the component class of self_message_iterator (src, flt, or sink).

PLUGIN-NAME

Name of the plugin which provides the component class of self_message_iterator.

CC-NAME

Name of the component class of self_message_iterator.

Parameters

[in]	self_message_iterator	Self message iterator of the appending method.
[in]	file_name	Name of the source file containing the method which appends the error cause.
[in]	line_number	Line number of the statement which appends the error cause.
[in]	message_format	Format string which specifies how the function converts the subsequent arguments (like `printf()`).

Return values

BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK	Success.
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: self_message_iterator is not NULL.; file_name is not NULL.; message_format is not NULL.; message_format is a valid printf()-like format string.

Postcondition: On success, the number of error causes in the current thread's error is incremented.

See also: BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() — Calls this function with __FILE__ and __LINE__ as the file_name and line_number parameters.

◆ bt_current_thread_error_append_cause_from_component_class()

bt_current_thread_error_append_cause_status bt_current_thread_error_append_cause_from_component_class	(	bt_self_component_class *	self_component_class,
		const char *	file_name,
		uint64_t	line_number,
		const char *	message_format,
			...
	)

Appends an error cause to the current thread's error from a component class method.

This this a printf()-like function starting from the format string parameter message_format.

As of Babeltrace 2.0, the only component class method is the query method.

On success, the appended error cause's module name (see bt_error_cause_get_module_name()) is:

CC-TYPE.PLUGIN-NAME.CC-NAME

or

CC-TYPE.CC-NAME

if no plugin provides self_component_class, with:

CC-TYPE

Type of self_component_class (src, flt, or sink).

PLUGIN-NAME

Name of the plugin which provides self_component_class.

CC-NAME

Name of self_component_class.

Parameters

[in]	self_component_class	Self component class of the appending method.
[in]	file_name	Name of the source file containing the method which appends the error cause.
[in]	line_number	Line number of the statement which appends the error cause.
[in]	message_format	Format string which specifies how the function converts the subsequent arguments (like `printf()`).

Return values

BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK	Success.
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: self_component_class is not NULL.; file_name is not NULL.; message_format is not NULL.; message_format is a valid printf()-like format string.

Postcondition: On success, the number of error causes in the current thread's error is incremented.

See also: BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() — Calls this function with __FILE__ and __LINE__ as the file_name and line_number parameters.

◆ bt_current_thread_error_append_cause_from_unknown()

bt_current_thread_error_append_cause_status bt_current_thread_error_append_cause_from_unknown	(	const char *	module_name,
		const char *	file_name,
		uint64_t	line_number,
		const char *	message_format,
			...
	)

Appends an error cause to the current thread's error from any function.

Use this function when you cannot use bt_current_thread_error_append_cause_from_component(), bt_current_thread_error_append_cause_from_message_iterator(), or bt_current_thread_error_append_cause_from_component_class().

This this a printf()-like function starting from the format string parameter message_format.

Parameters

[in]	module_name	Module name of the error cause to append.
[in]	file_name	Name of the source file containing the method which appends the error cause.
[in]	line_number	Line number of the statement which appends the error cause.
[in]	message_format	Format string which specifies how the function converts the subsequent arguments (like `printf()`).

Return values

BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK	Success.
BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR	Out of memory.

Precondition: module_name is not NULL.; file_name is not NULL.; message_format is not NULL.; message_format is a valid printf()-like format string.

Postcondition: On success, the number of error causes in the current thread's error is incremented.

See also: BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() — Calls this function with __FILE__ and __LINE__ as the file_name and line_number parameters.

◆ bt_error_get_cause_count()

uint64_t bt_error_get_cause_count ( const bt_error * error )

Returns the number of error causes contained in the error error.

Parameters

[in] error Error of which to get the number of contained error causes.

Returns: Number of contained error causes in error.

Precondition: error is not NULL.

◆ bt_error_borrow_cause_by_index()

const bt_error_cause* bt_error_borrow_cause_by_index	(	const bt_error *	error,
		uint64_t	index
	)

Borrows the error cause at index index from the error error.

Parameters

[in]	error	Error from which to borrow the error cause at index index.
[in]	index	Index of the error cause to borrow from error.

Returns

Borrowed reference of the error cause of error at index index.

The returned pointer remains valid until error is modified.

Precondition: error is not NULL.; index is less than the number of error causes in error (as returned by bt_error_get_cause_count()).

◆ bt_error_release()

void bt_error_release ( const bt_error * error )

Releases (frees) the error error.

After you call this function, error does not exist.

Take the current thread's error with bt_current_thread_take_error().

In object-oriented programming terms, calling this function corresponds to catching an exception and discarding it.

You can instead move the ownership of error to the library with bt_current_thread_move_error(), which, in object-oriented programming terms, corresponds to catching an exception and rethrowing it.

Parameters

[in] error Error to release (free).

Precondition: error is not NULL.

Postcondition: error does not exist.

See also: bt_current_thread_move_error() — Moves an error's ownership to the library.

◆ bt_error_cause_get_actor_type()

bt_error_cause_actor_type bt_error_cause_get_actor_type ( const bt_error_cause * error_cause )

Returns the actor type enumerator of the error cause error_cause.

Parameters

[in] error_cause Error cause of which to get the actor type enumerator.

Returns: Actor type enumerator of error_cause.

Precondition: error_cause is not NULL.

◆ bt_error_cause_get_message()

const char* bt_error_cause_get_message ( const bt_error_cause * error_cause )

Returns the message of the error cause error_cause.

Parameters

[in] error_cause Error cause of which to get the message.

Returns

Message of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.

◆ bt_error_cause_get_module_name()

const char* bt_error_cause_get_module_name ( const bt_error_cause * error_cause )

Returns the module name of the error cause error_cause.

Parameters

[in] error_cause Error cause of which to get the module name.

Returns

Module name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.

◆ bt_error_cause_get_file_name()

const char* bt_error_cause_get_file_name ( const bt_error_cause * error_cause )

Returns the name of the source file which contains the function which appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the source file name.

Returns

Source file name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.

◆ bt_error_cause_get_line_number()

uint64_t bt_error_cause_get_line_number ( const bt_error_cause * error_cause )

Returns the line number of the statement which appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the source statement's line number.

Returns: Source statement's line number of error_cause.

Precondition: error_cause is not NULL.

◆ bt_error_cause_component_actor_get_component_name()

const char* bt_error_cause_component_actor_get_component_name ( const bt_error_cause * error_cause )

Returns the name of the component of which a method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component name.

Returns

Component name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.

◆ bt_error_cause_component_actor_get_component_class_type()

bt_component_class_type bt_error_cause_component_actor_get_component_class_type ( const bt_error_cause * error_cause )

Returns the class type of the component of which a method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class type.

Returns: Component class type of error_cause.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.

◆ bt_error_cause_component_actor_get_component_class_name()

const char* bt_error_cause_component_actor_get_component_class_name ( const bt_error_cause * error_cause )

Returns the class name of the component of which a method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class name.

Returns

Component class name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.

◆ bt_error_cause_component_actor_get_plugin_name()

const char* bt_error_cause_component_actor_get_plugin_name ( const bt_error_cause * error_cause )

Returns the name of the plugin which provides the class of the component of which a method appended the error cause error_cause to the current thread's error.

This function returns NULL if no plugin provides the error cause's component class.

Parameters

[in] error_cause Error cause of which to get the plugin name.

Returns

Plugin name of error_cause, or NULL if no plugin provides the component class of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.

◆ bt_error_cause_message_iterator_actor_get_component_output_port_name()

const char* bt_error_cause_message_iterator_actor_get_component_output_port_name ( const bt_error_cause * error_cause )

Returns the name of the output port from which was created the message iterator of which the method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the output port name.

Returns

Output port name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.

◆ bt_error_cause_message_iterator_actor_get_component_name()

const char* bt_error_cause_message_iterator_actor_get_component_name ( const bt_error_cause * error_cause )

Returns the name of the component of which a message iterator method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component name.

Returns

Component name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.

◆ bt_error_cause_message_iterator_actor_get_component_class_type()

bt_component_class_type bt_error_cause_message_iterator_actor_get_component_class_type ( const bt_error_cause * error_cause )

Returns the class type of the component of which a message iterator method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class type.

Returns: Component class type of error_cause.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.

◆ bt_error_cause_message_iterator_actor_get_component_class_name()

const char* bt_error_cause_message_iterator_actor_get_component_class_name ( const bt_error_cause * error_cause )

Returns the class name of the component of which a message iterator method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class name.

Returns

Component class name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.

◆ bt_error_cause_message_iterator_actor_get_plugin_name()

const char* bt_error_cause_message_iterator_actor_get_plugin_name ( const bt_error_cause * error_cause )

Returns the name of the plugin which provides the class of the component of which a message iterator method appended the error cause error_cause to the current thread's error.

This function returns NULL if no plugin provides the error cause's component class.

Parameters

[in] error_cause Error cause of which to get the plugin name.

Returns

Plugin name of error_cause, or NULL if no plugin provides the component class of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.

◆ bt_error_cause_component_class_actor_get_component_class_type()

bt_component_class_type bt_error_cause_component_class_actor_get_component_class_type ( const bt_error_cause * error_cause )

Returns the name of the component class of which a method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class name.

Returns: Component class name of error_cause.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.

◆ bt_error_cause_component_class_actor_get_component_class_name()

const char* bt_error_cause_component_class_actor_get_component_class_name ( const bt_error_cause * error_cause )

Returns the name of the component class of which a method appended the error cause error_cause to the current thread's error.

Parameters

[in] error_cause Error cause of which to get the component class name.

Returns

Component class name of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.

◆ bt_error_cause_component_class_actor_get_plugin_name()

const char* bt_error_cause_component_class_actor_get_plugin_name ( const bt_error_cause * error_cause )

Returns the name of the plugin which provides the component class of which a method appended the error cause error_cause to the current thread's error.

This function returns NULL if no plugin provides the error cause's component class.

Parameters

[in] error_cause Error cause of which to get the plugin name.

Returns

Plugin name of error_cause, or NULL if no plugin provides the component class of error_cause.

The returned pointer remains valid as long as the error which contains error_cause exists.

Precondition: error_cause is not NULL.; The actor type of error_cause is BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.

Detailed Description

Append an error cause

Handle an error

Error cause

Error cause with a component actor

Error cause with a message iterator actor

Error cause with a component class actor

Types

Current thread's error

Error cause appending

Error

Error cause: common

Error cause with a component actor

Error cause with a message iterator actor

Error cause with a component class actor

Enumeration Type Documentation

◆ bt_current_thread_error_append_cause_status

◆ bt_error_cause_actor_type

Macro Definition Documentation

◆ BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS

◆ BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN

Function Documentation

◆ bt_current_thread_take_error()

◆ bt_current_thread_move_error()

◆ bt_current_thread_clear_error()

◆ bt_current_thread_error_append_cause_from_component()

◆ bt_current_thread_error_append_cause_from_message_iterator()

◆ bt_current_thread_error_append_cause_from_component_class()

◆ bt_current_thread_error_append_cause_from_unknown()

◆ bt_error_get_cause_count()

◆ bt_error_borrow_cause_by_index()

◆ bt_error_release()

◆ bt_error_cause_get_actor_type()

◆ bt_error_cause_get_message()

◆ bt_error_cause_get_module_name()

◆ bt_error_cause_get_file_name()

◆ bt_error_cause_get_line_number()

◆ bt_error_cause_component_actor_get_component_name()

◆ bt_error_cause_component_actor_get_component_class_type()

◆ bt_error_cause_component_actor_get_component_class_name()

◆ bt_error_cause_component_actor_get_plugin_name()

◆ bt_error_cause_message_iterator_actor_get_component_output_port_name()

◆ bt_error_cause_message_iterator_actor_get_component_name()

◆ bt_error_cause_message_iterator_actor_get_component_class_type()

◆ bt_error_cause_message_iterator_actor_get_component_class_name()

◆ bt_error_cause_message_iterator_actor_get_plugin_name()

◆ bt_error_cause_component_class_actor_get_component_class_type()

◆ bt_error_cause_component_class_actor_get_component_class_name()

◆ bt_error_cause_component_class_actor_get_plugin_name()