Lumiera  0.pre.03
»edit your freedom«
error.h File Reference

Go to the source code of this file.

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
errname 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
errname of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
msgmessage 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
flagNoBug flag describing the subsystem where the error was raised
errname of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extraoptional 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
flagNoBug flag describing the subsystem where the error was raised
errname of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extraoptional 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
flagNoBug flag describing the subsystem where the error was raised
errname of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extraoptional 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
flagNoBug flag describing the subsystem where the error was raised
errname of the error without the 'LUMIERA_ERROR_' prefix (example: NO_MEMORY)
extraoptional 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
nerrname of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
extraa 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
expectederror 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.