SpECTRE  v2024.02.05
Error Handling

Classes

class  SpectreAssert
 Exception indicating an ASSERT failed. More...
 
class  SpectreError
 Exception indicating an ERROR was triggered. More...
 
class  SpectreFpe
 Exception indicating an ERROR was triggered because of an FPE. More...
 
class  convergence_error
 Exception indicating convergence failure. More...
 
class  ScopedFpeState
 An RAII object to temporarily modify the handling of floating point exceptions. 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 ERROR_AS(m, EXCEPTION_TYPE)
 Same as ERROR but will throw EXCEPTION_TYPE instead of SpectreError. 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(...)   static_assert(true)
 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. More...
 
template<typename ExceptionTypeToThrow >
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. More...
 
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. More...
 
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. More...
 
void enable_segfault_handler ()
 After a call to this function, the code will handle SIGSEGV segmentation faults by printing an error with a stacktrace.
 
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,
 
)
Value:
do { \
if (false) { \
static_cast<void>(a); \
const ScopedFpeState disable_fpes_ASSERT(false); \
std::ostringstream avoid_name_collisions_ASSERT; \
/* clang-tidy: macro arg in parentheses */ \
avoid_name_collisions_ASSERT << std::setprecision(18) << std::scientific \
<< m; /* NOLINT */ \
static_cast<void>(avoid_name_collisions_ASSERT); \
} \
} while (false)
An RAII object to temporarily modify the handling of floating point exceptions.
Definition: FloatingPointExceptions.hpp:38

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

◆ 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 { \
if (__builtin_is_constant_evaluated()) { \
throw std::runtime_error("Failed"); \
} else { \
Error_detail::abort_without_fpes<SpectreError>( \
__FILE__, __LINE__, static_cast<const char*>(__PRETTY_FUNCTION__), \
[&]() -> std::string { \
return MakeString{} << std::setprecision(18) << std::scientific \
<< m; \
}); \
} \
} while (false)
Make a string by streaming into object.
Definition: MakeString.hpp:18

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.

Details

The implementation is specialized so that in compile time contexts, a short error message will be thrown, but in runtime contexts, a more verbose error will be printed. This specialization of throwing a short error at compile time greatly reduces the compile time and memory consumption during debug builds of deep and heavily inlined TensorExpression tree traversals.

To accomplish this, __builtin_is_constant_evaluated() is used directly instead of calling a wrapper function because calling a wrapper was found to slightly increase the compile time and memory usage of large TensorExpressions when compiling in debug mode.

Parameters
man arbitrary output stream.

◆ ERROR_AS

#define ERROR_AS (   m,
  EXCEPTION_TYPE 
)
Value:
do { \
if (__builtin_is_constant_evaluated()) { \
throw std::runtime_error("Failed"); \
} else { \
Error_detail::abort_without_fpes<EXCEPTION_TYPE>( \
__FILE__, __LINE__, static_cast<const char*>(__PRETTY_FUNCTION__), \
[&]() -> std::string { \
return MakeString{} << std::setprecision(18) << std::scientific \
<< m; \
}); \
} \
} while (false)

Same as ERROR but will throw EXCEPTION_TYPE instead of SpectreError.

Note
Any exception types used must have an associated explicit instantiation in Utilities/ErrorHandling/AbortWithErrorMessage.cpp

◆ ERROR_NO_TRACE

#define ERROR_NO_TRACE (   m)
Value:
do { \
if (__builtin_is_constant_evaluated()) { \
throw std::runtime_error("Failed"); \
} else { \
const ScopedFpeState disable_fpes_ERROR(false); \
abort_with_error_message_no_trace( \
__FILE__, __LINE__, static_cast<const char*>(__PRETTY_FUNCTION__), \
MakeString{} << std::setprecision(18) << std::scientific << m); \
} \
} 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.

◆ abort_with_error_message() [1/2]

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.

We try to demangle and format the backtrace. Long symbol names are abbreviated, unless you set the SPECTRE_SHOW_FULL_BACKTRACE_SYMBOLS environment variable to a non-empty value (e.g. "1").

◆ abort_with_error_message() [2/2]

template<typename ExceptionTypeToThrow >
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.

We try to demangle and format the backtrace. Long symbol names are abbreviated, unless you set the SPECTRE_SHOW_FULL_BACKTRACE_SYMBOLS environment variable to a non-empty value (e.g. "1").

◆ abort_with_error_message_no_trace()

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.

Note
This always throws SpectreError as the exception type.

◆ disable_floating_point_exceptions()

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.

Warning
Do not use this function to temporarily disable FPEs, because it will not interact correctly with C++ exceptions. Use ScopedFpeState instead.