exceptions.h File Reference

#include <deal.II/base/config.h>
#include <Kokkos_Macros.hpp>
#include <Kokkos_Core.hpp>
#include <exception>
#include <ostream>
#include <string>
#include <type_traits>

Go to the source code of this file.

Classes
class	ExceptionBase
class	StandardExceptions::ExcMPI
class	StandardExceptions::ExcExodusII
struct	internal::argument_type< T(U)>

Namespaces
namespace	StandardExceptions
namespace	deal_II_exceptions
namespace	deal_II_exceptions::internals
namespace	internal

Macros
#define	DeclException0(Exception0)
#define	DeclExceptionMsg(Exception, defaulttext)
#define	DeclException1(Exception1, type1, outsequence)
#define	DeclException2(Exception2, type1, type2, outsequence)
#define	DeclException3(Exception3, type1, type2, type3, outsequence)
#define	DeclException4(Exception4, type1, type2, type3, type4, outsequence)
#define	DeclException5( Exception5, type1, type2, type3, type4, type5, outsequence)
#define	Assert(cond, exc)
#define	AssertNothrow(cond, exc)
#define	AssertThrow(cond, exc)
#define	DEAL_II_NOT_IMPLEMENTED()
#define	DEAL_II_ASSERT_UNREACHABLE()
#define	AssertDimension(dim1, dim2)
#define	AssertIntegerConversion(index1, index2)
#define	AssertThrowIntegerConversion(index1, index2)
#define	AssertVectorVectorDimension(VEC, DIM1, DIM2)
#define	AssertIndexRange(index, range)
#define	AssertIsFinite(number)
#define	AssertIsNotUsed(obj)   Assert((obj)->used() == false, ExcInternalError())
#define	AssertThrowMPI(error_code)    AssertThrow(error_code == MPI_SUCCESS, ::ExcMPI(error_code))
#define	AssertThrowExodusII(error_code)

Typedefs
template<typename F >
using	internal::argument_type_t = typename argument_type< F >::type

Enumerations
enum class	deal_II_exceptions::internals::ExceptionHandling { deal_II_exceptions::internals::abort_or_throw_on_exception , deal_II_exceptions::internals::throw_on_exception }

