Reference documentation for deal.II version GIT relicensing-769-g16d39143b0 2024-05-28 17:50:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Loading...
Searching...
No Matches
Classes | Namespaces | Macros | Typedefs | Enumerations | Functions | Variables
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>
#include <cusolverSp.h>
#include <cusparse.h>

Go to the source code of this file.

Classes

class  ExceptionBase
 
class  StandardExceptions::ExcMPI
 
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 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 AssertCuda(error_code)
 
#define AssertNothrowCuda(error_code)
 
#define AssertCudaKernel()
 
#define AssertCusparse(error_code)
 
#define AssertNothrowCusparse(error_code)
 
#define AssertCusolver(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 ::ExceptionBaseStandardExceptions::ExcDivideByZero ()
 
static ::ExceptionBaseStandardExceptions::ExcNumberNotFinite (std::complex< double > arg1)
 
static ::ExceptionBaseStandardExceptions::ExcOutOfMemory (std::size_t arg1)
 
static ::ExceptionBaseStandardExceptions::ExcMemoryLeak (int arg1)
 
static ::ExceptionBaseStandardExceptions::ExcIO ()
 
static ::ExceptionBaseStandardExceptions::ExcFileNotOpen (std::string arg1)
 
static ::ExceptionBaseStandardExceptions::ExcNotImplemented ()
 
static ::ExceptionBaseStandardExceptions::ExcInternalError ()
 
static ::ExceptionBaseStandardExceptions::ExcPureFunctionCalled ()
 
static ::ExceptionBaseStandardExceptions::ExcFunctionNotProvided (std::string arg1)
 
static ::ExceptionBaseStandardExceptions::ExcFunctionNonzeroReturn (std::string arg1, int arg2)
 
static ::ExceptionBaseStandardExceptions::ExcNotInitialized ()
 
static ::ExceptionBaseStandardExceptions::ExcInvalidState ()
 
static ::ExceptionBaseStandardExceptions::ExcImpossibleInDim (int arg1)
 
static ::ExceptionBaseStandardExceptions::ExcImpossibleInDimSpacedim (int arg1, int arg2)
 
static ::ExceptionBaseStandardExceptions::ExcZero ()
 
static ::ExceptionBaseStandardExceptions::ExcEmptyObject ()
 
static ::ExceptionBaseStandardExceptions::ExcDimensionMismatch (std::size_t arg1, std::size_t arg2)
 
static ::ExceptionBaseStandardExceptions::ExcDimensionMismatch2 (std::size_t arg1, std::size_t arg2, std::size_t arg3)
 
static ::ExceptionBaseStandardExceptions::ExcIndexRange (std::size_t arg1, std::size_t arg2, std::size_t arg3)
 
template<typename T >
static ::ExceptionBaseStandardExceptions::ExcIndexRangeType (T arg1, T arg2, T arg3)
 
static ::ExceptionBaseStandardExceptions::ExcLowerRange (int arg1, int arg2)
 
template<typename T >
static ::ExceptionBaseStandardExceptions::ExcLowerRangeType (T arg1, T arg2)
 
static ::ExceptionBaseStandardExceptions::ExcNotMultiple (int arg1, int arg2)
 
static ::ExceptionBaseStandardExceptions::ExcInvalidIterator ()
 
static ::ExceptionBaseStandardExceptions::ExcIteratorPastEnd ()
 
static ::ExceptionBaseStandardExceptions::ExcMessage (std::string arg1)
 
static ::ExceptionBaseStandardExceptions::ExcGhostsPresent ()
 
static ::ExceptionBaseStandardExceptions::ExcGridHasInvalidCell (int arg1)
 
static ::ExceptionBaseStandardExceptions::ExcScalarAssignmentOnlyForZeroValue ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsLAPACK ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsHDF5 ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsMPI ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsFunctionparser ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsAssimp ()
 
static ::ExceptionBaseStandardExceptions::ExcCudaError (const char *arg1)
 
static ::ExceptionBaseStandardExceptions::ExcCusparseError (std::string arg1)
 
static ::ExceptionBaseStandardExceptions::ExcNeedsExodusII ()
 
static ::ExceptionBaseStandardExceptions::ExcNeedsCGAL ()
 
static ::ExceptionBaseStandardExceptions::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
 
std::string deal_II_exceptions::internals::get_cusparse_error_string (const cusparseStatus_t error_code)
 
std::string deal_II_exceptions::internals::get_cusolver_error_string (const cusolverStatus_t error_code)
 
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:
abort_or_throw_on_exception, \
__FILE__, \
__LINE__, \
__PRETTY_FUNCTION__, \
nullptr, \
nullptr, \
static ::ExceptionBase & ExcNotImplemented()
void issue_error_noreturn(ExceptionHandling handling, const char *file, int line, const char *function, const char *cond, const char *exc_name, ExceptionType e)

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
}
Definition point.h:111
#define DEAL_II_NOT_IMPLEMENTED()
::VectorizedArray< Number, width > sin(const ::VectorizedArray< Number, width > &)

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 1814 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!
}
#define 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 1897 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 2089 of file exceptions.h.