QPMS
Electromagnetic multiple scattering library and toolkit.
Macros | Enumerations | Functions | Variables
qpms_error.h File Reference

QPMS miscellanous internal error handling functions and macros. More...

#include "optim.h"
Include dependency graph for qpms_error.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define QPMS_WARN(msg, ...)   qpms_warn_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__)
 Print a warning to stderr and flush the buffer. More...
 
#define QPMS_WARN_ONCE(msg, ...)
 Print a warning to stderr and flush the buffer – only once per run (or current thread). More...
 
#define QPMS_DEBUG(type, msg, ...)   qpms_debug_at_flf(__FILE__,__LINE__,__func__,type,msg, ##__VA_ARGS__)
 Print a debugging message to stderr and flush the buffer. More...
 
#define QPMS_CRASHING_MALLOC(pointer, size)
 Wrapper macro of standard malloc(), crashing on failure. More...
 
#define QPMS_CRASHING_MALLOCPY(dest, src, size)
 Allocate and copy. More...
 
#define QPMS_CRASHING_CALLOC(pointer, nmemb, size)
 Wrapper macro of standard calloc(), crashing on failure. More...
 
#define QPMS_CRASHING_REALLOC(pointer, size)
 Wrapper macro of standard realloc(), crashing on failure. More...
 
#define QPMS_WTF   qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,"Unexpected error.")
 Prints an "unexpected error" message and aborts the program. More...
 
#define QPMS_INVALID_ENUM(x)   qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,"Invalid enum value (" #x " == %d)", (int) (x))
 Aborts the program with "invalid enumerator" error message.
 
#define QPMS_UNTESTED
 Prints an "untested function/feature" warning once when reached in the code. More...
 
#define QPMS_PR_ERROR(msg, ...)   qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__)
 Prints a given error message and aborts the program. More...
 
#define QPMS_ENSURE_SUCCESS(x)
 Raises an error if x is not zero. More...
 
#define QPMS_ENSURE_SUCCESS_M(x, msg, ...)
 Raises an error if x is not zero, with custom error message. More...
 
#define QPMS_ENSURE_SUCCESS_OR(x, ...)
 Raises an error if x is not zero or one of the values listed in arguments. More...
 
#define QPMS_ENSURE(x, msg, ...)   {if(QPMS_UNLIKELY(!(x))) qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__); }
 Raises an error if x is not true, with custom error message.
 
#define QPMS_ASSERT(x)
 Raises an error if x is false. More...
 
#define QPMS_PARANOID_ASSERT(x)   {;}
 
#define QPMS_NOT_IMPLEMENTED(msg, ...)
 Raises a "not implemented" error with additional custom message. More...
 
#define QPMS_INCOMPLETE_IMPLEMENTATION(msg, ...)
 Prints an "incomplete implementation" warning once with a custom message. More...
 

Enumerations

enum  qpms_dbgmsg_flags { QPMS_DBGMSG_MISC = 1 , QPMS_DBGMSG_THREADS = 2 , QPMS_DBGMSG_INTEGRATION = 4 }
 Classification of debugging messages. More...
 

Functions

QPMS_NORETURN void qpms_pr_error (const char *fmt,...)
 Print error message and abort();.
 
QPMS_NORETURN void qpms_pr_error_at_flf (const char *filename, unsigned int linenum, const char *func, const char *fmt,...)
 Print an error message, indicating source, function name and line number, and abort(). More...
 
void qpms_warn_at_flf (const char *filename, unsigned int linenum, const char *func, const char *fmt,...)
 Print a warning message to stderr and flush the buffer. Don't call this directly, use QPMS_WARN().
 
void qpms_debug_at_flf (const char *filename, unsigned int linenum, const char *func, qpms_dbgmsg_flags type, const char *fmt,...)
 Print a debugging message to stderr and flush the buffer. Don't call this directly, use QPMS_DEBUG().
 
qpms_dbgmsg_flags qpms_dbgmsg_disable (qpms_dbgmsg_flags types)
 Enable debugging messages of given types. More...
 
qpms_dbgmsg_flags qpms_dbgmsg_enable (qpms_dbgmsg_flags types)
 Disable debugging messages of given types. More...
 

Variables

qpms_dbgmsg_flags qpms_dbgmsg_enabled
 Global variable determining which types of debug messages shall be printed with QPMS_DEBUG(). More...
 

Detailed Description

QPMS miscellanous internal error handling functions and macros.

Macro Definition Documentation

◆ QPMS_ASSERT

#define QPMS_ASSERT (   x)
Value:
{\
if(QPMS_UNLIKELY(!(x)))\
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,\
"Unexpected error. This is most certainly a bug.");\
}