Functions
static ::ExceptionBase &	StandardExceptions::ExcDivideByZero ()
static ::ExceptionBase &	StandardExceptions::ExcNumberNotFinite (std::complex< double > arg1)
static ::ExceptionBase &	StandardExceptions::ExcOutOfMemory (std::size_t arg1)
static ::ExceptionBase &	StandardExceptions::ExcMemoryLeak (int arg1)
static ::ExceptionBase &	StandardExceptions::ExcIO ()
static ::ExceptionBase &	StandardExceptions::ExcFileNotOpen (std::string arg1)
static ::ExceptionBase &	StandardExceptions::ExcNotImplemented ()
static ::ExceptionBase &	StandardExceptions::ExcInternalError ()
static ::ExceptionBase &	StandardExceptions::ExcPureFunctionCalled ()
static ::ExceptionBase &	StandardExceptions::ExcFunctionNotProvided (std::string arg1)
static ::ExceptionBase &	StandardExceptions::ExcFunctionNonzeroReturn (std::string arg1, int arg2)
static ::ExceptionBase &	StandardExceptions::ExcNotInitialized ()
static ::ExceptionBase &	StandardExceptions::ExcInvalidState ()
static ::ExceptionBase &	StandardExceptions::ExcImpossibleInDim (int arg1)
static ::ExceptionBase &	StandardExceptions::ExcImpossibleInDimSpacedim (int arg1, int arg2)
static ::ExceptionBase &	StandardExceptions::ExcZero ()
static ::ExceptionBase &	StandardExceptions::ExcEmptyObject ()
static ::ExceptionBase &	StandardExceptions::ExcDimensionMismatch (std::size_t arg1, std::size_t arg2)
static ::ExceptionBase &	StandardExceptions::ExcInvalidIntegerConversion (long long arg1, long long arg2)
static ::ExceptionBase &	StandardExceptions::ExcDimensionMismatch2 (std::size_t arg1, std::size_t arg2, std::size_t arg3)
static ::ExceptionBase &	StandardExceptions::ExcIndexRange (std::size_t arg1, std::size_t arg2, std::size_t arg3)
template<typename T >
static ::ExceptionBase &	StandardExceptions::ExcIndexRangeType (T arg1, T arg2, T arg3)
static ::ExceptionBase &	StandardExceptions::ExcLowerRange (int arg1, int arg2)
template<typename T >
static ::ExceptionBase &	StandardExceptions::ExcLowerRangeType (T arg1, T arg2)
static ::ExceptionBase &	StandardExceptions::ExcNotMultiple (int arg1, int arg2)
static ::ExceptionBase &	StandardExceptions::ExcInvalidIterator ()
static ::ExceptionBase &	StandardExceptions::ExcIteratorPastEnd ()
static ::ExceptionBase &	StandardExceptions::ExcMessage (std::string arg1)
static ::ExceptionBase &	StandardExceptions::ExcGhostsPresent ()
static ::ExceptionBase &	StandardExceptions::ExcGridHasInvalidCell (int arg1)
static ::ExceptionBase &	StandardExceptions::ExcScalarAssignmentOnlyForZeroValue ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsLAPACK ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsHDF5 ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsMPI ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsFunctionparser ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsAssimp ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsExodusII ()
static ::ExceptionBase &	StandardExceptions::ExcNeedsCGAL ()
static ::ExceptionBase &	StandardExceptions::RecoverableUserCallbackError ()
void	deal_II_exceptions::set_additional_assert_output (const char *const p)
void	deal_II_exceptions::suppress_stacktrace_in_exceptions ()
void	deal_II_exceptions::disable_abort_on_exception ()
void	deal_II_exceptions::enable_abort_on_exception ()
void	deal_II_exceptions::internals::abort (const ExceptionBase &exc) noexcept
template<typename ExceptionType >
void	deal_II_exceptions::internals::issue_error_noreturn (ExceptionHandling handling, const char *file, int line, const char *function, const char *cond, const char *exc_name, ExceptionType e)
void	deal_II_exceptions::internals::do_issue_error_nothrow (const ExceptionBase &e) noexcept
template<typename ExceptionType >
void	deal_II_exceptions::internals::issue_error_nothrow (const char *file, int line, const char *function, const char *cond, const char *exc_name, ExceptionType e) noexcept
template<typename T , typename U >
constexpr bool	deal_II_exceptions::internals::compare_for_equality (const T &t, const U &u)
template<typename T , typename U >
constexpr bool	deal_II_exceptions::internals::compare_less_than (const T &t, const U &u)

Variables
bool	deal_II_exceptions::internals::allow_abort_on_exception = true

Macro Definition Documentation

DEAL_II_NOT_IMPLEMENTED

#define DEAL_II_NOT_IMPLEMENTED

(

)

Value:

  ::deal_II_exceptions::internals::issue_error_noreturn(         \
    ::deal_II_exceptions::internals::ExceptionHandling::         \
      abort_or_throw_on_exception,                               \
    __FILE__,                                                    \
    __LINE__,                                                    \
    __PRETTY_FUNCTION__,                                         \
    nullptr,                                                     \
    nullptr,                                                     \
    ::StandardExceptions::ExcNotImplemented())

DEAL_II_NOT_IMPLEMENTED is a macro (that looks like a function call when used as in DEAL_II_NOT_IMPLEMENTED();) that is used to raise an error in places where a piece of code is not yet implemented. If a code runs into such a place, it will be aborted with an error message that explains the situation, along with a backtrace of how the code ended up in this place. Alternatively, if deal_II_exceptions::internals::ExceptionHandling::abort_or_throw_on_exception is set to ExceptionHandling::throw_on_exception, then the corresponding error is thrown as a C++ exception that can be caught (though in many cases codes will then find it difficult to do what they wanted to do).

This macro is first used in step-8 of the tutorial.

A typical case where it is used would look as follows: Assume that we want to implement a function that describes the right hand side of an equation that corresponds to a known solution (i.e., we want to use the "Method of manufactured solutions", see step-7). We have computed the right hand side that corresponds to the 1d and 2d solutions, but we have been too lazy so far to do the calculations for the 3d case, perhaps because we first want to test correctness in 1d and 2d before moving on to the 3d case. We could then write this right hand side as follows (the specific formulas in the return statements are not important):

