SpECTRE  2021.08.02
Classes | Macros | Functions
Error Handling

Classes

class  convergence_error
 Exception indicating convergence failure. More...
 

Macros

#define ASSERT(a, m)
 Assert that an expression should be true. More...
 
#define ERROR(m)
 prints an error message to the standard error stream and aborts the program. More...
 
#define CERROR(m)
 prints an error message to the standard error and aborts the program. More...
 
#define ERROR_NO_TRACE(m)
 Same as ERROR but does not print a backtrace. Intended to be used for user errors, such as incorrect values in an input file. More...
 
#define Expects(cond)
 check expectation of pre-conditions of a function More...
 
#define Ensures(cond)
 Check that a post-condition of a function is true. More...
 
#define DEBUG_STATIC_ASSERT(...)
 A static_assert that is only checked in Debug builds.
 

Functions

void abort_with_error_message (const char *expression, const char *file, int line, const char *pretty_function, const std::string &message)
 Compose an error message with an expression and a backtrace, then abort the program.
 
void abort_with_error_message (const char *file, int line, const char *pretty_function, const std::string &message)
 Compose an error message including a backtrace and abort the program.
 
void abort_with_error_message_no_trace (const char *file, int line, const char *pretty_function, const std::string &message)
 Compose an error message without a backtrace and abort the program.
 
void enable_floating_point_exceptions ()
 After a call to this function, the code will terminate with a floating point exception on overflow, divide-by-zero, and invalid operations.
 
void disable_floating_point_exceptions ()
 After a call to this function, the code will NOT terminate with a floating point exception on overflow, divide-by-zero, and invalid operations.
 
void sys::abort (const std::string &message)
 Abort the program with an error message. More...
 

Detailed Description

Macros and functions used for handling errors

Macro Definition Documentation

◆ ASSERT

#define ASSERT (   a,
  m 
)
Value:
do { \
if (false) { \
static_cast<void>(a); \
disable_floating_point_exceptions(); \
std::ostringstream avoid_name_collisions_ASSERT; \
/* clang-tidy: macro arg in parentheses */ \
avoid_name_collisions_ASSERT << m; /* NOLINT */ \
static_cast<void>(avoid_name_collisions_ASSERT); \
enable_floating_point_exceptions(); \
} \
} while (false)

Assert that an expression should be true.

If the preprocessor macro SPECTRE_DEBUG is defined and the expression is false, an error message is printed to the standard error stream, and the program aborts. ASSERT should be used to catch coding errors as it does nothing in production code.

Parameters
athe expression that must be true
mthe error message as an ostream

◆ CERROR

#define CERROR (   m)
Value:
do { \
breakpoint(); \
sys::abort("\n################ ERROR ################\nLine: "s + \
std::to_string(__LINE__) + " of file '"s + __FILE__ + "'\n"s + \
m + /* NOLINT */ \
"\n#######################################\n"s); \
} while (false)
sys::abort
void abort(const std::string &message)
Abort the program with an error message.

prints an error message to the standard error and aborts the program.

CERROR is just like ERROR and so the same guidelines apply. However, because it does not use std::stringstream it can be used in some constexpr functions where ERROR cannot be.

Parameters
merror message as a string, may need to use string literals

◆ Ensures

#define Ensures (   cond)
Value:
if (false) { \
static_cast<void>(cond); \
} else \
static_cast<void>(0)

Check that a post-condition of a function is true.

The Ensures macro sets the postconditions of function, it is a contract (C++20) that must be satisfied. See the CppCoreGuidelines for details.

Parameters
condthe expression that is expected to be true

◆ ERROR

#define ERROR (   m)
Value:
do { \
disable_floating_point_exceptions(); \
std::ostringstream avoid_name_collisions_ERROR; \
/* clang-tidy: macro arg in parentheses */ \
avoid_name_collisions_ERROR << m; /* NOLINT */ \
abort_with_error_message(__FILE__, __LINE__, \
static_cast<const char*>(__PRETTY_FUNCTION__), \
avoid_name_collisions_ERROR.str()); \
} while (false)

prints an error message to the standard error stream and aborts the program.

ERROR should not be used for coding errors, but instead for user errors or failure modes of numerical algorithms. An acceptable use for error is also in the default case of a switch statement.

Parameters
man arbitrary output stream.

◆ ERROR_NO_TRACE

#define ERROR_NO_TRACE (   m)
Value:
do { \
disable_floating_point_exceptions(); \
std::ostringstream avoid_name_collisions_ERROR; \
/* clang-tidy: macro arg in parentheses */ \
avoid_name_collisions_ERROR << m; /* NOLINT */ \
abort_with_error_message_no_trace( \
__FILE__, __LINE__, static_cast<const char*>(__PRETTY_FUNCTION__), \
avoid_name_collisions_ERROR.str()); \
} while (false)

Same as ERROR but does not print a backtrace. Intended to be used for user errors, such as incorrect values in an input file.

◆ Expects

#define Expects (   cond)
Value:
if (false) { \
static_cast<void>(cond); \
} else \
static_cast<void>(0)

check expectation of pre-conditions of a function

The Expects macro sets the preconditions to a function's arguments, it is a contract (C++20) that must be satisfied. See the CppCoreGuidelines for details.

Parameters
condthe expression that is expected to be true

Function Documentation

◆ abort()

void sys::abort ( const std::string &  message)

Abort the program with an error message.

Details

This function calls CkExit with a non-zero argument to indicate a failure, unless the SPECTRE_TRAP_ON_ERROR environmental variable is set, in which case it raises SIGTRAP.