Description

Lumiera error handling (C interface).

This header declares the interface for C-style error handling based on a thread local error flag. This error state is "sticky"; client code is bound to clear the error flag explicitly before being able to set another error state.

Error states are tightly integrated with NoBug based logging, as well as with the exceptions used by the C++ part of the application: throwing an exception automatically sets the error flag, and by policy, any catch clause has to check, log and clear the error flag too.

See also: error.hpp C++ interface; error-state.c; error-exception.cpp

Definition in file error.h.

#include <nobug.h>
#include <stdlib.h>

Typedefs
typedef const char *	lumiera_err

Macros
#define	LUMIERA_DIE(err) do { NOBUG_ERROR(NOBUG_ON, "Fatal Error: %s ", strchr(LUMIERA_ERROR_##err, ':')); abort(); } while(0)
	Abort unconditionally with a 'Fatal Error!' message. More...

#define	LUMIERA_ERROR_DECLARE(err) extern lumiera_err const LUMIERA_ERROR_##err
	Forward declare an error constant. More...

#define	LUMIERA_ERROR_DEFINE(err, msg) lumiera_err const LUMIERA_ERROR_##err = "LUMIERA_ERROR_" #err ":" msg
	Definition and initialisation of an error constant. More...

#define	LUMIERA_ERROR_SET(flag, err, extra)
	Helper macro to raise an error for the current thread. More...

#define	LUMIERA_ERROR_SET_ALERT(flag, err, extra)
	Helper macro to raise an error for the current thread. More...

#define	LUMIERA_ERROR_SET_CRITICAL(flag, err, extra)
	Helper macro to raise an error for the current thread. More...

#define	LUMIERA_ERROR_SET_WARNING(flag, err, extra)
	Helper macro to raise an error for the current thread. More...

Functions
lumiera_err	lumiera_error (void)
	Get and clear current error state. More...

	LUMIERA_ERROR_DECLARE (ERRNO)

	LUMIERA_ERROR_DECLARE (UNKNOWN)

int	lumiera_error_expect (lumiera_err expected)
	Expect some error Check that the current error state matches some expectation, if true then the error state is cleared and 1 is returned, otherwise 0 is returned and the error state remains set. More...

const char *	lumiera_error_extra (void)
	Query the extra context for the last error. More...

lumiera_err	lumiera_error_peek (void)
	Check current error state without clearing it Please avoid this function and use lumiera_error() if possible. More...

lumiera_err	lumiera_error_set (lumiera_err nerr, const char *extra)
	Set error state for the current thread. More...

Macro Definition Documentation

◆ LUMIERA_DIE

#define LUMIERA_DIE ( err ) do { NOBUG_ERROR(NOBUG_ON, "Fatal Error: %s ", strchr(LUMIERA_ERROR_##err, ':')); abort(); } while(0)

Abort unconditionally with a 'Fatal Error!' message.

This macro is used whenever the program end up in a invalid state from which no runtime recovery is possible

Definition at line 63 of file error.h.

Referenced by die_no_mem(), lumiera_mutex_destroy(), lumiera_mutex_lock(), lumiera_mutex_unlock(), and lumiera_recmutex_destroy().

◆ LUMIERA_ERROR_DECLARE

#define LUMIERA_ERROR_DECLARE ( err ) extern lumiera_err const LUMIERA_ERROR_##err

Forward declare an error constant.

This macro eases the error declaration in header files

Parameters

err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)

Definition at line 71 of file error.h.

Referenced by Error::prependInfo().

◆ LUMIERA_ERROR_DEFINE

#define LUMIERA_ERROR_DEFINE	(	err,
		msg
	)	lumiera_err const LUMIERA_ERROR_##err = "LUMIERA_ERROR_" #err ":" msg

Definition and initialisation of an error constant.

This macro eases the error definition in implementation files

Parameters

err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
msg	message describing the error in plain English (example: "memory allocation failed")

Definition at line 80 of file error.h.

Referenced by MediaFactory::operator()(), ModelPortRegistry::rollback(), and FixedFrameQuantiser::timeOf().

◆ LUMIERA_ERROR_SET

#define LUMIERA_ERROR_SET	(	flag,
		err,
		extra
	)

Value:

do {                                                                                                  \
  const char* theextra = extra;                                                                         \
  ERROR (flag, "%s%s%s", strchr(LUMIERA_ERROR_##err, ':')+1, theextra?": ":"", theextra?theextra:"");   \
  lumiera_error_set(LUMIERA_ERROR_##err, theextra);                                                     \
  } while (0)

Helper macro to raise an error for the current thread.

This macro eases setting an error. It adds NoBug logging support to the low level error handling. Used for unexpected errors which can be handled without any problems.

Parameters

flag	NoBug flag describing the subsystem where the error was raised
err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extra	optional string (or NULL) which adds some more context to the error, can be a temporary

Definition at line 91 of file error.h.

Referenced by lumiera_lockerror_set().

◆ LUMIERA_ERROR_SET_ALERT

#define LUMIERA_ERROR_SET_ALERT	(	flag,
		err,
		extra
	)

Value:

do {                                                                                                  \
  const char* theextra = extra;                                                                         \
  ALERT (flag, "%s%s%s", strchr(LUMIERA_ERROR_##err, ':')+1, theextra?": ":"", theextra?theextra:"");   \
  lumiera_error_set(LUMIERA_ERROR_##err, theextra);                                                     \
  } while (0)

Helper macro to raise an error for the current thread.

Same as LUMIERA_ERROR_SET(), but logs at 'LOG_ALERT' level. Use this when the application is about to do a emergency shutdown.

Parameters

flag	NoBug flag describing the subsystem where the error was raised
err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extra	optional string (or NULL) which adds some more context to the error, can be a temporary

Definition at line 106 of file error.h.

Referenced by lumiera_lockerror_set().

◆ LUMIERA_ERROR_SET_CRITICAL

#define LUMIERA_ERROR_SET_CRITICAL	(	flag,
		err,
		extra
	)

Value:

do {                                                                                                  \
  const char* theextra = extra;                                                                         \
  CRITICAL (flag, "%s%s%s", strchr(LUMIERA_ERROR_##err, ':')+1, theextra?": ":"", theextra?theextra:"");\
  lumiera_error_set(LUMIERA_ERROR_##err, theextra);                                                     \
  } while (0)

Helper macro to raise an error for the current thread.

Same as LUMIERA_ERROR_SET(), but logs at 'LOG_CRIT' level. Use this when a requested task can not be completed (maybe user intervention is necessary).

Parameters

flag	NoBug flag describing the subsystem where the error was raised
err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extra	optional string (or NULL) which adds some more context to the error, can be a temporary

Definition at line 121 of file error.h.

Referenced by lumiera_lockerror_set().

◆ LUMIERA_ERROR_SET_WARNING

#define LUMIERA_ERROR_SET_WARNING	(	flag,
		err,
		extra
	)

Value:

do {                                                                                                  \
  const char* theextra = extra;                                                                         \
  WARN (flag, "%s%s%s", strchr(LUMIERA_ERROR_##err, ':')+1, theextra?": ":"", theextra?theextra:"");    \
  lumiera_error_set(LUMIERA_ERROR_##err, theextra);                                                     \
  } while (0)

Helper macro to raise an error for the current thread.

Same as LUMIERA_ERROR_SET(), but logs at 'LOG_WARNING' level. Use this when a not unexpected error happens which can be handled.

Parameters

flag	NoBug flag describing the subsystem where the error was raised
err	name of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extra	optional string (or NULL) which adds some more context to the error, can be a temporary

Definition at line 136 of file error.h.

Referenced by lumiera_lockerror_set().

Function Documentation

◆ lumiera_error_set()

lumiera_err lumiera_error_set	(	lumiera_err	nerr,
		const char *	extra
	)

Set error state for the current thread.

If the error state of the current thread was cleared, then set it, else preserve the old state.

Parameters

nerr	name of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
extra	a string (possibly a constructed tmpbuf) which adds some more context to the error, can be a temporary

Returns: old state, that is NULL for success, when the state was cleared and a pointer to a pending error when the error state was already set

Definition at line 105 of file error-state.c.

◆ lumiera_error_extra()

const char* lumiera_error_extra ( void )

Query the extra context for the last error.

Returns: the extra string from the last error

Definition at line 135 of file error-state.c.

Referenced by lumiera::error::detailInfo().

Here is the caller graph for this function:

◆ lumiera_error()

lumiera_err lumiera_error ( void )

Get and clear current error state.

This function clears the error state, if it needs to be reused, one has to store it in a temporary variable.

Returns: pointer to any pending error of this thread, NULL if no error is pending

Definition at line 124 of file error-state.c.

◆ lumiera_error_peek()

lumiera_err lumiera_error_peek ( void )

Check current error state without clearing it Please avoid this function and use lumiera_error() if possible.

Errors must be cleared else certain parts of the application refuse to cooperate with you. This shall only be used to decide if one wants to barf out of a loop or subroutine to deliver the error to a higher level.

Returns: pointer to any pending error of this thread, NULL if no error is pending

Definition at line 142 of file error-state.c.

Referenced by ExceptionError_test::checkErrorFlagPropagation(), and GuiSubsysDescriptor::checkRunningState().

Here is the caller graph for this function:

◆ lumiera_error_expect()

int lumiera_error_expect ( lumiera_err expected )

Expect some error Check that the current error state matches some expectation, if true then the error state is cleared and 1 is returned, otherwise 0 is returned and the error state remains set.

Parameters

expected error which is expected

Returns: 1 if the current error state equals the expected state, else 0, the error state is cleared when the expectation is met

Definition at line 148 of file error-state.c.

Description

Typedefs

Macros

Functions

Macro Definition Documentation

◆ LUMIERA_DIE

◆ LUMIERA_ERROR_DECLARE

◆ LUMIERA_ERROR_DEFINE

◆ LUMIERA_ERROR_SET

◆ LUMIERA_ERROR_SET_ALERT

◆ LUMIERA_ERROR_SET_CRITICAL

◆ LUMIERA_ERROR_SET_WARNING

Function Documentation

◆ lumiera_error_set()

◆ lumiera_error_extra()

◆ lumiera_error()

◆ lumiera_error_peek()

◆ lumiera_error_expect()