Debian Codegraph @

include/deal.II/base/exception_macros.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2012 - 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_exception_macros_h
16 #define dealii_exception_macros_h
17
18 #include <deal.II/base/config.h>
19
20
21 /**********************************************************************
22 * Preprocessor definitions in support of declaring exception classes.
23 *
24 * These make reference to classes and functions that are declared in
25 * exceptions.h. This is ok as far as concerning preprocessor defines
26 * is concerned, but in order to use the material below, you also need
27 * to have `#include <deal.II/base/exceptions.h>`.
28 */
29 #ifndef DOXYGEN
30
31 /**
32 * Declare an exception class derived from ExceptionBase without parameters.
33 *
34 * @note This and similar macro names are examples of preprocessor definitions
35 * in the deal.II library that are not prefixed by a string that likely makes
36 * them unique to deal.II. As a consequence, it is possible that other
37 * libraries your code interfaces with define the same name, and the result
38 * will be name collisions (see
39 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
40 * this macro, as well as all other macros defined by deal.II that are not
41 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
42 * the header <code>deal.II/base/undefine_macros.h</code> after all other
43 * deal.II headers have been included.
44 *
45 * @ingroup Exceptions
46 */
47 # define DeclException0(Exception0) \
48 class Exception0 : public dealii::ExceptionBase \
49 {}
50
51
52 /**
53 * Declare an exception class derived from ExceptionBase that can take one
54 * runtime argument, but if none is given in the place where you want to throw
55 * the exception, it simply reverts to the default text provided when
56 * declaring the exception class through this macro.
57 *
58 * @note This and similar macro names are examples of preprocessor definitions
59 * in the deal.II library that are not prefixed by a string that likely makes
60 * them unique to deal.II. As a consequence, it is possible that other
61 * libraries your code interfaces with define the same name, and the result
62 * will be name collisions (see
63 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
64 * this macro, as well as all other macros defined by deal.II that are not
65 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
66 * the header <code>deal.II/base/undefine_macros.h</code> after all other
67 * deal.II headers have been included.
68 *
69 * @ingroup Exceptions
70 */
71 # define DeclExceptionMsg(Exception, defaulttext) \
72 class Exception : public dealii::ExceptionBase \
73 { \
74 public: \
75 Exception(const std::string &msg = defaulttext) \
76 : arg(msg) \
77 {} \
78 virtual ~Exception() noexcept \
79 {} \
80 virtual void \
81 print_info(std::ostream &out) const override \
82 { \
83 out << " " << arg << std::endl; \
84 } \
85 \
86 private: \
87 const std::string arg; \
88 }
89
90 /**
91 * Declare an exception class derived from ExceptionBase with one additional
92 * parameter.
93 *
94 * @note This and similar macro names are examples of preprocessor definitions
95 * in the deal.II library that are not prefixed by a string that likely makes
96 * them unique to deal.II. As a consequence, it is possible that other
97 * libraries your code interfaces with define the same name, and the result
98 * will be name collisions (see
99 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
100 * this macro, as well as all other macros defined by deal.II that are not
101 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
102 * the header <code>deal.II/base/undefine_macros.h</code> after all other
103 * deal.II headers have been included.
104 *
105 * @ingroup Exceptions
106 */
107 # define DeclException1(Exception1, type1, outsequence) \
108 class Exception1 : public dealii::ExceptionBase \
109 { \
110 public: \
111 Exception1(type1 const &a1) \
112 : arg1(a1) \
113 {} \
114 virtual ~Exception1() noexcept \
115 {} \
116 virtual void \
117 print_info(std::ostream &out) const override \
118 { \
119 out << " " outsequence << std::endl; \
120 } \
121 \
122 private: \
123 type1 const arg1; \
124 }
125
126
127 /**
128 * Declare an exception class derived from ExceptionBase with two additional
129 * parameters.
130 *
131 * @note This and similar macro names are examples of preprocessor definitions
132 * in the deal.II library that are not prefixed by a string that likely makes
133 * them unique to deal.II. As a consequence, it is possible that other
134 * libraries your code interfaces with define the same name, and the result
135 * will be name collisions (see
136 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
137 * this macro, as well as all other macros defined by deal.II that are not
138 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
139 * the header <code>deal.II/base/undefine_macros.h</code> after all other
140 * deal.II headers have been included.
141 *
142 * @ingroup Exceptions
143 */
144 # define DeclException2(Exception2, type1, type2, outsequence) \
145 class Exception2 : public dealii::ExceptionBase \
146 { \
147 public: \
148 Exception2(type1 const &a1, type2 const &a2) \
149 : arg1(a1) \
150 , arg2(a2) \
151 {} \
152 virtual ~Exception2() noexcept \
153 {} \
154 virtual void \
155 print_info(std::ostream &out) const override \
156 { \
157 out << " " outsequence << std::endl; \
158 } \
159 \
160 private: \
161 type1 const arg1; \
162 type2 const arg2; \
163 }
164
165
166 /**
167 * Declare an exception class derived from ExceptionBase with three additional
168 * parameters.
169 *
170 * @note This and similar macro names are examples of preprocessor definitions
171 * in the deal.II library that are not prefixed by a string that likely makes
172 * them unique to deal.II. As a consequence, it is possible that other
173 * libraries your code interfaces with define the same name, and the result
174 * will be name collisions (see
175 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
176 * this macro, as well as all other macros defined by deal.II that are not
177 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
178 * the header <code>deal.II/base/undefine_macros.h</code> after all other
179 * deal.II headers have been included.
180 *
181 * @ingroup Exceptions
182 */
183 # define DeclException3(Exception3, type1, type2, type3, outsequence) \
184 class Exception3 : public dealii::ExceptionBase \
185 { \
186 public: \
187 Exception3(type1 const &a1, type2 const &a2, type3 const &a3) \
188 : arg1(a1) \
189 , arg2(a2) \
190 , arg3(a3) \
191 {} \
192 virtual ~Exception3() noexcept \
193 {} \
194 virtual void \
195 print_info(std::ostream &out) const override \
196 { \
197 out << " " outsequence << std::endl; \
198 } \
199 \
200 private: \
201 type1 const arg1; \
202 type2 const arg2; \
203 type3 const arg3; \
204 }
205
206
207 /**
208 * Declare an exception class derived from ExceptionBase with four additional
209 * parameters.
210 *
211 * @note This and similar macro names are examples of preprocessor definitions
212 * in the deal.II library that are not prefixed by a string that likely makes
213 * them unique to deal.II. As a consequence, it is possible that other
214 * libraries your code interfaces with define the same name, and the result
215 * will be name collisions (see
216 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
217 * this macro, as well as all other macros defined by deal.II that are not
218 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
219 * the header <code>deal.II/base/undefine_macros.h</code> after all other
220 * deal.II headers have been included.
221 *
222 * @ingroup Exceptions
223 */
224 # define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
225 class Exception4 : public dealii::ExceptionBase \
226 { \
227 public: \
228 Exception4(type1 const &a1, \
229 type2 const &a2, \
230 type3 const &a3, \
231 type4 const &a4) \
232 : arg1(a1) \
233 , arg2(a2) \
234 , arg3(a3) \
235 , arg4(a4) \
236 {} \
237 virtual ~Exception4() noexcept \
238 {} \
239 virtual void \
240 print_info(std::ostream &out) const override \
241 { \
242 out << " " outsequence << std::endl; \
243 } \
244 \
245 private: \
246 type1 const arg1; \
247 type2 const arg2; \
248 type3 const arg3; \
249 type4 const arg4; \
250 }
251
252
253 /**
254 * Declare an exception class derived from ExceptionBase with five additional
255 * parameters.
256 *
257 * @note This and similar macro names are examples of preprocessor definitions
258 * in the deal.II library that are not prefixed by a string that likely makes
259 * them unique to deal.II. As a consequence, it is possible that other
260 * libraries your code interfaces with define the same name, and the result
261 * will be name collisions (see
262 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
263 * this macro, as well as all other macros defined by deal.II that are not
264 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
265 * the header <code>deal.II/base/undefine_macros.h</code> after all other
266 * deal.II headers have been included.
267 *
268 * @ingroup Exceptions
269 */
270 # define DeclException5( \
271 Exception5, type1, type2, type3, type4, type5, outsequence) \
272 class Exception5 : public dealii::ExceptionBase \
273 { \
274 public: \
275 Exception5(type1 const &a1, \
276 type2 const &a2, \
277 type3 const &a3, \
278 type4 const &a4, \
279 type5 const &a5) \
280 : arg1(a1) \
281 , arg2(a2) \
282 , arg3(a3) \
283 , arg4(a4) \
284 , arg5(a5) \
285 {} \
286 virtual ~Exception5() noexcept \
287 {} \
288 virtual void \
289 print_info(std::ostream &out) const override \
290 { \
291 out << " " outsequence << std::endl; \
292 } \
293 \
294 private: \
295 type1 const arg1; \
296 type2 const arg2; \
297 type3 const arg3; \
298 type4 const arg4; \
299 type5 const arg5; \
300 }
301
302 #else /*ifndef DOXYGEN*/
303
304 // Dummy definitions for doxygen:
305
306 /**
307 * Declare an exception class derived from ExceptionBase without parameters.
308 *
309 * @note This and similar macro names are examples of preprocessor definitions
310 * in the deal.II library that are not prefixed by a string that likely makes
311 * them unique to deal.II. As a consequence, it is possible that other
312 * libraries your code interfaces with define the same name, and the result
313 * will be name collisions (see
314 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
315 * this macro, as well as all other macros defined by deal.II that are not
316 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
317 * the header <code>deal.II/base/undefine_macros.h</code> after all other
318 * deal.II headers have been included.
319 *
320 * @ingroup Exceptions
321 */
322 # define DeclException0(Exception0) \
323 /** @ingroup Exceptions */ \
324 static dealii::ExceptionBase &Exception0()
325
326 /**
327 * Declare an exception class derived from ExceptionBase that can take one
328 * runtime argument, but if none is given in the place where you want to throw
329 * the exception, it simply reverts to the default text provided when
330 * declaring the exception class through this macro.
331 *
332 * @note This and similar macro names are examples of preprocessor definitions
333 * in the deal.II library that are not prefixed by a string that likely makes
334 * them unique to deal.II. As a consequence, it is possible that other
335 * libraries your code interfaces with define the same name, and the result
336 * will be name collisions (see
337 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
338 * this macro, as well as all other macros defined by deal.II that are not
339 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
340 * the header <code>deal.II/base/undefine_macros.h</code> after all other
341 * deal.II headers have been included.
342 *
343 * @ingroup Exceptions
344 */
345 # define DeclExceptionMsg(Exception, defaulttext) \
346 /** @ingroup Exceptions */ \
347 /** @dealiiExceptionMessage{defaulttext} */ \
348 static dealii::ExceptionBase &Exception()
349
350 /**
351 * Declare an exception class derived from ExceptionBase with one additional
352 * parameter.
353 *
354 * @note This and similar macro names are examples of preprocessor definitions
355 * in the deal.II library that are not prefixed by a string that likely makes
356 * them unique to deal.II. As a consequence, it is possible that other
357 * libraries your code interfaces with define the same name, and the result
358 * will be name collisions (see
359 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
360 * this macro, as well as all other macros defined by deal.II that are not
361 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
362 * the header <code>deal.II/base/undefine_macros.h</code> after all other
363 * deal.II headers have been included.
364 *
365 * @ingroup Exceptions
366 */
367 # define DeclException1(Exception1, type1, outsequence) \
368 /** @ingroup Exceptions */ \
369 /** @dealiiExceptionMessage{outsequence} */ \
370 static dealii::ExceptionBase &Exception1(type1 arg1)
371
372
373 /**
374 * Declare an exception class derived from ExceptionBase with two additional
375 * parameters.
376 *
377 * @note This and similar macro names are examples of preprocessor definitions
378 * in the deal.II library that are not prefixed by a string that likely makes
379 * them unique to deal.II. As a consequence, it is possible that other
380 * libraries your code interfaces with define the same name, and the result
381 * will be name collisions (see
382 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
383 * this macro, as well as all other macros defined by deal.II that are not
384 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
385 * the header <code>deal.II/base/undefine_macros.h</code> after all other
386 * deal.II headers have been included.
387 *
388 * @ingroup Exceptions
389 */
390 # define DeclException2(Exception2, type1, type2, outsequence) \
391 /** @ingroup Exceptions */ \
392 /** @dealiiExceptionMessage{outsequence} */ \
393 static dealii::ExceptionBase &Exception2(type1 arg1, type2 arg2)
394
395
396 /**
397 * Declare an exception class derived from ExceptionBase with three additional
398 * parameters.
399 *
400 * @note This and similar macro names are examples of preprocessor definitions
401 * in the deal.II library that are not prefixed by a string that likely makes
402 * them unique to deal.II. As a consequence, it is possible that other
403 * libraries your code interfaces with define the same name, and the result
404 * will be name collisions (see
405 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
406 * this macro, as well as all other macros defined by deal.II that are not
407 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
408 * the header <code>deal.II/base/undefine_macros.h</code> after all other
409 * deal.II headers have been included.
410 *
411 * @ingroup Exceptions
412 */
413 # define DeclException3(Exception3, type1, type2, type3, outsequence) \
414 /** @ingroup Exceptions */ \
415 /** @dealiiExceptionMessage{outsequence} */ \
416 static dealii::ExceptionBase &Exception3(type1 arg1, type2 arg2, type3 arg3)
417
418
419 /**
420 * Declare an exception class derived from ExceptionBase with four additional
421 * parameters.
422 *
423 * @note This and similar macro names are examples of preprocessor definitions
424 * in the deal.II library that are not prefixed by a string that likely makes
425 * them unique to deal.II. As a consequence, it is possible that other
426 * libraries your code interfaces with define the same name, and the result
427 * will be name collisions (see
428 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
429 * this macro, as well as all other macros defined by deal.II that are not
430 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
431 * the header <code>deal.II/base/undefine_macros.h</code> after all other
432 * deal.II headers have been included.
433 *
434 * @ingroup Exceptions
435 */
436 # define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
437 /** @ingroup Exceptions */ \
438 /** @dealiiExceptionMessage{outsequence} */ \
439 static dealii::ExceptionBase &Exception4(type1 arg1, \
440 type2 arg2, \
441 type3 arg3, \
442 type4 arg4)
443
444
445 /**
446 * Declare an exception class derived from ExceptionBase with five additional
447 * parameters.
448 *
449 * @note This and similar macro names are examples of preprocessor definitions
450 * in the deal.II library that are not prefixed by a string that likely makes
451 * them unique to deal.II. As a consequence, it is possible that other
452 * libraries your code interfaces with define the same name, and the result
453 * will be name collisions (see
454 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
455 * this macro, as well as all other macros defined by deal.II that are not
456 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
457 * the header <code>deal.II/base/undefine_macros.h</code> after all other
458 * deal.II headers have been included.
459 *
460 * @ingroup Exceptions
461 */
462 # define DeclException5( \
463 Exception5, type1, type2, type3, type4, type5, outsequence) \
464 /** @ingroup Exceptions */ \
465 /** @dealiiExceptionMessage{outsequence} */ \
466 static dealii::ExceptionBase &Exception5( \
467 type1 arg1, type2 arg2, type3 arg3, type4 arg4, type5 arg5)
468
469 #endif /*ifndef DOXYGEN*/
470
471
472
473 /**********************************************************************
474 * Preprocessor definitions in support of assertions.
475 *
476 * These make reference to classes and functions that are declared in
477 * exceptions.h. This is ok as far as concerning preprocessor defines
478 * is concerned, but in order to use the material below, you also need
479 * to have `#include <deal.II/base/exceptions.h>`.
480 */
481
482 /**
483 * Wrapper macro around __builtin_expect(). Only used in the assertion macros
484 * (Assert(), AssertNothrow(), and AssertThrow()).
485 */
486 #ifdef DEAL_II_HAVE_BUILTIN_EXPECT
487 # define DEAL_II_BUILTIN_EXPECT(a, b) __builtin_expect((a), (b))
488 #else
489 # define DEAL_II_BUILTIN_EXPECT(a, b) (a)
490 #endif
491
492
493 /**
494 * A macro that serves as the main routine in the exception mechanism for debug
495 * mode error checking. It asserts that a certain condition is fulfilled,
496 * otherwise issues an error and aborts the program.
497 *
498 * A more detailed description can be found in the
499 * @ref Exceptions
500 * topic. It is first used in step-5 and step-6.
501 * See also the <tt>ExceptionBase</tt> class for more information.
502 *
503 * @note Active in DEBUG mode only
504 *
505 * @note This and similar macro names are examples of preprocessor definitions
506 * in the deal.II library that are not prefixed by a string that likely makes
507 * them unique to deal.II. As a consequence, it is possible that other
508 * libraries your code interfaces with define the same name, and the result
509 * will be name collisions (see
510 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
511 * this macro, as well as all other macros defined by deal.II that are not
512 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
513 * the header <code>deal.II/base/undefine_macros.h</code> after all other
514 * deal.II headers have been included.
515 *
516 * @ingroup Exceptions
517 */
518 #ifdef DEBUG
519 # if DEAL_II_KOKKOS_VERSION_GTE(3, 6, 0)
520 # define Assert(cond, exc) \
521 do \
522 { \
523 KOKKOS_IF_ON_HOST(({ \
524 if (DEAL_II_BUILTIN_EXPECT(!(cond), false)) \
525 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \
526 ::dealii::deal_II_exceptions::internals::ExceptionHandling:: \
527 abort_or_throw_on_exception, \
528 __FILE__, \
529 __LINE__, \
530 __PRETTY_FUNCTION__, \
531 #cond, \
532 #exc, \
533 exc); \
534 })) \
535 KOKKOS_IF_ON_DEVICE(({ \
536 if (!(cond)) \
537 Kokkos::abort(#cond); \
538 })) \
539 } \
540 while (false)
541 # else /*if DEAL_II_KOKKOS_VERSION_GTE(3,6,0)*/
542 # ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST
543 # define Assert(cond, exc) \
544 do \
545 { \
546 if (DEAL_II_BUILTIN_EXPECT(!(cond), false)) \
547 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \
548 ::dealii::deal_II_exceptions::internals::ExceptionHandling:: \
549 abort_or_throw_on_exception, \
550 __FILE__, \
551 __LINE__, \
552 __PRETTY_FUNCTION__, \
553 #cond, \
554 #exc, \
555 exc); \
556 } \
557 while (false)
558 # else /*#ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
559 # define Assert(cond, exc) \
560 do \
561 { \
562 if (!(cond)) \
563 Kokkos::abort(#cond); \
564 } \
565 while (false)
566 # endif /*ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
567 # endif /*KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST*/
568 #else /*ifdef DEBUG*/
569 # define Assert(cond, exc) \
570 do \
571 { \
572 if (false) \
573 if (!(cond)) \
574 { \
575 } \
576 } \
577 while (false)
578 #endif /*ifdef DEBUG*/
579
580
581
582 /**
583 * A variant of the <tt>Assert</tt> macro above that exhibits the same runtime
584 * behavior as long as disable_abort_on_exception was not called.
585 *
586 * However, if disable_abort_on_exception was called, this macro merely prints
587 * the exception that would be thrown to deallog and continues normally
588 * without throwing an exception.
589 *
590 * A more detailed description can be found in the
591 * @ref Exceptions
592 * topic, in the discussion about the corner case at the bottom of the page.
593 *
594 * @note This and similar macro names are examples of preprocessor definitions
595 * in the deal.II library that are not prefixed by a string that likely makes
596 * them unique to deal.II. As a consequence, it is possible that other
597 * libraries your code interfaces with define the same name, and the result
598 * will be name collisions (see
599 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
600 * this macro, as well as all other macros defined by deal.II that are not
601 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
602 * the header <code>deal.II/base/undefine_macros.h</code> after all other
603 * deal.II headers have been included.
604 *
605 * @note Active in DEBUG mode only
606 * @ingroup Exceptions
607 */
608 #ifdef DEBUG
609 # define AssertNothrow(cond, exc) \
610 do \
611 { \
612 if (DEAL_II_BUILTIN_EXPECT(!(cond), false)) \
613 ::dealii::deal_II_exceptions::internals::issue_error_nothrow( \
614 __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
615 } \
616 while (false)
617 #else
618 # define AssertNothrow(cond, exc) \
619 do \
620 { \
621 if (false) \
622 if (!(cond)) \
623 { \
624 } \
625 } \
626 while (false)
627 #endif
628
629 /**
630 * A macro that serves as the main routine in the exception mechanism for
631 * dynamic error checking. It asserts that a certain condition is fulfilled,
632 * otherwise
633 * throws an exception via the C++ @p throw mechanism. This exception can
634 * be caught via a @p catch clause, as is shown in step-6 and all following
635 * tutorial programs.
636 *
637 * A more detailed description can be found in the
638 * @ref Exceptions
639 * topic. It is first used in step-9 and step-13.
640 * See also the <tt>ExceptionBase</tt> class for more information.
641 *
642 * @note This and similar macro names are examples of preprocessor definitions
643 * in the deal.II library that are not prefixed by a string that likely makes
644 * them unique to deal.II. As a consequence, it is possible that other
645 * libraries your code interfaces with define the same name, and the result
646 * will be name collisions (see
647 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
648 * this macro, as well as all other macros defined by deal.II that are not
649 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
650 * the header <code>deal.II/base/undefine_macros.h</code> after all other
651 * deal.II headers have been included.
652 *
653 * @note Active in both DEBUG and RELEASE modes
654 * @ingroup Exceptions
655 */
656 #define AssertThrow(cond, exc) \
657 do \
658 { \
659 if (DEAL_II_BUILTIN_EXPECT(!(cond), false)) \
660 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \
661 ::dealii::deal_II_exceptions::internals::ExceptionHandling:: \
662 throw_on_exception, \
663 __FILE__, \
664 __LINE__, \
665 __PRETTY_FUNCTION__, \
666 #cond, \
667 #exc, \
668 exc); \
669 } \
670 while (false)
671
672
673 /**
674 * `DEAL_II_NOT_IMPLEMENTED` is a macro (that looks like a function call
675 * when used as in `DEAL_II_NOT_IMPLEMENTED();`) that is used to raise an
676 * error in places where a piece of code is not yet implemented. If a code
677 * runs into such a place, it will be aborted with an error message that
678 * explains the situation, along with a backtrace of how the code ended
679 * up in this place. Alternatively, if
680 * deal_II_exceptions::internals::ExceptionHandling::abort_or_throw_on_exception
681 * is set to ExceptionHandling::throw_on_exception, then the corresponding
682 * error is thrown as a C++ exception that can be caught (though in
683 * many cases codes will then find it difficult to do what they wanted
684 * to do).
685 *
686 * This macro is first used in step-8 of the tutorial.
687 *
688 * A typical case where it is used would look as follows: Assume that we want
689 * to implement a function that describes the right hand side of an equation
690 * that corresponds to a known solution (i.e., we want to use the "Method
691 * of manufactured solutions", see step-7). We have computed the right
692 * hand side that corresponds to the 1d and 2d solutions, but we have been
693 * too lazy so far to do the calculations for the 3d case, perhaps because
694 * we first want to test correctness in 1d and 2d before moving on to the 3d
695 * case. We could then write this right hand side as follows (the specific
696 * formulas in the `return` statements are not important):
697 * @code
698 * template <int dim>
699 * double right_hand_side (const Point<dim> &x)
700 * {
701 * if (dim==1)
702 * return x[0]*std::sin(x[0]);
703 * else if (dim==2)
704 * return x[0]*std::sin(x[0])*std::sin(x[1];
705 * else
706 * DEAL_II_NOT_IMPLEMENTED();
707 * }
708 * @endcode
709 * Here, the call to `DEAL_II_NOT_IMPLEMENTED()` simply indicates that we
710 * haven't gotten around to filling in this code block. If someone ends up
711 * running the program in 3d, execution will abort in the location with an
712 * error message that indicates where this happened and why.
713 */
714 #define DEAL_II_NOT_IMPLEMENTED() \
715 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \
716 ::dealii::deal_II_exceptions::internals::ExceptionHandling:: \
717 abort_or_throw_on_exception, \
718 __FILE__, \
719 __LINE__, \
720 __PRETTY_FUNCTION__, \
721 nullptr, \
722 nullptr, \
723 ::dealii::StandardExceptions::ExcNotImplemented())
724
725
726 /**
727 * `DEAL_II_ASSERT_UNREACHABLE` is a macro (that looks like a function call
728 * when used as in `DEAL_II_ASSERT_UNREACHABLE();`) that is used to raise an
729 * error in places where the programmer believed that execution should
730 * never get to. If a code
731 * runs into such a place, it will be aborted with an error message that
732 * explains the situation, along with a backtrace of how the code ended
733 * up in this place. Alternatively, if
734 * deal_II_exceptions::internals::ExceptionHandling::abort_or_throw_on_exception
735 * is set to ExceptionHandling::throw_on_exception, then the corresponding
736 * error is thrown as a C++ exception that can be caught (though in
737 * many cases codes will then find it difficult to do what they wanted
738 * to do).
739 *
740 * A typical case where it is used would look as follows. In many cases,
741 * one has a finite enumeration of things that can happen, and one runs
742 * through those in a sequence of `if`-`else` blocks, or perhaps
743 * with a `switch` selection and a number of `case` statements. Of
744 * course, if the code is correct, if all possible cases are handled,
745 * nothing terrible can happen -- though perhaps it is worth making sure
746 * that we have really covered all cases by using `DEAL_II_ASSERT_UNREACHABLE()`
747 * as the *last* case. Here is an example:
748 * @code
749 * enum OutputFormat { vtk, vtu };
750 *
751 * void write_output (const OutputFormat format)
752 * {
753 * if (format == vtk)
754 * {
755 * ... write in VTK format ...
756 * }
757 * else // must not clearly be VTU format
758 * {
759 * ... write in VTU format ...
760 * }
761 * }
762 * @endcode
763 * The issue here is "Are we really sure it is VTU format if we end up in
764 * the `else` block"? There are two reasons that should make us suspicious.
765 * First, the authors of the code may later have expanded the list of options
766 * in the `OutputFormat` enum, but forgotten to also update the
767 * `write_output()` function. We may then end up in the `else` branch even
768 * though the argument indicates the now possible third option that was added
769 * to `OutputFormat`. The second possibility to consider is that enums are
770 * really just fancy ways of using integers; from a language perspective, it
771 * is allowed to pass *any* integer to `write_output()`, even values that do
772 * not match either `vtk` or `vtu`. This is then clearly a bug in the program,
773 * but one that we are better off if we catch it as early as possible.
774 *
775 * We can guard against both cases by writing the code as follows instead:
776 * @code
777 * enum OutputFormat { vtk, vtu };
778 *
779 * void write_output (const OutputFormat format)
780 * {
781 * if (format == vtk)
782 * {
783 * ... write in VTK format ...
784 * }
785 * else if (format == vtu)
786 * {
787 * ... write in VTU format ...
788 * }
789 * else // we shouldn't get here, but if we did, abort the program now!
790 * DEAL_II_ASSERT_UNREACHABLE();
791 * }
792 * @endcode
793 *
794 * This macro is first used in step-7, where we show another example of
795 * a context where it is frequently used.
796 */
797 #define DEAL_II_ASSERT_UNREACHABLE() \
798 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \
799 ::dealii::deal_II_exceptions::internals::ExceptionHandling:: \
800 abort_or_throw_on_exception, \
801 __FILE__, \
802 __LINE__, \
803 __PRETTY_FUNCTION__, \
804 nullptr, \
805 nullptr, \
806 ::dealii::StandardExceptions::ExcMessage( \
807 "The program has hit a line of code that the programmer " \
808 "marked with the macro DEAL_II_ASSERT_UNREACHABLE() to " \
809 "indicate that the program should never reach this " \
810 "location. You will have to find out (best done in a " \
811 "debugger) why that happened. Typical reasons include " \
812 "passing invalid arguments to functions (for example, if " \
813 "a function takes an 'enum' with two possible values " \
814 "as argument, but you call the function with a third " \
815 "value), or if the programmer of the code that triggered " \
816 "the error believed that a variable can only have " \
817 "specific values, but either that assumption is wrong " \
818 "or the computation of that value is buggy." \
819 "\n\n" \
820 "In those latter conditions, where some internal " \
821 "assumption is not satisfied, there may not be very " \
822 "much you can do if you encounter such an exception, " \
823 "since it indicates an error in deal.II, not in your " \
824 "own program. If that is the situation you encounter, " \
825 "try to come up with " \
826 "the smallest possible program that still demonstrates " \
827 "the error and contact the deal.II mailing lists with it " \
828 "to obtain help."))
829
830
831 /**
832 * Special assertion for dimension mismatch.
833 *
834 * Since this is used very often and always repeats the arguments, we
835 * introduce this special assertion for ExcDimensionMismatch in order to keep
836 * the user codes shorter.
837 *
838 * @note This and similar macro names are examples of preprocessor definitions
839 * in the deal.II library that are not prefixed by a string that likely makes
840 * them unique to deal.II. As a consequence, it is possible that other
841 * libraries your code interfaces with define the same name, and the result
842 * will be name collisions (see
843 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
844 * this macro, as well as all other macros defined by deal.II that are not
845 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
846 * the header <code>deal.II/base/undefine_macros.h</code> after all other
847 * deal.II headers have been included.
848 *
849 * @ingroup Exceptions
850 */
851 #define AssertDimension(dim1, dim2) \
852 Assert(::dealii::deal_II_exceptions::internals::compare_for_equality(dim1, \
853 dim2), \
854 dealii::ExcDimensionMismatch((dim1), (dim2)))
855
856 /**
857 * Special assertion for integer conversions.
858 *
859 * deal.II does not always use the same integer types as its dependencies. For
860 * example, PETSc uses signed integers whereas deal.II uses unsigned integers.
861 * This assertion checks that we can successfully convert between two index
862 * types.
863 */
864 #define AssertIntegerConversion(index1, index2) \
865 Assert(::dealii::deal_II_exceptions::internals::compare_for_equality( \
866 index1, index2), \
867 dealii::ExcInvalidIntegerConversion((index1), (index2)))
868
869 /**
870 * Special assertion for integer conversions which will throw exceptions.
871 * Otherwise this is the same as AssertIntegerConversion.
872 */
873 #define AssertThrowIntegerConversion(index1, index2) \
874 AssertThrow(::dealii::deal_II_exceptions::internals::compare_for_equality( \
875 index1, index2), \
876 dealii::ExcInvalidIntegerConversion((index1), (index2)))
877
878 /**
879 * An assertion that tests whether <tt>vec</tt> has size <tt>dim1</tt>, and
880 * each entry of the vector is itself an array that has the size <tt>dim2</tt>.
881 *
882 * @note This and similar macro names are examples of preprocessor definitions
883 * in the deal.II library that are not prefixed by a string that likely makes
884 * them unique to deal.II. As a consequence, it is possible that other
885 * libraries your code interfaces with define the same name, and the result
886 * will be name collisions (see
887 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
888 * this macro, as well as all other macros defined by deal.II that are not
889 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
890 * the header <code>deal.II/base/undefine_macros.h</code> after all other
891 * deal.II headers have been included.
892 *
893 * @ingroup Exceptions
894 */
895 #define AssertVectorVectorDimension(VEC, DIM1, DIM2) \
896 AssertDimension(VEC.size(), DIM1); \
897 for (const auto &subvector : VEC) \
898 { \
899 (void)subvector; \
900 AssertDimension(subvector.size(), DIM2); \
901 }
902
903
904 /**
905 * An assertion that tests that a given index is within the half-open
906 * range <code>[0,range)</code>. It throws an exception object
907 * <code>ExcIndexRange(index,0,range)</code> if the assertion
908 * fails.
909 *
910 * @note This and similar macro names are examples of preprocessor definitions
911 * in the deal.II library that are not prefixed by a string that likely makes
912 * them unique to deal.II. As a consequence, it is possible that other
913 * libraries your code interfaces with define the same name, and the result
914 * will be name collisions (see
915 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
916 * this macro, as well as all other macros defined by deal.II that are not
917 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
918 * the header <code>deal.II/base/undefine_macros.h</code> after all other
919 * deal.II headers have been included.
920 *
921 * @ingroup Exceptions
922 */
923 #define AssertIndexRange(index, range) \
924 Assert(::dealii::deal_II_exceptions::internals::compare_less_than(index, \
925 range), \
926 ::dealii::ExcIndexRangeType<::dealii::internal::argument_type_t<void( \
927 std::common_type_t<decltype(index), decltype(range)>)>>((index), \
928 0, \
929 (range)))
930
931 /**
932 * An assertion that checks whether a number is finite or not. We explicitly
933 * cast the number to std::complex to match the signature of the exception
934 * (see there for an explanation of why we use std::complex at all) and to
935 * satisfy the fact that std::complex has no implicit conversions.
936 *
937 * @note This and similar macro names are examples of preprocessor definitions
938 * in the deal.II library that are not prefixed by a string that likely makes
939 * them unique to deal.II. As a consequence, it is possible that other
940 * libraries your code interfaces with define the same name, and the result
941 * will be name collisions (see
942 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
943 * this macro, as well as all other macros defined by deal.II that are not
944 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
945 * the header <code>deal.II/base/undefine_macros.h</code> after all other
946 * deal.II headers have been included.
947 *
948 * @ingroup Exceptions
949 */
950 #define AssertIsFinite(number) \
951 Assert(dealii::numbers::is_finite(number), \
952 dealii::ExcNumberNotFinite(std::complex<double>(number)))
953
954 /**
955 * Assert that a geometric object is not used. This assertion is used when
956 * constructing triangulations and should normally not be used inside user
957 * codes.
958 */
959 #define AssertIsNotUsed(obj) Assert((obj)->used() == false, ExcInternalError())
960
961 #ifdef DEAL_II_WITH_MPI
962 /**
963 * An assertion that checks whether or not an error code returned by an MPI
964 * function is equal to <code>MPI_SUCCESS</code>. If the check fails then an
965 * exception of type ExcMPI is thrown with the given error code as an
966 * argument.
967 *
968 * @note This and similar macro names are examples of preprocessor definitions
969 * in the deal.II library that are not prefixed by a string that likely makes
970 * them unique to deal.II. As a consequence, it is possible that other
971 * libraries your code interfaces with define the same name, and the result
972 * will be name collisions (see
973 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
974 * this macro, as well as all other macros defined by deal.II that are not
975 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
976 * the header <code>deal.II/base/undefine_macros.h</code> after all other
977 * deal.II headers have been included.
978 *
979 * @note Active only if deal.II is compiled with MPI
980 * @ingroup Exceptions
981 */
982 # define AssertThrowMPI(error_code) \
983 AssertThrow(error_code == MPI_SUCCESS, dealii::ExcMPI(error_code))
984 #else
985 # define AssertThrowMPI(error_code) \
986 do \
987 { \
988 } \
989 while (false)
990 #endif // DEAL_II_WITH_MPI
991
992 #ifdef DEAL_II_TRILINOS_WITH_SEACAS
993 /**
994 * Assertion that checks that the error code produced by calling an ExodusII
995 * routine is equal to EX_NOERR (which is zero).
996 *
997 * @note This and similar macro names are examples of preprocessor definitions
998 * in the deal.II library that are not prefixed by a string that likely makes
999 * them unique to deal.II. As a consequence, it is possible that other
1000 * libraries your code interfaces with define the same name, and the result
1001 * will be name collisions (see
1002 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
1003 * this macro, as well as all other macros defined by deal.II that are not
1004 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
1005 * the header <code>deal.II/base/undefine_macros.h</code> after all other
1006 * deal.II headers have been included.
1007 *
1008 * @ingroup Exceptions
1009 */
1010 # define AssertThrowExodusII(error_code) \
1011 AssertThrow(error_code == 0, \
1012 dealii::StandardExceptions::ExcExodusII(error_code));
1013 #endif // DEAL_II_TRILINOS_WITH_SEACAS
1014
1015
1016 #ifdef DEAL_II_WITH_SUNDIALS
1017 /**
1018 * Assertion that checks that the error code produced by calling one
1019 * of SUNDIALS' ARKode functions.
1020 *
1021 * @note This and similar macro names are examples of preprocessor definitions
1022 * in the deal.II library that are not prefixed by a string that likely makes
1023 * them unique to deal.II. As a consequence, it is possible that other
1024 * libraries your code interfaces with define the same name, and the result
1025 * will be name collisions (see
1026 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
1027 * this macro, as well as all other macros defined by deal.II that are not
1028 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
1029 * the header <code>deal.II/base/undefine_macros.h</code> after all other
1030 * deal.II headers have been included.
1031 *
1032 * @ingroup Exceptions
1033 */
1034 # define AssertARKode(code) Assert(code >= 0, ExcARKodeError(code))
1035
1036 /**
1037 * Assertion that checks that the error code produced by calling one
1038 * of SUNDIALS' KINSOL functions.
1039 *
1040 * @note This and similar macro names are examples of preprocessor definitions
1041 * in the deal.II library that are not prefixed by a string that likely makes
1042 * them unique to deal.II. As a consequence, it is possible that other
1043 * libraries your code interfaces with define the same name, and the result
1044 * will be name collisions (see
1045 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
1046 * this macro, as well as all other macros defined by deal.II that are not
1047 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
1048 * the header <code>deal.II/base/undefine_macros.h</code> after all other
1049 * deal.II headers have been included.
1050 *
1051 * @ingroup Exceptions
1052 */
1053 # define AssertKINSOL(code) Assert(code >= 0, ExcKINSOLError(code))
1054
1055 /**
1056 * Assertion that checks that the error code produced by calling one
1057 * of SUNDIALS' IDA functions.
1058 *
1059 * @note This and similar macro names are examples of preprocessor definitions
1060 * in the deal.II library that are not prefixed by a string that likely makes
1061 * them unique to deal.II. As a consequence, it is possible that other
1062 * libraries your code interfaces with define the same name, and the result
1063 * will be name collisions (see
1064 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code>
1065 * this macro, as well as all other macros defined by deal.II that are not
1066 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including
1067 * the header <code>deal.II/base/undefine_macros.h</code> after all other
1068 * deal.II headers have been included.
1069 *
1070 * @ingroup Exceptions
1071 */
1072 # define AssertIDA(code) Assert(code >= 0, ExcIDAError(code))
1073 #endif
1074
1075 #endif