template <int dim>
double right_hand_side (const Point<dim> &x)
{
  if (dim==1)
    return x[0]*std::sin(x[0]);
  else if (dim==2)
    return x[0]*std::sin(x[0])*std::sin(x[1];
  else
    DEAL_II_NOT_IMPLEMENTED();
}

Here, the call to DEAL_II_NOT_IMPLEMENTED() simply indicates that we haven't gotten around to filling in this code block. If someone ends up running the program in 3d, execution will abort in the location with an error message that indicates where this happened and why.

Definition at line 1855 of file exceptions.h.

DEAL_II_ASSERT_UNREACHABLE

#define DEAL_II_ASSERT_UNREACHABLE

(

)

DEAL_II_ASSERT_UNREACHABLE is a macro (that looks like a function call when used as in DEAL_II_ASSERT_UNREACHABLE();) that is used to raise an error in places where the programmer believed that execution should never get to. If a code runs into such a place, it will be aborted with an error message that explains the situation, along with a backtrace of how the code ended up in this place. Alternatively, if deal_II_exceptions::internals::ExceptionHandling::abort_or_throw_on_exception is set to ExceptionHandling::throw_on_exception, then the corresponding error is thrown as a C++ exception that can be caught (though in many cases codes will then find it difficult to do what they wanted to do).

A typical case where it is used would look as follows. In many cases, one has a finite enumeration of things that can happen, and one runs through those in a sequence of if-else blocks, or perhaps with a switch selection and a number of case statements. Of course, if the code is correct, if all possible cases are handled, nothing terrible can happen – though perhaps it is worth making sure that we have really covered all cases by using DEAL_II_ASSERT_UNREACHABLE() as the last case. Here is an example:

enum OutputFormat { vtk, vtu };
 
void write_output (const OutputFormat format)
{
  if (format == vtk)
    {
      ... write in VTK format ...
    }
  else // must not clearly be VTU format
    {
      ... write in VTU format ...
    }
}

The issue here is "Are we really sure it is VTU format if we end up in the `else` block"? There are two reasons that should make us suspicious. First, the authors of the code may later have expanded the list of options in the OutputFormat enum, but forgotten to also update the write_output() function. We may then end up in the else branch even though the argument indicates the now possible third option that was added to OutputFormat. The second possibility to consider is that enums are really just fancy ways of using integers; from a language perspective, it is allowed to pass any integer to write_output(), even values that do not match either vtk or vtu. This is then clearly a bug in the program, but one that we are better off if we catch it as early as possible.

We can guard against both cases by writing the code as follows instead:

enum OutputFormat { vtk, vtu };
 
void write_output (const OutputFormat format)
{
  if (format == vtk)
    {
      ... write in VTK format ...
    }
  else if (format == vtu)
    {
      ... write in VTU format ...
    }
  else // we shouldn't get here, but if we did, abort the program now!
    DEAL_II_ASSERT_UNREACHABLE();
}

This macro is first used in step-7, where we show another example of a context where it is frequently used.

Definition at line 1938 of file exceptions.h.

AssertIntegerConversion

#define AssertIntegerConversion	(		index1,
			index2
	)

Value:

  Assert(::deal_II_exceptions::internals::compare_for_equality( \
           index1, index2),                                             \
         ::ExcInvalidIntegerConversion((index1), (index2)))

Special assertion for integer conversions.

deal.II does not always use the same integer types as its dependencies. For example, PETSc uses signed integers whereas deal.II uses unsigned integers. This assertion checks that we can successfully convert between two index types.

Definition at line 2039 of file exceptions.h.

AssertThrowIntegerConversion

#define AssertThrowIntegerConversion	(		index1,
			index2
	)

Value:

  AssertThrow(::deal_II_exceptions::internals::compare_for_equality( \
                index1, index2),                                             \
              ::ExcInvalidIntegerConversion((index1), (index2)))

Special assertion for integer conversions which will throw exceptions. Otherwise this is the same as AssertIntegerConversion.

Definition at line 2048 of file exceptions.h.

AssertIsNotUsed

#define AssertIsNotUsed

(

obj

)

Assert((obj)->used() == false, ExcInternalError())

Assert that a geometric object is not used. This assertion is used when constructing triangulations and should normally not be used inside user codes.

Definition at line 2151 of file exceptions.h.