Debian Codegraph @

include/deal.II/base/exceptions.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2025 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
20 // The exception machinery (including the macros defined in
21 // exception_macros.h) references Kokkos functions. The places that
22 // use exceptions must know about these functions, and to avoid them
23 // all having to include Kokkos headers, we have to do it here:
24 DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
25 #include <Kokkos_Macros.hpp>
26 #if DEAL_II_KOKKOS_VERSION_GTE(4, 2, 0)
27 # include <Kokkos_Abort.hpp>
28 #else
29 # include <Kokkos_Core.hpp>
30 #endif
31 DEAL_II_ENABLE_EXTRA_DIAGNOSTICS
32
33
34 #include <deal.II/base/exception_macros.h>
35
36 #include <complex>
37 #include <exception>
38 #include <ostream>
39 #include <string>
40 #include <type_traits>
41
42 DEAL_II_NAMESPACE_OPEN
43
44
45 /**
46 * This class is the base class for all exception classes. Do not use its
47 * methods and variables directly since the interface and mechanism may be
48 * subject to change. Rather create new exception classes using the
49 * <tt>DeclException</tt> macro family.
50 *
51 * See the
52 * @ref Exceptions
53 * topic for more details on this class and what can be done with classes
54 * derived from it.
55 *
56 * @ingroup Exceptions
57 */
58 class ExceptionBase : public std::exception
59 {
60 public:
61 /**
62 * Default constructor.
63 */
64 ExceptionBase();
65
66 /**
67 * Copy constructor.
68 */
69 ExceptionBase(const ExceptionBase &exc);
70
71 /**
72 * Destructor.
73 */
74 virtual ~ExceptionBase() noexcept override = default;
75
76 /**
77 * Copy operator. This operator is deleted since exception objects
78 * are not copyable.
79 */
80 ExceptionBase
81 operator=(const ExceptionBase &) = delete;
82
83 /**
84 * Set the file name and line of where the exception appeared as well as the
85 * violated condition and the name of the exception as a char pointer. This
86 * function also populates the stacktrace.
87 */
88 void
89 set_fields(const char *file,
90 const int line,
91 const char *function,
92 const char *cond,
93 const char *exc_name);
94
95
96 /**
97 * Override the standard function that returns the description of the error.
98 */
99 virtual const char *
100 what() const noexcept override;
101
102 /**
103 * Get exception name.
104 */
105 const char *
106 get_exc_name() const;
107
108 /**
109 * Print out the general part of the error information.
110 */
111 void
112 print_exc_data(std::ostream &out) const;
113
114 /**
115 * Print more specific information about the exception which occurred.
116 * Overload this function in your own exception classes.
117 */
118 virtual void
119 print_info(std::ostream &out) const;
120
121 /**
122 * Print a stacktrace, if one has been recorded previously, to the given
123 * stream.
124 */
125 void
126 print_stack_trace(std::ostream &out) const;
127
128 protected:
129 /**
130 * Name of the file this exception happens in.
131 */
132 const char *file;
133
134 /**
135 * Line number in this file.
136 */
137 unsigned int line;
138
139 /**
140 * Name of the function, pretty printed.
141 */
142 const char *function;
143
144 /**
145 * The violated condition, as a string.
146 */
147 const char *cond;
148
149 /**
150 * Name of the exception and call sequence.
151 */
152 const char *exc;
153
154 /**
155 * The number of stacktrace frames that are stored in the following variable.
156 * Zero if the system does not support stack traces.
157 */
158 int n_stacktrace_frames;
159
160 #ifdef DEAL_II_HAVE_GLIBC_STACKTRACE
161 /**
162 * Array of pointers that contains the raw stack trace.
163 */
164 void *raw_stacktrace[25];
165 #endif
166
167 private:
168 /**
169 * Internal function that generates the c_string. Called by what().
170 */
171 void
172 generate_message() const;
173
174 /**
175 * A pointer to the c_string that will be printed by what(). It is populated
176 * by generate_message()
177 */
178 mutable std::string what_str;
179 };
180
181
182 /**
183 * Declare some exceptions that occur over and over. This way, you can simply
184 * use these exceptions, instead of having to declare them locally in your
185 * class. The namespace in which these exceptions are declared is later
186 * included into the global namespace by
187 * @code
188 * using namespace StandardExceptions;
189 * @endcode
190 *
191 * @ingroup Exceptions
192 */
193 namespace StandardExceptions
194 {
195 /**
196 * @addtogroup Exceptions
197 * @{
198 */
199
200 /**
201 * Exception denoting a division by zero.
202 */
203 DeclExceptionMsg(ExcDivideByZero,
204 "A piece of code is attempting a division by zero. This is "
205 "likely going to lead to results that make no sense.");
206
207 /**
208 * Exception raised if a number is not finite.
209 *
210 * This exception should be used to catch infinite or not a number results
211 * of arithmetic operations that do not result from a division by zero (use
212 * ExcDivideByZero for those).
213 *
214 * The exception uses std::complex as its argument to ensure that we can use
215 * it for all scalar arguments (real or complex-valued).
216 */
217 DeclException1(
218 ExcNumberNotFinite,
219 std::complex<double>,
220 << "In a significant number of places, deal.II checks that some intermediate "
221 << "value is a finite number (as opposed to plus or minus infinity, or "
222 << "NaN/Not a Number). In the current function, we encountered a number "
223 << "that is not finite (its value is " << arg1 << " and therefore "
224 << "violates the current assertion).\n\n"
225 << "This may be due to the fact that some operation in this function "
226 << "created such a value, or because one of the arguments you passed "
227 << "to the function already had this value from some previous "
228 << "operation. In the latter case, this function only triggered the "
229 << "error but may not actually be responsible for the computation of "
230 << "the number that is not finite.\n\n"
231 << "There are two common cases where this situation happens. First, your "
232 << "code (or something in deal.II) divides by zero in a place where this "
233 << "should not happen. Or, you are trying to solve a linear system "
234 << "with an unsuitable solver (such as an indefinite or non-symmetric "
235 << "linear system using a Conjugate Gradient solver); such attempts "
236 << "oftentimes yield an operation somewhere that tries to divide "
237 << "by zero or take the square root of a negative value.\n\n"
238 << "In any case, when trying to find the source of the error, "
239 << "recall that the location where you are getting this error is "
240 << "simply the first place in the program where there is a check "
241 << "that a number (e.g., an element of a solution vector) is in fact "
242 << "finite, but that the actual error that computed the number "
243 << "may have happened far earlier. To find this location, you "
244 << "may want to add checks for finiteness in places of your "
245 << "program visited before the place where this error is produced. "
246 << "One way to check for finiteness is to use the 'AssertIsFinite' "
247 << "macro.");
248
249 /**
250 * Trying to allocate a new object failed due to lack of free memory.
251 */
252 DeclException1(ExcOutOfMemory,
253 std::size_t,
254 "Your program tried to allocate some memory but this "
255 "allocation failed. Typically, this either means that "
256 "you simply do not have enough memory in your system, "
257 "or that you are (erroneously) trying to allocate "
258 "a chunk of memory that is simply beyond all reasonable "
259 "size, for example because the size of the object has "
260 "been computed incorrectly."
261 "\n\n"
262 "In the current case, the request was for "
263 << arg1 << " bytes.");
264
265 /**
266 * A memory handler reached a point where all allocated objects should have
267 * been released. Since this exception is thrown, some were still allocated.
268 */
269 DeclException1(ExcMemoryLeak,
270 int,
271 << "Destroying memory handler while " << arg1
272 << " objects are still allocated.");
273
274 /**
275 * An error occurred reading or writing a file.
276 */
277 DeclExceptionMsg(ExcIO,
278 "An input/output error has occurred. There are a number of "
279 "reasons why this may be happening, both for reading and "
280 "writing operations."
281 "\n\n"
282 "If this happens during an operation that tries to read "
283 "data: First, you may be "
284 "trying to read from a file that doesn't exist or that is "
285 "not readable given its file permissions. Second, deal.II "
286 "uses this error at times if it tries to "
287 "read information from a file but where the information "
288 "in the file does not correspond to the expected format. "
289 "An example would be a truncated file, or a mesh file "
290 "that contains not only sections that describe the "
291 "vertices and cells, but also sections for additional "
292 "data that deal.II does not understand."
293 "\n\n"
294 "If this happens during an operation that tries to write "
295 "data: you may be trying to write to a file to which file "
296 "or directory permissions do not allow you to write. A "
297 "typical example is where you specify an output file in "
298 "a directory that does not exist.");
299
300 /**
301 * An error occurred opening the named file.
302 *
303 * The constructor takes a single argument of type <tt>std::string</tt> naming
304 * the file.
305 */
306 DeclException1(ExcFileNotOpen,
307 std::string,
308 << "Could not open file " << arg1
309 << "."
310 "\n\n"
311 "If this happens during an operation that tries to read "
312 "data: you may be "
313 "trying to read from a file that doesn't exist or that is "
314 "not readable given its file permissions."
315 "\n\n"
316 "If this happens during an operation that tries to write "
317 "data: you may be trying to write to a file to which file "
318 "or directory permissions do not allow you to write. A "
319 "typical example is where you specify an output file in "
320 "a directory that does not exist.");
321
322 /**
323 * Exception denoting a part of the library or application program that has
324 * not yet been implemented. In many cases, this only indicates that there
325 * wasn't much need for something yet, not that this is difficult to
326 * implement. It is therefore quite worth the effort to take a look at the
327 * corresponding place and see whether it can be implemented without too
328 * much effort.
329 */
330 DeclExceptionMsg(ExcNotImplemented,
331 "You are trying to use functionality in deal.II that is "
332 "currently not implemented. In many cases, this indicates "
333 "that there simply didn't appear much of a need for it, or "
334 "that the author of the original code did not have the "
335 "time to implement a particular case. If you hit this "
336 "exception, it is therefore worth the time to look into "
337 "the code to find out whether you may be able to "
338 "implement the missing functionality. If you do, please "
339 "consider providing a patch to the deal.II development "
340 "sources (see the deal.II website on how to contribute).");
341
342 /**
343 * This exception usually indicates that some condition which the programmer
344 * thinks must be satisfied at a certain point in an algorithm, is not
345 * fulfilled. This might be due to some programming error above, due to
346 * changes to the algorithm that did not preserve this assertion, or due to
347 * assumptions the programmer made that are not valid at all (i.e. the
348 * exception is thrown although there is no error here). Within the library,
349 * this exception is most often used when we write some kind of complicated
350 * algorithm and are not yet sure whether we got it right; we then put in
351 * assertions after each part of the algorithm that check for some
352 * conditions that should hold there, and throw an exception if they do not.
353 *
354 * We usually leave in these assertions even after we are confident that the
355 * implementation is correct, since if someone later changes or extends the
356 * algorithm, these exceptions will indicate to them if they violate
357 * assumptions that are used later in the algorithm. Furthermore, it
358 * sometimes happens that an algorithm does not work in very rare corner
359 * cases. These cases will then be trapped sooner or later by the exception,
360 * so that the algorithm can then be fixed for these cases as well.
361 */
362 DeclExceptionMsg(ExcInternalError,
363 "This exception -- which is used in many places in the "
364 "library -- usually indicates that some condition which "
365 "the author of the code thought must be satisfied at a "
366 "certain point in an algorithm, is not fulfilled. An "
367 "example would be that the first part of an algorithm "
368 "sorts elements of an array in ascending order, and "
369 "a second part of the algorithm later encounters an "
370 "element that is not larger than the previous one."
371 "\n\n"
372 "There is usually not very much you can do if you "
373 "encounter such an exception since it indicates an error "
374 "in deal.II, not in your own program. Try to come up with "
375 "the smallest possible program that still demonstrates "
376 "the error and contact the deal.II mailing lists with it "
377 "to obtain help.");
378
379 /**
380 * This exception is used in functions that may not be called (i.e. in pure
381 * functions) but could not be declared pure since the class is intended to
382 * be used anyway, even though the respective function may only be called if
383 * a derived class is used.
384 */
385 DeclExceptionMsg(
386 ExcPureFunctionCalled,
387 "You (or a place in the library) are trying to call a "
388 "function that is declared as a virtual function in a "
389 "base class but that has not been overridden in your "
390 "derived class."
391 "\n\n"
392 "This exception happens in cases where the base class "
393 "cannot provide a useful default implementation for "
394 "the virtual function, but where we also do not want "
395 "to mark the function as abstract (i.e., with '=0' at the end) "
396 "because the function is not essential to the class in many "
397 "contexts. In cases like this, the base class provides "
398 "a dummy implementation that makes the compiler happy, but "
399 "that then throws the current exception."
400 "\n\n"
401 "A concrete example would be the 'Function' class. It declares "
402 "the existence of 'value()' and 'gradient()' member functions, "
403 "and both are marked as 'virtual'. Derived classes have to "
404 "override these functions for the values and gradients of a "
405 "particular function. On the other hand, not every function "
406 "has a gradient, and even for those that do, not every program "
407 "actually needs to evaluate it. Consequently, there is no "
408 "*requirement* that a derived class actually override the "
409 "'gradient()' function (as there would be had it been marked "
410 "as abstract). But, since the base class cannot know how to "
411 "compute the gradient, if a derived class does not override "
412 "the 'gradient()' function and it is called anyway, then the "
413 "default implementation in the base class will simply throw "
414 "an exception."
415 "\n\n"
416 "The exception you see is what happens in cases such as the "
417 "one just illustrated. To fix the problem, you need to "
418 "investigate whether the function being called should indeed have "
419 "been called; if the answer is 'yes', then you need to "
420 "implement the missing override in your class.");
421
422 /**
423 * This exception is used if some user function is not provided.
424 */
425 DeclException1(ExcFunctionNotProvided,
426 std::string,
427 << "Please provide an implementation for the function \""
428 << arg1 << "\"");
429
430 /**
431 * This exception is used if some user function returns nonzero exit codes.
432 */
433 DeclException2(
434 ExcFunctionNonzeroReturn,
435 std::string,
436 int,
437 << "The function \"" << arg1 << "\" returned the nonzero value " << arg2
438 << ", but the calling site expected the return value to be zero. "
439 "This error often happens when the function in question is a 'callback', "
440 "that is a user-provided function called from somewhere within deal.II "
441 "or within an external library such as PETSc, Trilinos, SUNDIALS, etc., "
442 "that expect these callbacks to indicate errors via nonzero return "
443 "codes.");
444
445 /**
446 * This exception is used if some object is found uninitialized.
447 */
448 DeclException0(ExcNotInitialized);
449
450 /**
451 * The object is in a state not suitable for this operation.
452 */
453 DeclException0(ExcInvalidState);
454
455 /**
456 * This exception is raised if a functionality is not possible in the given
457 * dimension. Mostly used to throw function calls in 1d.
458 *
459 * The constructor takes a single <tt>int</tt>, denoting the dimension.
460 */
461 DeclException1(ExcImpossibleInDim,
462 int,
463 << "You are trying to execute functionality that is "
464 << "impossible in " << arg1
465 << "d or simply does not make any sense.");
466
467 /**
468 * This exception is raised if a functionality is not possible in the given
469 * combination of dimension and space-dimension.
470 *
471 * The constructor takes two <tt>int</tt>, denoting the dimension and the
472 * space dimension.
473 */
474 DeclException2(ExcImpossibleInDimSpacedim,
475 int,
476 int,
477 << "You are trying to execute functionality that is "
478 << "impossible in dimensions <" << arg1 << ',' << arg2
479 << "> or simply does not make any sense.");
480
481
482 /**
483 * A number is zero, but it should not be here.
484 */
485 DeclExceptionMsg(ExcZero,
486 "In a check in the code, deal.II encountered a zero in "
487 "a place where this does not make sense. See the condition "
488 "that was being checked and that is printed further up "
489 "in the error message to get more information on what "
490 "the erroneous zero corresponds to.");
491
492 /**
493 * The object should have been filled with something before this member
494 * function is called.
495 */
496 DeclExceptionMsg(ExcEmptyObject,
497 "The object you are trying to access is empty but it makes "
498 "no sense to attempt the operation you are trying on an "
499 "empty object.");
500
501 /**
502 * This exception is raised whenever the sizes of two objects were assumed
503 * to be equal, but were not.
504 *
505 * Parameters to the constructor are the first and second size, both of type
506 * <tt>int</tt>.
507 */
508 DeclException2(ExcDimensionMismatch,
509 std::size_t,
510 std::size_t,
511 << "Two sizes or dimensions were supposed to be equal, "
512 << "but aren't. They are " << arg1 << " and " << arg2 << '.');
513
514 /**
515 * This exception is raised whenever deal.II cannot convert between integer
516 * types.
517 */
518 DeclException2(
519 ExcInvalidIntegerConversion,
520 long long,
521 long long,
522 << "Two integers should be equal to each other after a type conversion but "
523 << "aren't. A typical cause of this problem is that the integral types "
524 << "used by deal.II and an external library are different (e.g., one uses "
525 << "32-bit integers and the other uses 64-bit integers). The integers are "
526 << arg1 << " and " << arg2 << '.');
527
528 /**
529 * The first dimension should be either equal to the second or the third,
530 * but it is neither.
531 */
532 DeclException3(ExcDimensionMismatch2,
533 std::size_t,
534 std::size_t,
535 std::size_t,
536 << "The size or dimension of one object, " << arg1
537 << " was supposed to be "
538 << "equal to one of two values, but isn't. The two possible "
539 << "values are " << arg2 << " and " << arg3 << '.');
540
541 /**
542 * This exception indicates that an index is not within the expected range.
543 * For example, it may be that you are trying to access an element of a
544 * vector which does not exist.
545 *
546 * The constructor takes three <tt>std::size_t</tt> arguments, namely
547 * <ol>
548 * <li> the violating index
549 * <li> the lower bound
550 * <li> the upper bound plus one
551 * </ol>
552 */
553 DeclException3(
554 ExcIndexRange,
555 std::size_t,
556 std::size_t,
557 std::size_t,
558 << "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
559 << arg3 << ")."
560 << (arg2 == arg3 ?
561 " In the current case, this half-open range is in fact empty, "
562 "suggesting that you are accessing an element of an empty "
563 "collection such as a vector that has not been set to the "
564 "correct size." :
565 ""));
566
567 /**
568 * This exception indicates that an index is not within the expected range.
569 * For example, it may be that you are trying to access an element of a
570 * vector which does not exist.
571 *
572 * The constructor takes three arguments, namely
573 * <ol>
574 * <li> the violating index
575 * <li> the lower bound
576 * <li> the upper bound plus one
577 * </ol>
578 *
579 * This generic exception differs from ExcIndexRange by allowing to specify
580 * the type of indices.
581 */
582 template <typename T>
583 DeclException3(
584 ExcIndexRangeType,
585 T,
586 T,
587 T,
588 << "Index " << arg1 << " is not in the half-open range [" << arg2 << ','
589 << arg3 << ")."
590 << (arg2 == arg3 ?
591 " In the current case, this half-open range is in fact empty, "
592 "suggesting that you are accessing an element of an empty "
593 "collection such as a vector that has not been set to the "
594 "correct size." :
595 ""));
596
597 /**
598 * A number is too small.
599 */
600 DeclException2(ExcLowerRange,
601 int,
602 int,
603 << "Number " << arg1 << " must be larger than or equal "
604 << arg2 << '.');
605
606 /**
607 * A generic exception definition for the ExcLowerRange above.
608 */
609 template <typename T>
610 DeclException2(ExcLowerRangeType,
611 T,
612 T,
613 << "Number " << arg1 << " must be larger than or equal "
614 << arg2 << '.');
615
616 /**
617 * This exception indicates that the first argument should be an integer
618 * multiple of the second, but is not.
619 */
620 DeclException2(ExcNotMultiple,
621 int,
622 int,
623 << "Division " << arg1 << " by " << arg2
624 << " has remainder different from zero.");
625
626 /**
627 * This exception is thrown if the iterator you access has corrupted data.
628 * It might for instance be, that the container it refers does not have an
629 * entry at the point the iterator refers.
630 *
631 * Typically, this will be an internal error of deal.II, because the
632 * increment and decrement operators should never yield an invalid iterator.
633 */
634 DeclExceptionMsg(ExcInvalidIterator,
635 "You are trying to use an iterator, but the iterator is "
636 "in an invalid state. This may indicate that the iterator "
637 "object has not been initialized, or that it has been "
638 "moved beyond the end of the range of valid elements.");
639
640 /**
641 * This exception is thrown if the iterator you incremented or decremented
642 * was already at its final state.
643 */
644 DeclExceptionMsg(ExcIteratorPastEnd,
645 "You are trying to use an iterator, but the iterator is "
646 "pointing past the end of the range of valid elements. "
647 "It is not valid to dereference the iterator in this "
648 "case.");
649
650 /**
651 * This exception works around a design flaw in the <tt>DeclException0</tt>
652 * macro: exceptions declared through DeclException0 do not allow one to
653 * specify a message that is displayed when the exception is raised, as
654 * opposed to the other exceptions which allow to show a text along with the
655 * given parameters.
656 *
657 * When throwing this exception, you can give a message as a
658 * <tt>std::string</tt> as argument to the exception that is then displayed.
659 * The argument can, of course, be constructed at run-time, for example
660 * including the name of a file that can't be opened, or any other text you
661 * may want to assemble from different pieces.
662 */
663 DeclException1(ExcMessage, std::string, << arg1);
664
665 /**
666 * Parallel vectors with ghost elements are read-only vectors.
667 */
668 DeclExceptionMsg(ExcGhostsPresent,
669 "You are trying an operation on a vector that is only "
670 "allowed if the vector has no ghost elements, but the "
671 "vector you are operating on does have ghost elements."
672 "\n\n"
673 "Specifically, there are two kinds of operations that "
674 "are typically not allowed on vectors with ghost elements. "
675 "First, vectors with ghost elements are read-only "
676 "and cannot appear in operations that write into these "
677 "vectors. Second, reduction operations (such as computing "
678 "the norm of a vector, or taking dot products between "
679 "vectors) are not allowed to ensure that each vector "
680 "element is counted only once (as opposed to once for "
681 "the owner of the element plus once for each process "
682 "on which the element is stored as a ghost copy)."
683 "\n\n"
684 "See the glossary entry on 'Ghosted vectors' for more "
685 "information.");
686
687 /**
688 * Exception indicating that one of the cells in the input to
689 * Triangulation::create_triangulation() or a related function cannot be used.
690 */
691 DeclException1(ExcGridHasInvalidCell,
692 int,
693 << "Something went wrong when making cell " << arg1
694 << ". Read the docs and the source code "
695 << "for more information.");
696
697 /**
698 * Some of our numerical classes allow for setting all entries to zero using
699 * the assignment operator <tt>=</tt>.
700 *
701 * In many cases, this assignment operator makes sense <b>only</b> for the
702 * argument zero. In other cases, this exception is thrown.
703 */
704 DeclExceptionMsg(ExcScalarAssignmentOnlyForZeroValue,
705 "You are trying an operation of the form 'vector = C', "
706 "'matrix = C', or 'tensor = C' with a nonzero scalar value "
707 "'C'. However, such assignments are only allowed if the "
708 "C is zero, since the semantics for assigning any other "
709 "value are not clear. For example: one could interpret "
710 "assigning a matrix a value of 1 to mean the matrix has a "
711 "norm of 1, the matrix is the identity matrix, or the "
712 "matrix contains only 1s. Similar problems exist with "
713 "vectors and tensors. Hence, to avoid this ambiguity, such "
714 "assignments are not permitted.");
715
716 /**
717 * This function requires support for the LAPACK library.
718 */
719 DeclExceptionMsg(
720 ExcNeedsLAPACK,
721 "You are attempting to use functionality that is only available "
722 "if deal.II was configured to use LAPACK, but when you configured "
723 "the library, cmake did not find a valid LAPACK library."
724 "\n\n"
725 "You will have to ensure that your system has a usable LAPACK "
726 "installation and re-install deal.II, making sure that cmake "
727 "finds the LAPACK installation. You can check this by "
728 "looking at the summary printed at the end of the cmake "
729 "output.");
730
731 /**
732 * This function requires support for the HDF5 library.
733 */
734 DeclExceptionMsg(
735 ExcNeedsHDF5,
736 "You are attempting to use functionality that requires that deal.II is configured "
737 "with HDF5 support. However, when you called 'cmake', HDF5 support "
738 "was not detected."
739 "\n\n"
740 "You will have to ensure that your system has a usable HDF5 "
741 "installation and re-install deal.II, making sure that cmake "
742 "finds the HDF5 installation. You can check this by "
743 "looking at the summary printed at the end of the cmake "
744 "output.");
745
746 /**
747 * This function requires support for the MPI library.
748 */
749 DeclExceptionMsg(
750 ExcNeedsMPI,
751 "You are attempting to use functionality that is only available "
752 "if deal.II was configured to use MPI."
753 "\n\n"
754 "You will have to ensure that your system has a usable MPI "
755 "installation and re-install deal.II, making sure that cmake "
756 "finds the MPI installation. You can check this by "
757 "looking at the summary printed at the end of the cmake "
758 "output.");
759
760 /**
761 * This function requires support for the FunctionParser library.
762 */
763 DeclExceptionMsg(
764 ExcNeedsFunctionparser,
765 "You are attempting to use functionality that is only available "
766 "if deal.II was configured to use the function parser which "
767 "relies on the muparser library, but cmake did not "
768 "find a valid muparser library on your system and also did "
769 "not choose the one that comes bundled with deal.II."
770 "\n\n"
771 "You will have to ensure that your system has a usable muparser "
772 "installation and re-install deal.II, making sure that cmake "
773 "finds the muparser installation. You can check this by "
774 "looking at the summary printed at the end of the cmake "
775 "output.");
776
777
778 /**
779 * This function requires support for the Assimp library.
780 */
781 DeclExceptionMsg(
782 ExcNeedsAssimp,
783 "You are attempting to use functionality that is only available "
784 "if deal.II was configured to use Assimp, but cmake did not "
785 "find a valid Assimp library."
786 "\n\n"
787 "You will have to ensure that your system has a usable Assimp "
788 "installation and re-install deal.II, making sure that cmake "
789 "finds the Assimp installation. You can check this by "
790 "looking at the summary printed at the end of the cmake "
791 "output.");
792
793 /**
794 * This function requires support for the Exodus II library.
795 */
796 DeclExceptionMsg(
797 ExcNeedsExodusII,
798 "You are attempting to use functionality that is only available if deal.II "
799 "was configured to use Trilinos' SEACAS library (which provides ExodusII), "
800 "but cmake did not find a valid SEACAS library."
801 "\n\n"
802 "You will have to ensure that your system has a usable ExodusII "
803 "installation and re-install deal.II, making sure that cmake "
804 "finds the ExodusII installation. You can check this by "
805 "looking at the summary printed at the end of the cmake "
806 "output.");
807
808 /**
809 * This function requires support for the CGAL library.
810 */
811 DeclExceptionMsg(
812 ExcNeedsCGAL,
813 "You are attempting to use functionality that is only available "
814 "if deal.II was configured to use CGAL, but cmake did not "
815 "find a valid CGAL library."
816 "\n\n"
817 "You will have to ensure that your system has a usable CGAL "
818 "installation and re-install deal.II, making sure that cmake "
819 "finds the CGAL installation. You can check this by "
820 "looking at the summary printed at the end of the cmake "
821 "output.");
822
823 #ifdef DEAL_II_WITH_MPI
824 /**
825 * Exception for MPI errors. This exception is only defined if
826 * <code>deal.II</code> is compiled with MPI support. This exception should
827 * be used with <code>AssertThrow</code> to check error codes of MPI
828 * functions. For example:
829 * @code
830 * const int ierr = MPI_Isend(...);
831 * AssertThrow(ierr == MPI_SUCCESS, ExcMPI(ierr));
832 * @endcode
833 * or, using the convenience macro <code>AssertThrowMPI</code>,
834 * @code
835 * const int ierr = MPI_Irecv(...);
836 * AssertThrowMPI(ierr);
837 * @endcode
838 *
839 * If the assertion fails then the error code will be used to print a helpful
840 * message to the screen by utilizing the <code>MPI_Error_string</code>
841 * function.
842 *
843 * @ingroup Exceptions
844 */
845 class ExcMPI : public dealii::ExceptionBase
846 {
847 public:
848 ExcMPI(const int error_code);
849
850 virtual void
851 print_info(std::ostream &out) const override;
852
853 const int error_code;
854 };
855 #endif // DEAL_II_WITH_MPI
856
857
858
859 #ifdef DEAL_II_TRILINOS_WITH_SEACAS
860 /**
861 * Exception for ExodusII errors. This exception is only defined if
862 * <code>deal.II</code> is compiled with SEACAS support, which is available
863 * through Trilinos. This function should be used with the convenience macro
864 * AssertThrowExodusII.
865 *
866 * @ingroup Exceptions
867 */
868 class ExcExodusII : public ExceptionBase
869 {
870 public:
871 /**
872 * Constructor.
873 *
874 * @param error_code The error code returned by an ExodusII function.
875 */
876 ExcExodusII(const int error_code);
877
878 /**
879 * Print a description of the error to the given stream.
880 */
881 virtual void
882 print_info(std::ostream &out) const override;
883
884 /**
885 * Store the error code.
886 */
887 const int error_code;
888 };
889 #endif // DEAL_II_TRILINOS_WITH_SEACAS
890
891 /**
892 * An exception to be thrown in user call-backs. See the glossary entry
893 * on user call-back functions for more information.
894 */
895 DeclExceptionMsg(
896 RecoverableUserCallbackError,
897 "A user call-back function encountered a recoverable error, "
898 "but the underlying library that called the call-back did not "
899 "manage to recover from the error and aborted its operation."
900 "\n\n"
901 "See the glossary entry on user call-back functions for more "
902 "information.");
903
904 /** @} */
905
906 } /*namespace StandardExceptions*/
907
908
909
910 /**
911 * In this namespace, functions in connection with the Assert and AssertThrow
912 * mechanism are declared.
913 *
914 * @ingroup Exceptions
915 */
916 namespace deal_II_exceptions
917 {
918 namespace internals
919 {
920 /**
921 * Setting this variable to false will disable deal.II's exception mechanism
922 * to abort the problem. The Assert() macro will throw the exception instead
923 * and the AssertNothrow() macro will just print the error message. This
924 * variable should not be changed directly. Use disable_abort_on_exception()
925 * instead.
926 */
927 extern bool allow_abort_on_exception;
928 } // namespace internals
929
930 /**
931 * Set a string that is printed upon output of the message indicating a
932 * triggered <tt>Assert</tt> statement. This string, which is printed in
933 * addition to the usual output may indicate information that is otherwise
934 * not readily available unless we are using a debugger. For example, with
935 * distributed programs on cluster computers, the output of all processes is
936 * redirected to the same console window. In this case, it is convenient to
937 * set as additional name the name of the host on which the program runs, so
938 * that one can see in which instance of the program the exception occurred.
939 *
940 * The string pointed to by the argument is copied, so doesn't need to be
941 * stored after the call to this function.
942 *
943 * Previously set additional output is replaced by the argument given to
944 * this function.
945 *
946 * @see Exceptions
947 */
948 void
949 set_additional_assert_output(const char *const p);
950
951 /**
952 * Calling this function disables printing a stacktrace along with the other
953 * output printed when an exception occurs. Most of the time, you will want
954 * to see such a stacktrace; suppressing it, however, is useful if one wants
955 * to compare the output of a program across different machines and systems,
956 * since the stacktrace shows memory addresses and library names/paths that
957 * depend on the exact setup of a machine.
958 *
959 * @see Exceptions
960 */
961 void
962 suppress_stacktrace_in_exceptions();
963
964 /**
965 * Calling this function switches off the use of <tt>std::abort()</tt> when
966 * an exception is created using the Assert() macro. Instead, the Exception
967 * will be thrown using 'throw', so it can be caught if desired. Generally,
968 * you want to abort the execution of a program when Assert() is called, but
969 * it needs to be switched off if you want to log all exceptions created, or
970 * if you want to test if an assertion is working correctly. This is done
971 * for example in regression tests. Please note that some fatal errors will
972 * still call abort(), e.g. when an exception is caught during exception
973 * handling.
974 *
975 * @see enable_abort_on_exception
976 * @see Exceptions
977 */
978 void
979 disable_abort_on_exception();
980
981 /**
982 * Calling this function switches on the use of <tt>std::abort()</tt> when
983 * an exception is created using the Assert() macro, instead of throwing it.
984 * This restores the standard behavior.
985 *
986 * @see disable_abort_on_exception
987 * @see Exceptions
988 */
989 void
990 enable_abort_on_exception();
991
992 /**
993 * The functions in this namespace are in connection with the Assert and
994 * AssertThrow mechanism but are solely for internal purposes and are not
995 * for use outside the exception handling and throwing mechanism.
996 *
997 * @ingroup Exceptions
998 */
999 namespace internals
1000 {
1001 /**
1002 * Abort the program by printing the
1003 * error message provided by @p exc and calling <tt>std::abort()</tt>.
1004 */
1005 [[noreturn]] void
1006 abort(const ExceptionBase &exc) noexcept;
1007
1008 /**
1009 * An enum describing how to treat an exception in issue_error_noreturn.
1010 */
1011 enum class ExceptionHandling
1012 {
1013 /**
1014 * Abort the program by calling <code>std::abort</code> unless
1015 * deal_II_exceptions::disable_abort_on_exception has been called: in
1016 * that case the program will throw an exception.
1017 */
1018 abort_or_throw_on_exception,
1019 /**
1020 * Throw the exception normally.
1021 */
1022 throw_on_exception
1023 };
1024
1025 /**
1026 * This routine does the main work for the exception generation mechanism
1027 * used in the <tt>Assert</tt> and <tt>AssertThrow</tt> macros: as the
1028 * name implies, this function either ends by throwing an exception (if
1029 * @p handling is ExceptionHandling::throw_on_exception, or @p handling is try_abort_exception
1030 * and deal_II_exceptions::disable_abort_on_exception is false) or with a
1031 * call to <tt>abort</tt> (if @p handling is try_abort_exception and
1032 * deal_II_exceptions::disable_abort_on_exception is true).
1033 *
1034 * The actual exception object (the last argument) is typically an unnamed
1035 * object created in place; because we modify it, we can't take it by
1036 * const reference, and temporaries don't bind to non-const references.
1037 * So take it by value (=copy it) with a templated type to avoid slicing
1038 * -- the performance implications are pretty minimal anyway.
1039 *
1040 * @ref ExceptionBase
1041 */
1042 template <typename ExceptionType>
1043 [[noreturn]] void
1044 issue_error_noreturn(ExceptionHandling handling,
1045 const char *file,
1046 int line,
1047 const char *function,
1048 const char *cond,
1049 const char *exc_name,
1050 ExceptionType e)
1051 {
1052 static_assert(std::is_base_of_v<ExceptionBase, ExceptionType>,
1053 "The provided exception must inherit from ExceptionBase.");
1054 // Fill the fields of the exception object
1055 e.set_fields(file, line, function, cond, exc_name);
1056
1057 switch (handling)
1058 {
1059 case ExceptionHandling::abort_or_throw_on_exception:
1060 {
1061 if (dealii::deal_II_exceptions::internals::
1062 allow_abort_on_exception)
1063 internals::abort(e);
1064 else
1065 {
1066 // We are not allowed to abort, so just throw the error:
1067 throw e;
1068 }
1069 }
1070 case ExceptionHandling::throw_on_exception:
1071 throw e;
1072 // this function should never return (and AssertNothrow can);
1073 // something must have gone wrong in the error handling code for us
1074 // to get this far, so throw an exception.
1075 default:
1076 throw ::dealii::StandardExceptions::ExcInternalError();
1077 }
1078 }
1079
1080 /**
1081 * Internal function that does the work of issue_error_nothrow.
1082 */
1083 void
1084 do_issue_error_nothrow(const ExceptionBase &e) noexcept;
1085
1086 /**
1087 * Exception generation mechanism in case we must not throw.
1088 *
1089 * @ref ExceptionBase
1090 *
1091 * @note This function is defined with a template for the same reasons as
1092 * issue_error_noreturn().
1093 */
1094 template <typename ExceptionType>
1095 void
1096 issue_error_nothrow(const char *file,
1097 int line,
1098 const char *function,
1099 const char *cond,
1100 const char *exc_name,
1101 ExceptionType e) noexcept
1102 {
1103 static_assert(std::is_base_of_v<ExceptionBase, ExceptionType>,
1104 "The provided exception must inherit from ExceptionBase.");
1105 // Fill the fields of the exception object
1106 e.set_fields(file, line, function, cond, exc_name);
1107 // avoid moving a bunch of code into the header by dispatching to
1108 // another function:
1109 do_issue_error_nothrow(e);
1110 }
1111 } /*namespace internals*/
1112
1113 } /*namespace deal_II_exceptions*/
1114
1115
1116
1117 namespace deal_II_exceptions
1118 {
1119 namespace internals
1120 {
1121 /**
1122 * A function that compares two values for equality, after converting to a
1123 * common type to avoid compiler warnings when comparing objects of
1124 * different types (e.g., unsigned and signed variables).
1125 */
1126 template <typename T, typename U>
1127 inline DEAL_II_HOST_DEVICE constexpr bool
1128 compare_for_equality(const T &t, const U &u)
1129 {
1130 using common_type = std::common_type_t<T, U>;
1131 return static_cast<common_type>(t) == static_cast<common_type>(u);
1132 }
1133
1134
1135 /**
1136 * A function that compares two values with `operator<`, after converting to
1137 * a common type to avoid compiler warnings when comparing objects of
1138 * different types (e.g., unsigned and signed variables).
1139 */
1140 template <typename T, typename U>
1141 inline DEAL_II_HOST_DEVICE constexpr bool
1142 compare_less_than(const T &t, const U &u)
1143 {
1144 using common_type = std::common_type_t<T, U>;
1145 return (static_cast<common_type>(t) < static_cast<common_type>(u));
1146 }
1147 } // namespace internals
1148 } // namespace deal_II_exceptions
1149
1150
1151
1152 namespace internal
1153 {
1154 // Workaround to allow for commas in template parameter lists
1155 // in preprocessor macros as found in
1156 // https://stackoverflow.com/questions/13842468/comma-in-c-c-macro
1157 template <typename F>
1158 struct argument_type;
1159
1160 template <typename T, typename U>
1161 struct argument_type<T(U)>
1162 {
1163 using type = U;
1164 };
1165
1166 template <typename F>
1167 using argument_type_t = typename argument_type<F>::type;
1168 } // namespace internal
1169
1170
1171 using namespace StandardExceptions;
1172
1173 DEAL_II_NAMESPACE_CLOSE
1174
1175 #endif