deal.II version GIT relicensing-1931-g88c382288c 2024-10-04 03:40:00+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
exceptions.h
Go to the documentation of this file.
1// ------------------------------------------------------------------------
2//
3// SPDX-License-Identifier: LGPL-2.1-or-later
4// Copyright (C) 1998 - 2024 by the deal.II authors
5//
6// This file is part of the deal.II library.
7//
8// Part of the source code is dual licensed under Apache-2.0 WITH
9// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10// governing the source code and code contributions can be found in
11// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12//
13// ------------------------------------------------------------------------
14
15#ifndef dealii_exceptions_h
16#define dealii_exceptions_h
17
18#include <deal.II/base/config.h>
19
20DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
21#include <Kokkos_Macros.hpp>
22#if KOKKOS_VERSION >= 40200
23# include <Kokkos_Abort.hpp>
24#else
25# include <Kokkos_Core.hpp>
26#endif
27DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
28
29#include <exception>
30#include <ostream>
31#include <string>
32#include <type_traits>
33
34DEAL_II_NAMESPACE_OPEN
35
36
50class ExceptionBase : public std::exception
51{
52public:
56 ExceptionBase();
57
61 ExceptionBase(const ExceptionBase &exc);
62
66 virtual ~ExceptionBase() noexcept override = default;
67
72 ExceptionBase
73 operator=(const ExceptionBase &) = delete;
74
80 void
81 set_fields(const char *file,
82 const int line,
83 const char *function,
84 const char *cond,
85 const char *exc_name);
86
87
91 virtual const char *
92 what() const noexcept override;
93
97 const char *
98 get_exc_name() const;
99
103 void
104 print_exc_data(std::ostream &out) const;
105
110 virtual void
111 print_info(std::ostream &out) const;
112
117 void
118 print_stack_trace(std::ostream &out) const;
119
120protected:
124 const char *file;
125
129 unsigned int line;
130
134 const char *function;
135
139 const char *cond;
140
144 const char *exc;
145
150 int n_stacktrace_frames;
151
152#ifdef DEAL_II_HAVE_GLIBC_STACKTRACE
156 void *raw_stacktrace[25];
157#endif
158
159private:
163 void
164 generate_message() const;
165
170 mutable std::string what_str;
171};
172
173#ifndef DOXYGEN
174
191# define DeclException0(Exception0) \
192 class Exception0 : public ::ExceptionBase \
193 {}
194
195
215# define DeclExceptionMsg(Exception, defaulttext) \
216 class Exception : public ::ExceptionBase \
217 { \
218 public: \
219 Exception(const std::string &msg = defaulttext) \
220 : arg(msg) \
221 {} \
222 virtual ~Exception() noexcept \
223 {} \
224 virtual void \
225 print_info(std::ostream &out) const override \
226 { \
227 out << " " << arg << std::endl; \
228 } \
229 \
230 private: \
231 const std::string arg; \
232 }
233
251# define DeclException1(Exception1, type1, outsequence) \
252 class Exception1 : public ::ExceptionBase \
253 { \
254 public: \
255 Exception1(type1 const &a1) \
256 : arg1(a1) \
257 {} \
258 virtual ~Exception1() noexcept \
259 {} \
260 virtual void \
261 print_info(std::ostream &out) const override \
262 { \
263 out << " " outsequence << std::endl; \
264 } \
265 \
266 private: \
267 type1 const arg1; \
268 }
269
270
288# define DeclException2(Exception2, type1, type2, outsequence) \
289 class Exception2 : public ::ExceptionBase \
290 { \
291 public: \
292 Exception2(type1 const &a1, type2 const &a2) \
293 : arg1(a1) \
294 , arg2(a2) \
295 {} \
296 virtual ~Exception2() noexcept \
297 {} \
298 virtual void \
299 print_info(std::ostream &out) const override \
300 { \
301 out << " " outsequence << std::endl; \
302 } \
303 \
304 private: \
305 type1 const arg1; \
306 type2 const arg2; \
307 }
308
309
327# define DeclException3(Exception3, type1, type2, type3, outsequence) \
328 class Exception3 : public ::ExceptionBase \
329 { \
330 public: \
331 Exception3(type1 const &a1, type2 const &a2, type3 const &a3) \
332 : arg1(a1) \
333 , arg2(a2) \
334 , arg3(a3) \
335 {} \
336 virtual ~Exception3() noexcept \
337 {} \
338 virtual void \
339 print_info(std::ostream &out) const override \
340 { \
341 out << " " outsequence << std::endl; \
342 } \
343 \
344 private: \
345 type1 const arg1; \
346 type2 const arg2; \
347 type3 const arg3; \
348 }
349
350
368# define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
369 class Exception4 : public ::ExceptionBase \
370 { \
371 public: \
372 Exception4(type1 const &a1, \
373 type2 const &a2, \
374 type3 const &a3, \
375 type4 const &a4) \
376 : arg1(a1) \
377 , arg2(a2) \
378 , arg3(a3) \
379 , arg4(a4) \
380 {} \
381 virtual ~Exception4() noexcept \
382 {} \
383 virtual void \
384 print_info(std::ostream &out) const override \
385 { \
386 out << " " outsequence << std::endl; \
387 } \
388 \
389 private: \
390 type1 const arg1; \
391 type2 const arg2; \
392 type3 const arg3; \
393 type4 const arg4; \
394 }
395
396
414# define DeclException5( \
415 Exception5, type1, type2, type3, type4, type5, outsequence) \
416 class Exception5 : public ::ExceptionBase \
417 { \
418 public: \
419 Exception5(type1 const &a1, \
420 type2 const &a2, \
421 type3 const &a3, \
422 type4 const &a4, \
423 type5 const &a5) \
424 : arg1(a1) \
425 , arg2(a2) \
426 , arg3(a3) \
427 , arg4(a4) \
428 , arg5(a5) \
429 {} \
430 virtual ~Exception5() noexcept \
431 {} \
432 virtual void \
433 print_info(std::ostream &out) const override \
434 { \
435 out << " " outsequence << std::endl; \
436 } \
437 \
438 private: \
439 type1 const arg1; \
440 type2 const arg2; \
441 type3 const arg3; \
442 type4 const arg4; \
443 type5 const arg5; \
444 }
445
446#else /*ifndef DOXYGEN*/
447
448// Dummy definitions for doxygen:
449
466# define DeclException0(Exception0) \
467 \
468 static ::ExceptionBase &Exception0()
469
489# define DeclExceptionMsg(Exception, defaulttext) \
490 \
491 \
492 static ::ExceptionBase &Exception()
493
511# define DeclException1(Exception1, type1, outsequence) \
512 \
513 \
514 static ::ExceptionBase &Exception1(type1 arg1)
515
516
534# define DeclException2(Exception2, type1, type2, outsequence) \
535 \
536 \
537 static ::ExceptionBase &Exception2(type1 arg1, type2 arg2)
538
539
557# define DeclException3(Exception3, type1, type2, type3, outsequence) \
558 \
559 \
560 static ::ExceptionBase &Exception3(type1 arg1, type2 arg2, type3 arg3)
561
562
580# define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
581 \
582 \
583 static ::ExceptionBase &Exception4(type1 arg1, \
584 type2 arg2, \
585 type3 arg3, \
586 type4 arg4)
587
588
606# define DeclException5( \
607 Exception5, type1, type2, type3, type4, type5, outsequence) \
608 \
609 \
610 static ::ExceptionBase &Exception5( \
611 type1 arg1, type2 arg2, type3 arg3, type4 arg4, type5 arg5)
612
613#endif /*ifndef DOXYGEN*/
614
615
627namespace StandardExceptions
628{
637 DeclExceptionMsg(ExcDivideByZero,
638 "A piece of code is attempting a division by zero. This is "
639 "likely going to lead to results that make no sense.");
640
651 DeclException1(
652 ExcNumberNotFinite,
653 std::complex<double>,
654 << "In a significant number of places, deal.II checks that some intermediate "
655 << "value is a finite number (as opposed to plus or minus infinity, or "
656 << "NaN/Not a Number). In the current function, we encountered a number "
657 << "that is not finite (its value is " << arg1 << " and therefore "
658 << "violates the current assertion).\n\n"
659 << "This may be due to the fact that some operation in this function "
660 << "created such a value, or because one of the arguments you passed "
661 << "to the function already had this value from some previous "
662 << "operation. In the latter case, this function only triggered the "
663 << "error but may not actually be responsible for the computation of "
664 << "the number that is not finite.\n\n"
665 << "There are two common cases where this situation happens. First, your "
666 << "code (or something in deal.II) divides by zero in a place where this "
667 << "should not happen. Or, you are trying to solve a linear system "
668 << "with an unsuitable solver (such as an indefinite or non-symmetric "
669 << "linear system using a Conjugate Gradient solver); such attempts "
670 << "oftentimes yield an operation somewhere that tries to divide "
671 << "by zero or take the square root of a negative value.\n\n"
672 << "In any case, when trying to find the source of the error, "
673 << "recall that the location where you are getting this error is "
674 << "simply the first place in the program where there is a check "
675 << "that a number (e.g., an element of a solution vector) is in fact "
676 << "finite, but that the actual error that computed the number "
677 << "may have happened far earlier. To find this location, you "
678 << "may want to add checks for finiteness in places of your "
679 << "program visited before the place where this error is produced. "
680 << "One way to check for finiteness is to use the 'AssertIsFinite' "
681 << "macro.");
682
686 DeclException1(ExcOutOfMemory,
687 std::size_t,
688 "Your program tried to allocate some memory but this "
689 "allocation failed. Typically, this either means that "
690 "you simply do not have enough memory in your system, "
691 "or that you are (erroneously) trying to allocate "
692 "a chunk of memory that is simply beyond all reasonable "
693 "size, for example because the size of the object has "
694 "been computed incorrectly."
695 "\n\n"
696 "In the current case, the request was for "
697 << arg1 << " bytes.");
698
703 DeclException1(ExcMemoryLeak,
704 int,
705 << "Destroying memory handler while " << arg1
706 << " objects are still allocated.");
707
711 DeclExceptionMsg(ExcIO,
712 "An input/output error has occurred. There are a number of "
713 "reasons why this may be happening, both for reading and "
714 "writing operations."
715 "\n\n"
716 "If this happens during an operation that tries to read "
717 "data: First, you may be "
718 "trying to read from a file that doesn't exist or that is "
719 "not readable given its file permissions. Second, deal.II "
720 "uses this error at times if it tries to "
721 "read information from a file but where the information "
722 "in the file does not correspond to the expected format. "
723 "An example would be a truncated file, or a mesh file "
724 "that contains not only sections that describe the "
725 "vertices and cells, but also sections for additional "
726 "data that deal.II does not understand."
727 "\n\n"
728 "If this happens during an operation that tries to write "
729 "data: you may be trying to write to a file to which file "
730 "or directory permissions do not allow you to write. A "
731 "typical example is where you specify an output file in "
732 "a directory that does not exist.");
733
740 DeclException1(ExcFileNotOpen,
741 std::string,
742 << "Could not open file " << arg1
743 << "."
744 "\n\n"
745 "If this happens during an operation that tries to read "
746 "data: you may be "
747 "trying to read from a file that doesn't exist or that is "
748 "not readable given its file permissions."
749 "\n\n"
750 "If this happens during an operation that tries to write "
751 "data: you may be trying to write to a file to which file "
752 "or directory permissions do not allow you to write. A "
753 "typical example is where you specify an output file in "
754 "a directory that does not exist.");
755
764 DeclExceptionMsg(ExcNotImplemented,
765 "You are trying to use functionality in deal.II that is "
766 "currently not implemented. In many cases, this indicates "
767 "that there simply didn't appear much of a need for it, or "
768 "that the author of the original code did not have the "
769 "time to implement a particular case. If you hit this "
770 "exception, it is therefore worth the time to look into "
771 "the code to find out whether you may be able to "
772 "implement the missing functionality. If you do, please "
773 "consider providing a patch to the deal.II development "
774 "sources (see the deal.II website on how to contribute).");
775
796 DeclExceptionMsg(ExcInternalError,
797 "This exception -- which is used in many places in the "
798 "library -- usually indicates that some condition which "
799 "the author of the code thought must be satisfied at a "
800 "certain point in an algorithm, is not fulfilled. An "
801 "example would be that the first part of an algorithm "
802 "sorts elements of an array in ascending order, and "
803 "a second part of the algorithm later encounters an "
804 "element that is not larger than the previous one."
805 "\n\n"
806 "There is usually not very much you can do if you "
807 "encounter such an exception since it indicates an error "
808 "in deal.II, not in your own program. Try to come up with "
809 "the smallest possible program that still demonstrates "
810 "the error and contact the deal.II mailing lists with it "
811 "to obtain help.");
812
819 DeclExceptionMsg(
820 ExcPureFunctionCalled,
821 "You (or a place in the library) are trying to call a "
822 "function that is declared as a virtual function in a "
823 "base class but that has not been overridden in your "
824 "derived class."
825 "\n\n"
826 "This exception happens in cases where the base class "
827 "cannot provide a useful default implementation for "
828 "the virtual function, but where we also do not want "
829 "to mark the function as abstract (i.e., with '=0' at the end) "
830 "because the function is not essential to the class in many "
831 "contexts. In cases like this, the base class provides "
832 "a dummy implementation that makes the compiler happy, but "
833 "that then throws the current exception."
834 "\n\n"
835 "A concrete example would be the 'Function' class. It declares "
836 "the existence of 'value()' and 'gradient()' member functions, "
837 "and both are marked as 'virtual'. Derived classes have to "
838 "override these functions for the values and gradients of a "
839 "particular function. On the other hand, not every function "
840 "has a gradient, and even for those that do, not every program "
841 "actually needs to evaluate it. Consequently, there is no "
842 "*requirement* that a derived class actually override the "
843 "'gradient()' function (as there would be had it been marked "
844 "as abstract). But, since the base class cannot know how to "
845 "compute the gradient, if a derived class does not override "
846 "the 'gradient()' function and it is called anyway, then the "
847 "default implementation in the base class will simply throw "
848 "an exception."
849 "\n\n"
850 "The exception you see is what happens in cases such as the "
851 "one just illustrated. To fix the problem, you need to "
852 "investigate whether the function being called should indeed have "
853 "been called; if the answer is 'yes', then you need to "
854 "implement the missing override in your class.");
855
859 DeclException1(ExcFunctionNotProvided,
860 std::string,
861 << "Please provide an implementation for the function \""
862 << arg1 << "\"");
863
867 DeclException2(
868 ExcFunctionNonzeroReturn,
869 std::string,
870 int,
871 << "The function \"" << arg1 << "\" returned the nonzero value " << arg2
872 << ", but the calling site expected the return value to be zero. "
873 "This error often happens when the function in question is a 'callback', "
874 "that is a user-provided function called from somewhere within deal.II "
875 "or within an external library such as PETSc, Trilinos, SUNDIALS, etc., "
876 "that expect these callbacks to indicate errors via nonzero return "
877 "codes.");
878
882 DeclException0(ExcNotInitialized);
883
887 DeclException0(ExcInvalidState);
888
895 DeclException1(ExcImpossibleInDim,
896 int,
897 << "You are trying to execute functionality that is "
898 << "impossible in " << arg1
899 << "d or simply does not make any sense.");
900
908 DeclException2(ExcImpossibleInDimSpacedim,
909 int,
910 int,
911 << "You are trying to execute functionality that is "
912 << "impossible in dimensions <" << arg1 << ',' << arg2
913 << "> or simply does not make any sense.");
914
915
919 DeclExceptionMsg(ExcZero,
920 "In a check in the code, deal.II encountered a zero in "
921 "a place where this does not make sense. See the condition "
922 "that was being checked and that is printed further up "
923 "in the error message to get more information on what "
924 "the erroneous zero corresponds to.");
925
930 DeclExceptionMsg(ExcEmptyObject,
931 "The object you are trying to access is empty but it makes "
932 "no sense to attempt the operation you are trying on an "
933 "empty object.");
934
942 DeclException2(ExcDimensionMismatch,
943 std::size_t,
944 std::size_t,
945 << "Two sizes or dimensions were supposed to be equal, "
946 << "but aren't. They are " << arg1 << " and " << arg2 << '.');
947
952 DeclException2(
953 ExcInvalidIntegerConversion,
954 long long,
955 long long,
956 << "Two integers should be equal to each other after a type conversion but "
957 << "aren't. A typical cause of this problem is that the integral types "
958 << "used by deal.II and an external library are different (e.g., one uses "
959 << "32-bit integers and the other uses 64-bit integers). The integers are "
960 << arg1 << " and " << arg2 << '.');
961
966 DeclException3(ExcDimensionMismatch2,
967 std::size_t,
968 std::size_t,
969 std::size_t,
970 << "The size or dimension of one object, " << arg1
971 << " was supposed to be "
972 << "equal to one of two values, but isn't. The two possible "
973 << "values are " << arg2 << " and " << arg3 << '.');
974
987 DeclException3(
988 ExcIndexRange,
989 std::size_t,
990 std::size_t,
991 std::size_t,
992 << "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
993 << arg3 << ")."
994 << (arg2 == arg3 ?
995 " In the current case, this half-open range is in fact empty, "
996 "suggesting that you are accessing an element of an empty "
997 "collection such as a vector that has not been set to the "
998 "correct size." :
999 ""));
1000
1016 template <typename T>
1017 DeclException3(
1018 ExcIndexRangeType,
1019 T,
1020 T,
1021 T,
1022 << "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
1023 << arg3 << ")."
1024 << (arg2 == arg3 ?
1025 " In the current case, this half-open range is in fact empty, "
1026 "suggesting that you are accessing an element of an empty "
1027 "collection such as a vector that has not been set to the "
1028 "correct size." :
1029 ""));
1030
1034 DeclException2(ExcLowerRange,
1035 int,
1036 int,
1037 << "Number " << arg1 << " must be larger than or equal "
1038 << arg2 << '.');
1039
1043 template <typename T>
1044 DeclException2(ExcLowerRangeType,
1045 T,
1046 T,
1047 << "Number " << arg1 << " must be larger than or equal "
1048 << arg2 << '.');
1049
1054 DeclException2(ExcNotMultiple,
1055 int,
1056 int,
1057 << "Division " << arg1 << " by " << arg2
1058 << " has remainder different from zero.");
1059
1068 DeclExceptionMsg(ExcInvalidIterator,
1069 "You are trying to use an iterator, but the iterator is "
1070 "in an invalid state. This may indicate that the iterator "
1071 "object has not been initialized, or that it has been "
1072 "moved beyond the end of the range of valid elements.");
1073
1078 DeclExceptionMsg(ExcIteratorPastEnd,
1079 "You are trying to use an iterator, but the iterator is "
1080 "pointing past the end of the range of valid elements. "
1081 "It is not valid to dereference the iterator in this "
1082 "case.");
1083
1097 DeclException1(ExcMessage, std::string, << arg1);
1098
1102 DeclExceptionMsg(ExcGhostsPresent,
1103 "You are trying an operation on a vector that is only "
1104 "allowed if the vector has no ghost elements, but the "
1105 "vector you are operating on does have ghost elements."
1106 "\n\n"
1107 "Specifically, there are two kinds of operations that "
1108 "are typically not allowed on vectors with ghost elements. "
1109 "First, vectors with ghost elements are read-only "
1110 "and cannot appear in operations that write into these "
1111 "vectors. Second, reduction operations (such as computing "
1112 "the norm of a vector, or taking dot products between "
1113 "vectors) are not allowed to ensure that each vector "
1114 "element is counted only once (as opposed to once for "
1115 "the owner of the element plus once for each process "
1116 "on which the element is stored as a ghost copy)."
1117 "\n\n"
1118 "See the glossary entry on 'Ghosted vectors' for more "
1119 "information.");
1120
1125 DeclException1(ExcGridHasInvalidCell,
1126 int,
1127 << "Something went wrong when making cell " << arg1
1128 << ". Read the docs and the source code "
1129 << "for more information.");
1130
1138 DeclExceptionMsg(ExcScalarAssignmentOnlyForZeroValue,
1139 "You are trying an operation of the form 'vector = C', "
1140 "'matrix = C', or 'tensor = C' with a nonzero scalar value "
1141 "'C'. However, such assignments are only allowed if the "
1142 "C is zero, since the semantics for assigning any other "
1143 "value are not clear. For example: one could interpret "
1144 "assigning a matrix a value of 1 to mean the matrix has a "
1145 "norm of 1, the matrix is the identity matrix, or the "
1146 "matrix contains only 1s. Similar problems exist with "
1147 "vectors and tensors. Hence, to avoid this ambiguity, such "
1148 "assignments are not permitted.");
1149
1153 DeclExceptionMsg(
1154 ExcNeedsLAPACK,
1155 "You are attempting to use functionality that is only available "
1156 "if deal.II was configured to use LAPACK, but cmake did not "
1157 "find a valid LAPACK library.");
1158
1162 DeclExceptionMsg(
1163 ExcNeedsHDF5,
1164 "You are attempting to use functionality that requires that deal.II is configured "
1165 "with HDF5 support. However, when you called 'cmake', HDF5 support "
1166 "was not detected.");
1167
1171 DeclExceptionMsg(
1172 ExcNeedsMPI,
1173 "You are attempting to use functionality that is only available "
1174 "if deal.II was configured to use MPI.");
1175
1179 DeclExceptionMsg(
1180 ExcNeedsFunctionparser,
1181 "You are attempting to use functionality that is only available "
1182 "if deal.II was configured to use the function parser which "
1183 "relies on the muparser library, but cmake did not "
1184 "find a valid muparser library on your system and also did "
1185 "not choose the one that comes bundled with deal.II.");
1186
1190 DeclExceptionMsg(
1191 ExcNeedsAssimp,
1192 "You are attempting to use functionality that is only available "
1193 "if deal.II was configured to use Assimp, but cmake did not "
1194 "find a valid Assimp library.");
1195
1201 DeclExceptionMsg(
1202 ExcNeedsExodusII,
1203 "You are attempting to use functionality that is only available if deal.II "
1204 "was configured to use Trilinos' SEACAS library (which provides ExodusII), "
1205 "but cmake did not find a valid SEACAS library.");
1206
1210 DeclExceptionMsg(
1211 ExcNeedsCGAL,
1212 "You are attempting to use functionality that is only available "
1213 "if deal.II was configured to use CGAL, but cmake did not "
1214 "find a valid CGAL library.");
1215
1216#ifdef DEAL_II_WITH_MPI
1238 class ExcMPI : public ::ExceptionBase
1239 {
1240 public:
1241 ExcMPI(const int error_code);
1242
1243 virtual void
1244 print_info(std::ostream &out) const override;
1245
1246 const int error_code;
1247 };
1248#endif // DEAL_II_WITH_MPI
1249
1250
1251
1252#ifdef DEAL_II_TRILINOS_WITH_SEACAS
1261 class ExcExodusII : public ExceptionBase
1262 {
1263 public:
1269 ExcExodusII(const int error_code);
1270
1274 virtual void
1275 print_info(std::ostream &out) const override;
1276
1280 const int error_code;
1281 };
1282#endif // DEAL_II_TRILINOS_WITH_SEACAS
1283
1288 DeclExceptionMsg(
1289 RecoverableUserCallbackError,
1290 "A user call-back function encountered a recoverable error, "
1291 "but the underlying library that called the call-back did not "
1292 "manage to recover from the error and aborted its operation."
1293 "\n\n"
1294 "See the glossary entry on user call-back functions for more "
1295 "information.");
1296} /*namespace StandardExceptions*/
1297
1298
1299
1306namespace deal_II_exceptions
1307{
1308 namespace internals
1309 {
1317 extern bool allow_abort_on_exception;
1318 } // namespace internals
1319
1338 void
1339 set_additional_assert_output(const char *const p);
1340
1351 void
1352 suppress_stacktrace_in_exceptions();
1353
1368 void
1369 disable_abort_on_exception();
1370
1379 void
1380 enable_abort_on_exception();
1381
1389 namespace internals
1390 {
1395 [[noreturn]] void
1396 abort(const ExceptionBase &exc) noexcept;
1397
1414
1432 template <typename ExceptionType>
1433 [[noreturn]] void
1434 issue_error_noreturn(ExceptionHandling handling,
1435 const char *file,
1436 int line,
1437 const char *function,
1438 const char *cond,
1439 const char *exc_name,
1440 ExceptionType e)
1441 {
1442 static_assert(std::is_base_of_v<ExceptionBase, ExceptionType>,
1443 "The provided exception must inherit from ExceptionBase.");
1444 // Fill the fields of the exception object
1445 e.set_fields(file, line, function, cond, exc_name);
1446
1447 switch (handling)
1448 {
1449 case ExceptionHandling::abort_or_throw_on_exception:
1450 {
1451 if (::deal_II_exceptions::internals::
1452 allow_abort_on_exception)
1453 internals::abort(e);
1454 else
1455 {
1456 // We are not allowed to abort, so just throw the error:
1457 throw e;
1458 }
1459 }
1460 case ExceptionHandling::throw_on_exception:
1461 throw e;
1462 // this function should never return (and AssertNothrow can);
1463 // something must have gone wrong in the error handling code for us
1464 // to get this far, so throw an exception.
1465 default:
1466 throw ::StandardExceptions::ExcInternalError();
1467 }
1468 }
1469
1473 void
1474 do_issue_error_nothrow(const ExceptionBase &e) noexcept;
1475
1484 template <typename ExceptionType>
1485 void
1486 issue_error_nothrow(const char *file,
1487 int line,
1488 const char *function,
1489 const char *cond,
1490 const char *exc_name,
1491 ExceptionType e) noexcept
1492 {
1493 static_assert(std::is_base_of_v<ExceptionBase, ExceptionType>,
1494 "The provided exception must inherit from ExceptionBase.");
1495 // Fill the fields of the exception object
1496 e.set_fields(file, line, function, cond, exc_name);
1497 // avoid moving a bunch of code into the header by dispatching to
1498 // another function:
1499 do_issue_error_nothrow(e);
1500 }
1501 } /*namespace internals*/
1502
1503} /*namespace deal_II_exceptions*/
1504
1505
1506
1532#ifdef DEBUG
1533# if KOKKOS_VERSION >= 30600
1534# ifdef DEAL_II_HAVE_BUILTIN_EXPECT
1535# define Assert(cond, exc) \
1536 do \
1537 { \
1538 KOKKOS_IF_ON_HOST(({ \
1539 if (__builtin_expect(!(cond), false)) \
1540 ::deal_II_exceptions::internals::issue_error_noreturn( \
1541 ::deal_II_exceptions::internals::ExceptionHandling:: \
1542 abort_or_throw_on_exception, \
1543 __FILE__, \
1544 __LINE__, \
1545 __PRETTY_FUNCTION__, \
1546 #cond, \
1547 #exc, \
1548 exc); \
1549 })) \
1550 KOKKOS_IF_ON_DEVICE(({ \
1551 if (!(cond)) \
1552 Kokkos::abort(#cond); \
1553 })) \
1554 } \
1555 while (false)
1556# else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1557# define Assert(cond, exc) \
1558 do \
1559 { \
1560 KOKKOS_IF_ON_HOST(({ \
1561 if (!(cond)) \
1562 ::deal_II_exceptions::internals::issue_error_noreturn( \
1563 ::deal_II_exceptions::internals::ExceptionHandling:: \
1564 abort_or_throw_on_exception, \
1565 __FILE__, \
1566 __LINE__, \
1567 __PRETTY_FUNCTION__, \
1568 #cond, \
1569 #exc, \
1570 exc); \
1571 })) \
1572 KOKKOS_IF_ON_DEVICE(({ \
1573 if (!(cond)) \
1574 Kokkos::abort(#cond); \
1575 })) \
1576 } \
1577 while (false)
1578# endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1579# else /*if KOKKOS_VERSION >= 30600*/
1580# ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST
1581# ifdef DEAL_II_HAVE_BUILTIN_EXPECT
1582# define Assert(cond, exc) \
1583 do \
1584 { \
1585 if (__builtin_expect(!(cond), false)) \
1586 ::deal_II_exceptions::internals::issue_error_noreturn( \
1587 ::deal_II_exceptions::internals::ExceptionHandling:: \
1588 abort_or_throw_on_exception, \
1589 __FILE__, \
1590 __LINE__, \
1591 __PRETTY_FUNCTION__, \
1592 #cond, \
1593 #exc, \
1594 exc); \
1595 } \
1596 while (false)
1597# else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1598# define Assert(cond, exc) \
1599 do \
1600 { \
1601 if (!(cond)) \
1602 ::deal_II_exceptions::internals::issue_error_noreturn( \
1603 ::deal_II_exceptions::internals::ExceptionHandling:: \
1604 abort_or_throw_on_exception, \
1605 __FILE__, \
1606 __LINE__, \
1607 __PRETTY_FUNCTION__, \
1608 #cond, \
1609 #exc, \
1610 exc); \
1611 } \
1612 while (false)
1613# endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1614# else /*#ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
1615# define Assert(cond, exc) \
1616 do \
1617 { \
1618 if (!(cond)) \
1619 Kokkos::abort(#cond); \
1620 } \
1621 while (false)
1622# endif /*ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
1623# endif /*KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
1624#else /*ifdef DEBUG*/
1625# ifdef DEAL_II_HAVE_CXX20
1626/*
1627 * In order to avoid unused parameters (etc.) warnings we need to use cond
1628 * and exc without actually evaluating the expression and generating code.
1629 * We accomplish this by using decltype(...) and create a dummy pointer
1630 * with these signatures. Notably, this approach works with C++20 onwards.
1631 */
1632# define Assert(cond, exc) \
1633 do \
1634 { \
1635 typename std::remove_reference<decltype(cond)>::type \
1636 *dealii_assert_variable_a = nullptr; \
1637 typename std::remove_reference<decltype(exc)>::type \
1638 *dealii_assert_variable_b = nullptr; \
1639 (void)dealii_assert_variable_a; \
1640 (void)dealii_assert_variable_b; \
1641 } \
1642 while (false)
1643# else
1644# define Assert(cond, exc) \
1645 do \
1646 { \
1647 } \
1648 while (false)
1649# endif
1650#endif /*ifdef DEBUG*/
1651
1652
1653
1680#ifdef DEBUG
1681# ifdef DEAL_II_HAVE_BUILTIN_EXPECT
1682# define AssertNothrow(cond, exc) \
1683 do \
1684 { \
1685 if (__builtin_expect(!(cond), false)) \
1686 ::deal_II_exceptions::internals::issue_error_nothrow( \
1687 __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
1688 } \
1689 while (false)
1690# else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1691# define AssertNothrow(cond, exc) \
1692 do \
1693 { \
1694 if (!(cond)) \
1695 ::deal_II_exceptions::internals::issue_error_nothrow( \
1696 __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
1697 } \
1698 while (false)
1699# endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1700#else
1701# define AssertNothrow(cond, exc) \
1702 do \
1703 { \
1704 } \
1705 while (false)
1706#endif
1707
1735#ifdef DEAL_II_HAVE_BUILTIN_EXPECT
1736# define AssertThrow(cond, exc) \
1737 do \
1738 { \
1739 if (__builtin_expect(!(cond), false)) \
1740 ::deal_II_exceptions::internals::issue_error_noreturn( \
1741 ::deal_II_exceptions::internals::ExceptionHandling:: \
1742 throw_on_exception, \
1743 __FILE__, \
1744 __LINE__, \
1745 __PRETTY_FUNCTION__, \
1746 #cond, \
1747 #exc, \
1748 exc); \
1749 } \
1750 while (false)
1751#else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1752# define AssertThrow(cond, exc) \
1753 do \
1754 { \
1755 if (!(cond)) \
1756 ::deal_II_exceptions::internals::issue_error_noreturn( \
1757 ::deal_II_exceptions::internals::ExceptionHandling:: \
1758 throw_on_exception, \
1759 __FILE__, \
1760 __LINE__, \
1761 __PRETTY_FUNCTION__, \
1762 #cond, \
1763 #exc, \
1764 exc); \
1765 } \
1766 while (false)
1767#endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
1768
1769
1811#define DEAL_II_NOT_IMPLEMENTED() \
1812 ::deal_II_exceptions::internals::issue_error_noreturn( \
1813 ::deal_II_exceptions::internals::ExceptionHandling:: \
1814 abort_or_throw_on_exception, \
1815 __FILE__, \
1816 __LINE__, \
1817 __PRETTY_FUNCTION__, \
1818 nullptr, \
1819 nullptr, \
1820 ::StandardExceptions::ExcNotImplemented())
1821
1822
1894#define DEAL_II_ASSERT_UNREACHABLE() \
1895 ::deal_II_exceptions::internals::issue_error_noreturn( \
1896 ::deal_II_exceptions::internals::ExceptionHandling:: \
1897 abort_or_throw_on_exception, \
1898 __FILE__, \
1899 __LINE__, \
1900 __PRETTY_FUNCTION__, \
1901 nullptr, \
1902 nullptr, \
1903 ::StandardExceptions::ExcMessage( \
1904 "The program has hit a line of code that the programmer " \
1905 "marked with the macro DEAL_II_ASSERT_UNREACHABLE() to " \
1906 "indicate that the program should never reach this " \
1907 "location. You will have to find out (best done in a " \
1908 "debugger) why that happened. Typical reasons include " \
1909 "passing invalid arguments to functions (for example, if " \
1910 "a function takes an 'enum' with two possible values " \
1911 "as argument, but you call the function with a third " \
1912 "value), or if the programmer of the code that triggered " \
1913 "the error believed that a variable can only have " \
1914 "specific values, but either that assumption is wrong " \
1915 "or the computation of that value is buggy." \
1916 "\n\n" \
1917 "In those latter conditions, where some internal " \
1918 "assumption is not satisfied, there may not be very " \
1919 "much you can do if you encounter such an exception, " \
1920 "since it indicates an error in deal.II, not in your " \
1921 "own program. If that is the situation you encounter, " \
1922 "try to come up with " \
1923 "the smallest possible program that still demonstrates " \
1924 "the error and contact the deal.II mailing lists with it " \
1925 "to obtain help."))
1926
1927
1928namespace deal_II_exceptions
1929{
1930 namespace internals
1931 {
1937 template <typename T, typename U>
1938 inline DEAL_II_HOST_DEVICE constexpr bool
1939 compare_for_equality(const T &t, const U &u)
1940 {
1941 using common_type = std::common_type_t<T, U>;
1942 return static_cast<common_type>(t) == static_cast<common_type>(u);
1943 }
1944
1945
1951 template <typename T, typename U>
1952 inline DEAL_II_HOST_DEVICE constexpr bool
1953 compare_less_than(const T &t, const U &u)
1954 {
1955 using common_type = std::common_type_t<T, U>;
1956 return (static_cast<common_type>(t) < static_cast<common_type>(u));
1957 }
1958 } // namespace internals
1959} // namespace deal_II_exceptions
1960
1961
1982#define AssertDimension(dim1, dim2) \
1983 Assert(::deal_II_exceptions::internals::compare_for_equality(dim1, \
1984 dim2), \
1985 ::ExcDimensionMismatch((dim1), (dim2)))
1986
1995#define AssertIntegerConversion(index1, index2) \
1996 Assert(::deal_II_exceptions::internals::compare_for_equality( \
1997 index1, index2), \
1998 ::ExcInvalidIntegerConversion((index1), (index2)))
1999
2004#define AssertThrowIntegerConversion(index1, index2) \
2005 AssertThrow(::deal_II_exceptions::internals::compare_for_equality( \
2006 index1, index2), \
2007 ::ExcInvalidIntegerConversion((index1), (index2)))
2008
2026#define AssertVectorVectorDimension(VEC, DIM1, DIM2) \
2027 AssertDimension(VEC.size(), DIM1); \
2028 for (const auto &subvector : VEC) \
2029 { \
2030 (void)subvector; \
2031 AssertDimension(subvector.size(), DIM2); \
2032 }
2033
2034namespace internal
2035{
2036 // Workaround to allow for commas in template parameter lists
2037 // in preprocessor macros as found in
2038 // https://stackoverflow.com/questions/13842468/comma-in-c-c-macro
2039 template <typename F>
2040 struct argument_type;
2041
2042 template <typename T, typename U>
2043 struct argument_type<T(U)>
2044 {
2045 using type = U;
2046 };
2047
2048 template <typename F>
2049 using argument_type_t = typename argument_type<F>::type;
2050} // namespace internal
2051
2071#define AssertIndexRange(index, range) \
2072 Assert(::deal_II_exceptions::internals::compare_less_than(index, \
2073 range), \
2074 ExcIndexRangeType<::internal::argument_type_t<void( \
2075 std::common_type_t<decltype(index), decltype(range)>)>>((index), \
2076 0, \
2077 (range)))
2078
2098#define AssertIsFinite(number) \
2099 Assert(::numbers::is_finite(number), \
2100 ::ExcNumberNotFinite(std::complex<double>(number)))
2101
2107#define AssertIsNotUsed(obj) Assert((obj)->used() == false, ExcInternalError())
2108
2109#ifdef DEAL_II_WITH_MPI
2130# define AssertThrowMPI(error_code) \
2131 AssertThrow(error_code == MPI_SUCCESS, ::ExcMPI(error_code))
2132#else
2133# define AssertThrowMPI(error_code) \
2134 do \
2135 { \
2136 } \
2137 while (false)
2138#endif // DEAL_II_WITH_MPI
2139
2140#ifdef DEAL_II_TRILINOS_WITH_SEACAS
2158# define AssertThrowExodusII(error_code) \
2159 AssertThrow(error_code == 0, \
2160 ::StandardExceptions::ExcExodusII(error_code));
2161#endif // DEAL_II_TRILINOS_WITH_SEACAS
2162
2163using namespace StandardExceptions;
2164
2165DEAL_II_NAMESPACE_CLOSE
2166
2167#endif
ExceptionBase::generate_message
void generate_message() const
Definition exceptions.cc:342
ExceptionBase::print_stack_trace
void print_stack_trace(std::ostream &out) const
Definition exceptions.cc:240
ExceptionBase::file
const char * file
Definition exceptions.h:124
ExceptionBase::what_str
std::string what_str
Definition exceptions.h:170
ExceptionBase::get_exc_name
const char * get_exc_name() const
Definition exceptions.cc:172
ExceptionBase::~ExceptionBase
virtual ~ExceptionBase() noexcept override=default
ExceptionBase::n_stacktrace_frames
int n_stacktrace_frames
Definition exceptions.h:150
ExceptionBase::set_fields
void set_fields(const char *file, const int line, const char *function, const char *cond, const char *exc_name)
Definition exceptions.cc:135
ExceptionBase::print_info
virtual void print_info(std::ostream &out) const
Definition exceptions.cc:232
ExceptionBase::what
virtual const char * what() const noexcept override
Definition exceptions.cc:160
ExceptionBase::exc
const char * exc
Definition exceptions.h:144
ExceptionBase::function
const char * function
Definition exceptions.h:134
ExceptionBase::print_exc_data
void print_exc_data(std::ostream &out) const
Definition exceptions.cc:180
ExceptionBase::line
unsigned int line
Definition exceptions.h:129
ExceptionBase::raw_stacktrace
void * raw_stacktrace[25]
Definition exceptions.h:156
ExceptionBase::cond
const char * cond
Definition exceptions.h:139
StandardExceptions::ExcMPI::print_info
virtual void print_info(std::ostream &out) const override
Definition exceptions.cc:408
DEAL_II_NAMESPACE_OPEN
#define DEAL_II_NAMESPACE_OPEN
Definition config.h:498
DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
#define DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
Definition config.h:512
DEAL_II_NAMESPACE_CLOSE
#define DEAL_II_NAMESPACE_CLOSE
Definition config.h:499
DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
#define DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
Definition config.h:555
StandardExceptions::ExcIndexRangeType
static ::ExceptionBase & ExcIndexRangeType(T arg1, T arg2, T arg3)
StandardExceptions::ExcImpossibleInDimSpacedim
static ::ExceptionBase & ExcImpossibleInDimSpacedim(int arg1, int arg2)
DeclException0
#define DeclException0(Exception0)
Definition exceptions.h:466
StandardExceptions::ExcInvalidIterator
static ::ExceptionBase & ExcInvalidIterator()
StandardExceptions::ExcOutOfMemory
static ::ExceptionBase & ExcOutOfMemory(std::size_t arg1)
StandardExceptions::ExcIO
static ::ExceptionBase & ExcIO()
StandardExceptions::ExcGhostsPresent
static ::ExceptionBase & ExcGhostsPresent()
StandardExceptions::ExcFileNotOpen
static ::ExceptionBase & ExcFileNotOpen(std::string arg1)
StandardExceptions::ExcZero
static ::ExceptionBase & ExcZero()
StandardExceptions::ExcNeedsAssimp
static ::ExceptionBase & ExcNeedsAssimp()
StandardExceptions::ExcNeedsFunctionparser
static ::ExceptionBase & ExcNeedsFunctionparser()
StandardExceptions::ExcNotMultiple
static ::ExceptionBase & ExcNotMultiple(int arg1, int arg2)
StandardExceptions::ExcNotImplemented
static ::ExceptionBase & ExcNotImplemented()
StandardExceptions::ExcNeedsMPI
static ::ExceptionBase & ExcNeedsMPI()
StandardExceptions::ExcFunctionNotProvided
static ::ExceptionBase & ExcFunctionNotProvided(std::string arg1)
StandardExceptions::ExcEmptyObject
static ::ExceptionBase & ExcEmptyObject()
StandardExceptions::ExcScalarAssignmentOnlyForZeroValue
static ::ExceptionBase & ExcScalarAssignmentOnlyForZeroValue()
StandardExceptions::ExcMemoryLeak
static ::ExceptionBase & ExcMemoryLeak(int arg1)
StandardExceptions::ExcLowerRangeType
static ::ExceptionBase & ExcLowerRangeType(T arg1, T arg2)
StandardExceptions::ExcImpossibleInDim
static ::ExceptionBase & ExcImpossibleInDim(int arg1)
StandardExceptions::ExcIteratorPastEnd
static ::ExceptionBase & ExcIteratorPastEnd()
StandardExceptions::ExcNeedsExodusII
static ::ExceptionBase & ExcNeedsExodusII()
StandardExceptions::ExcDimensionMismatch2
static ::ExceptionBase & ExcDimensionMismatch2(std::size_t arg1, std::size_t arg2, std::size_t arg3)
DeclException2
#define DeclException2(Exception2, type1, type2, outsequence)
Definition exceptions.h:534
StandardExceptions::ExcLowerRange
static ::ExceptionBase & ExcLowerRange(int arg1, int arg2)
StandardExceptions::ExcGridHasInvalidCell
static ::ExceptionBase & ExcGridHasInvalidCell(int arg1)
StandardExceptions::ExcNumberNotFinite
static ::ExceptionBase & ExcNumberNotFinite(std::complex< double > arg1)
StandardExceptions::ExcPureFunctionCalled
static ::ExceptionBase & ExcPureFunctionCalled()
DeclExceptionMsg
#define DeclExceptionMsg(Exception, defaulttext)
Definition exceptions.h:489
StandardExceptions::ExcInternalError
static ::ExceptionBase & ExcInternalError()
StandardExceptions::ExcDivideByZero
static ::ExceptionBase & ExcDivideByZero()
StandardExceptions::ExcNeedsHDF5
static ::ExceptionBase & ExcNeedsHDF5()
StandardExceptions::ExcNeedsLAPACK
static ::ExceptionBase & ExcNeedsLAPACK()
DeclException3
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition exceptions.h:557
StandardExceptions::ExcNeedsCGAL
static ::ExceptionBase & ExcNeedsCGAL()
StandardExceptions::ExcIndexRange
static ::ExceptionBase & ExcIndexRange(std::size_t arg1, std::size_t arg2, std::size_t arg3)
StandardExceptions::ExcDimensionMismatch
static ::ExceptionBase & ExcDimensionMismatch(std::size_t arg1, std::size_t arg2)
StandardExceptions::ExcNotInitialized
static ::ExceptionBase & ExcNotInitialized()
StandardExceptions::ExcInvalidState
static ::ExceptionBase & ExcInvalidState()
DeclException1
#define DeclException1(Exception1, type1, outsequence)
Definition exceptions.h:511
StandardExceptions::RecoverableUserCallbackError
static ::ExceptionBase & RecoverableUserCallbackError()
StandardExceptions::ExcInvalidIntegerConversion
static ::ExceptionBase & ExcInvalidIntegerConversion(long long arg1, long long arg2)
StandardExceptions::ExcMessage
static ::ExceptionBase & ExcMessage(std::string arg1)
StandardExceptions::ExcFunctionNonzeroReturn
static ::ExceptionBase & ExcFunctionNonzeroReturn(std::string arg1, int arg2)
deal_II_exceptions::internals::compare_less_than
constexpr bool compare_less_than(const T &t, const U &u)
Definition exceptions.h:1953
deal_II_exceptions::internals::compare_for_equality
constexpr bool compare_for_equality(const T &t, const U &u)
Definition exceptions.h:1939
deal_II_exceptions::internals::issue_error_noreturn
void issue_error_noreturn(ExceptionHandling handling, const char *file, int line, const char *function, const char *cond, const char *exc_name, ExceptionType e)
Definition exceptions.h:1434
deal_II_exceptions::internals::ExceptionHandling
ExceptionHandling
Definition exceptions.h:1402
deal_II_exceptions::internals::ExceptionHandling::throw_on_exception
@ throw_on_exception
deal_II_exceptions::internals::ExceptionHandling::abort_or_throw_on_exception
@ abort_or_throw_on_exception
deal_II_exceptions::internals::abort
void abort(const ExceptionBase &exc) noexcept
Definition exceptions.cc:480
deal_II_exceptions::internals::do_issue_error_nothrow
void do_issue_error_nothrow(const ExceptionBase &e) noexcept
Definition exceptions.cc:545
deal_II_exceptions::internals::allow_abort_on_exception
bool allow_abort_on_exception
Definition exceptions.cc:58
deal_II_exceptions::internals::issue_error_nothrow
void issue_error_nothrow(const char *file, int line, const char *function, const char *cond, const char *exc_name, ExceptionType e) noexcept
Definition exceptions.h:1486
deal_II_exceptions
Definition exceptions.h:1307
deal_II_exceptions::enable_abort_on_exception
void enable_abort_on_exception()
Definition exceptions.cc:88
deal_II_exceptions::disable_abort_on_exception
void disable_abort_on_exception()
Definition exceptions.cc:80
deal_II_exceptions::set_additional_assert_output
void set_additional_assert_output(const char *const p)
deal_II_exceptions::suppress_stacktrace_in_exceptions
void suppress_stacktrace_in_exceptions()
Definition exceptions.cc:72
internal::argument_type_t
typename argument_type< F >::type argument_type_t
Definition exceptions.h:2049
std
STL namespace.
DEAL_II_HOST_DEVICE
#define DEAL_II_HOST_DEVICE
Definition numbers.h:30
internal::argument_type< T(U)>::type
U type
Definition exceptions.h:2045
internal::argument_type
Definition exceptions.h:2040
Generated by doxygen 1.9.8