Raises an error if x is false.

Currently, this is always expanded, ignoring the possible NDEBUG macro. In places where the evaluation could have significant performance impact, consider using QPMS_PARANOID_ASSERT() instead.

◆ QPMS_CRASHING_CALLOC

#define QPMS_CRASHING_CALLOC (   pointer,
  nmemb,
  size 
)
Value:
{\
(pointer) = calloc((nmemb), (size));\
if(QPMS_UNLIKELY(!(pointer) && (nmemb) && (size)))\
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,\
"Allocation of %zd bytes for " #pointer " failed.",\
(size_t)((nmemb)*(size)));\
}

Wrapper macro of standard calloc(), crashing on failure.

Normally corresponds to a pointer = calloc(nmemb, size) statement; however, if NULL is returned, this prints an error message and abort()s the program.

The arguments are expanded several times.

Note that this macro expands to a code block, to be kept in mind when using together with if/else etc.

Assigned memory block is to be deallocated with standard free().

See also
QPMS_CRASHING_MALLOC, QPMS_CRASHING_REALLOC.

◆ QPMS_CRASHING_MALLOC

#define QPMS_CRASHING_MALLOC (   pointer,
  size 
)
Value:
{\
(pointer) = malloc(size);\
if(QPMS_UNLIKELY(!(pointer) && (size)))\
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,\
"Allocation of %zd bytes for " #pointer " failed.",\
(size_t) (size));\
}

Wrapper macro of standard malloc(), crashing on failure.

Normally corresponds to a pointer = malloc(size) statement; however, if NULL is returned, this prints an error message and abort()s the program.

The arguments are expanded several times.

Note that this macro expands to a code block, to be kept in mind when using together with if/else etc.

Assigned memory block is to be deallocated with standard free().

See also
QPMS_CRASHING_CALLOC.

◆ QPMS_CRASHING_MALLOCPY

#define QPMS_CRASHING_MALLOCPY (   dest,
  src,
  size 
)
Value:
{\
(dest) = malloc(size);\
if(QPMS_UNLIKELY(!(dest) && (size)))\
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,\
"Allocation of %zd bytes for " #dest " failed.",\
(size_t) (size));\
memcpy((dest), (src), (size));\
}

Allocate and copy.

Behaves as QPMS_CRASHING_MALLOC(dest, size), but additionaly copies a chunk of memory from src to dest.

See also
QPMS_CRASHING_MALLOC()

◆ QPMS_CRASHING_REALLOC

#define QPMS_CRASHING_REALLOC (   pointer,
  size 
)
Value:
{\
(pointer) = realloc((pointer), size);\
if(QPMS_UNLIKELY(!(pointer) && (size)))\
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,\
"Rellocation of %zd bytes for " #pointer " failed.",\
(size_t) (size));\
}

Wrapper macro of standard realloc(), crashing on failure.

Normally corresponds to a pointer = realloc(pointer, size) statement; however, if NULL is returned, this prints an error message and abort()s the program.

The arguments are expanded several times.

Note that this macro expands to a code block, to be kept in mind when using together with if/else etc.

Assigned memory block is to be deallocated with standard free().

See also
QPMS_CRASHING_MALLOC.

◆ QPMS_DEBUG

#define QPMS_DEBUG (   type,
  msg,
  ... 
)    qpms_debug_at_flf(__FILE__,__LINE__,__func__,type,msg, ##__VA_ARGS__)

Print a debugging message to stderr and flush the buffer.

The arguments after type are the same as in standard printf().

The debugging message is printed only if the corresponding type flag is set in qpms_dbgmsg_enabled.

See also
qpms_dbgmsg_enabled < Debugging message type flag, see qpms_dbgmsg_flags

◆ QPMS_ENSURE_SUCCESS

#define QPMS_ENSURE_SUCCESS (   x)
Value:
{ \
int errorcode = (x); /* evaluate x only once */ \
if(QPMS_UNLIKELY(errorcode)) \
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,"Unexpected error (%d)", errorcode); \
}

Raises an error if x is not zero.

◆ QPMS_ENSURE_SUCCESS_M

#define QPMS_ENSURE_SUCCESS_M (   x,
  msg,
  ... 
)
Value:
{ \
int errorcode = (x); \
if(QPMS_UNLIKELY(errorcode)) \
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__); \
}

Raises an error if x is not zero, with custom error message.

◆ QPMS_ENSURE_SUCCESS_OR

#define QPMS_ENSURE_SUCCESS_OR (   x,
  ... 
)
Value:
{ \
int errorcode = (x); /* evaluate x only once */ \
static const int allowed_errorcodes[] = {0, ##__VA_ARGS__};\
static const int n_allowed = sizeof(allowed_errorcodes) / sizeof(int); \
int i; \
for(i = 0; i < n_allowed; ++i) \
if (errorcode == allowed_errorcodes[i]) break; \
if (QPMS_UNLIKELY(i >= n_allowed)) \
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,"Unexpected error (%d)", errorcode); \
}

Raises an error if x is not zero or one of the values listed in arguments.

◆ QPMS_INCOMPLETE_IMPLEMENTATION

#define QPMS_INCOMPLETE_IMPLEMENTATION (   msg,
  ... 
)
Value:
{\
static _Bool already_bitched = 0; \
if (QPMS_UNLIKELY(!already_bitched)) {\
qpms_warn_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__);\
already_bitched = 1;\
}\
}

Prints an "incomplete implementation" warning once with a custom message.

Serves mainly as a label/placeholder of incomplete parts of the code.

◆ QPMS_NOT_IMPLEMENTED

#define QPMS_NOT_IMPLEMENTED (   msg,
  ... 
)
Value:
qpms_pr_error_at_flf(__FILE__,__LINE__,__func__, \
"Not implemented:" msg, ##__VA_ARGS__)
QPMS_NORETURN void qpms_pr_error_at_flf(const char *filename, unsigned int linenum, const char *func, const char *fmt,...)
Print an error message, indicating source, function name and line number, and abort().
Definition: error.c:43

Raises a "not implemented" error with additional custom message.

Serves also as a label/placeholder of not implemented parts of the code.

◆ QPMS_PR_ERROR

#define QPMS_PR_ERROR (   msg,
  ... 
)    qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__)

Prints a given error message and aborts the program.

The arguments are as in standard printf().

◆ QPMS_UNTESTED

#define QPMS_UNTESTED
Value:
{\
static _Bool already_bitched = 0; \
if (QPMS_UNLIKELY(!already_bitched)) {\
qpms_warn_at_flf(__FILE__,__LINE__,__func__,"Warning: untested function/feature!");\
already_bitched = 1;\
}\
}

Prints an "untested function/feature" warning once when reached in the code.

◆ QPMS_WARN

#define QPMS_WARN (   msg,
  ... 
)    qpms_warn_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__)

Print a warning to stderr and flush the buffer.

The arguments are the same as in standard printf().

◆ QPMS_WARN_ONCE

#define QPMS_WARN_ONCE (   msg,
  ... 
)
Value:
{\
static _Bool already_bitched = 0; \
if (QPMS_UNLIKELY(!already_bitched)) {\
qpms_warn_at_flf(__FILE__,__LINE__,__func__,msg, ##__VA_ARGS__);\
already_bitched = 1;\
}\
}

Print a warning to stderr and flush the buffer – only once per run (or current thread).

The arguments are the same as in standard printf().

◆ QPMS_WTF

#define QPMS_WTF   qpms_pr_error_at_flf(__FILE__,__LINE__,__func__,"Unexpected error.")

Prints an "unexpected error" message and aborts the program.

Usually only put to presumably unreachable places in the code and similar.

Enumeration Type Documentation

◆ qpms_dbgmsg_flags

Classification of debugging messages.

See also
qpms_dbgmsg_enabled, qpms_dbgmsg_enable(), qpms_dbgmsg_disable()
Enumerator
QPMS_DBGMSG_THREADS 

Multithreading-related debug messages.

QPMS_DBGMSG_INTEGRATION 

Quadrature-related debug messages.

Function Documentation

◆ qpms_dbgmsg_disable()

qpms_dbgmsg_flags qpms_dbgmsg_disable ( qpms_dbgmsg_flags  types)

Enable debugging messages of given types.

See also
qpms_dbgmsg_disable()

◆ qpms_dbgmsg_enable()

qpms_dbgmsg_flags qpms_dbgmsg_enable ( qpms_dbgmsg_flags  types)

Disable debugging messages of given types.

See also
qpms_dbgmsg_enable()

◆ qpms_pr_error_at_flf()

QPMS_NORETURN void qpms_pr_error_at_flf ( const char *  filename,
unsigned int  linenum,
const char *  func,
const char *  fmt,
  ... 
)

Print an error message, indicating source, function name and line number, and abort().

Usually not used directly, but rather via some of the macros that fill the first arguments automatically.

See also
QPMS_PR_ERROR

Variable Documentation

◆ qpms_dbgmsg_enabled

qpms_dbgmsg_flags qpms_dbgmsg_enabled
extern

Global variable determining which types of debug messages shall be printed with QPMS_DEBUG().

Use qpms_dbgmsg_enable() and qpms_dbgmsg_disable() to manipulate this variable.

See also
QPMS_DEBUG()