1 // --------------------------------------------------------------------- 2 // 3 // Copyright (C) 1998 - 2020 by the deal.II authors 4 // 5 // This file is part of the deal.II library. 6 // 7 // The deal.II library is free software; you can use it, redistribute 8 // it, and/or modify it under the terms of the GNU Lesser General 9 // Public License as published by the Free Software Foundation; either 10 // version 2.1 of the License, or (at your option) any later version. 11 // The full text of the license can be found in the file LICENSE.md at 12 // the top level directory of deal.II. 13 // 14 // --------------------------------------------------------------------- 15 16 #ifndef dealii_exceptions_h 17 #define dealii_exceptions_h 18 19 #include <deal.II/base/config.h> 20 21 #include <exception> 22 #include <ostream> 23 #include <string> 24 #include <type_traits> 25 26 #ifdef DEAL_II_WITH_CUDA 27 # include <cusolverSp.h> 28 # include <cusparse.h> 29 #endif 30 31 32 DEAL_II_NAMESPACE_OPEN 33 34 35 /** 36 * This class is the base class for all exception classes. Do not use its 37 * methods and variables directly since the interface and mechanism may be 38 * subject to change. Rather create new exception classes using the 39 * <tt>DeclException</tt> macro family. 40 * 41 * See the 42 * @ref Exceptions 43 * module for more details on this class and what can be done with classes 44 * derived from it. 45 * 46 * @ingroup Exceptions 47 */ 48 class ExceptionBase : public std::exception 49 { 50 public: 51 /** 52 * Default constructor. 53 */ 54 ExceptionBase(); 55 56 /** 57 * Copy constructor. 58 */ 59 ExceptionBase(const ExceptionBase &exc); 60 61 /** 62 * Destructor. 63 */ 64 virtual ~ExceptionBase() noexcept override; 65 66 /** 67 * Copy operator. This operator is deleted since exception objects 68 * are not copyable. 69 */ 70 ExceptionBase 71 operator=(const ExceptionBase &) = delete; 72 73 /** 74 * Set the file name and line of where the exception appeared as well as the 75 * violated condition and the name of the exception as a char pointer. This 76 * function also populates the stacktrace. 77 */ 78 void 79 set_fields(const char *file, 80 const int line, 81 const char *function, 82 const char *cond, 83 const char *exc_name); 84 85 86 /** 87 * Override the standard function that returns the description of the error. 88 */ 89 virtual const char * 90 what() const noexcept override; 91 92 /** 93 * Get exception name. 94 */ 95 const char * 96 get_exc_name() const; 97 98 /** 99 * Print out the general part of the error information. 100 */ 101 void 102 print_exc_data(std::ostream &out) const; 103 104 /** 105 * Print more specific information about the exception which occurred. 106 * Overload this function in your own exception classes. 107 */ 108 virtual void 109 print_info(std::ostream &out) const; 110 111 /** 112 * Print a stacktrace, if one has been recorded previously, to the given 113 * stream. 114 */ 115 void 116 print_stack_trace(std::ostream &out) const; 117 118 protected: 119 /** 120 * Name of the file this exception happens in. 121 */ 122 const char *file; 123 124 /** 125 * Line number in this file. 126 */ 127 unsigned int line; 128 129 /** 130 * Name of the function, pretty printed. 131 */ 132 const char *function; 133 134 /** 135 * The violated condition, as a string. 136 */ 137 const char *cond; 138 139 /** 140 * Name of the exception and call sequence. 141 */ 142 const char *exc; 143 144 /** 145 * A backtrace to the position where the problem happened, if the system 146 * supports this. 147 */ 148 mutable char **stacktrace; 149 150 /** 151 * The number of stacktrace frames that are stored in the previous variable. 152 * Zero if the system does not support stack traces. 153 */ 154 int n_stacktrace_frames; 155 156 #ifdef DEAL_II_HAVE_GLIBC_STACKTRACE 157 /** 158 * array of pointers that contains the raw stack trace 159 */ 160 void *raw_stacktrace[25]; 161 #endif 162 163 private: 164 /** 165 * Internal function that generates the c_string. Called by what(). 166 */ 167 void 168 generate_message() const; 169 170 /** 171 * A pointer to the c_string that will be printed by what(). It is populated 172 * by generate_message() 173 */ 174 mutable std::string what_str; 175 }; 176 177 #ifndef DOXYGEN 178 179 /** 180 * Declare an exception class derived from ExceptionBase without parameters. 181 * 182 * @note This and similar macro names are examples of preprocessor definitions 183 * in the deal.II library that are not prefixed by a string that likely makes 184 * them unique to deal.II. As a consequence, it is possible that other 185 * libraries your code interfaces with define the same name, and the result 186 * will be name collisions (see 187 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 188 * this macro, as well as all other macros defined by deal.II that are not 189 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 190 * the header <code>deal.II/base/undefine_macros.h</code> after all other 191 * deal.II headers have been included. 192 * 193 * @ingroup Exceptions 194 */ 195 # define DeclException0(Exception0) \ 196 class Exception0 : public dealii::ExceptionBase \ 197 {} 198 199 200 /** 201 * Declare an exception class derived from ExceptionBase that can take one 202 * runtime argument, but if none is given in the place where you want to throw 203 * the exception, it simply reverts to the default text provided when 204 * declaring the exception class through this macro. 205 * 206 * @note This and similar macro names are examples of preprocessor definitions 207 * in the deal.II library that are not prefixed by a string that likely makes 208 * them unique to deal.II. As a consequence, it is possible that other 209 * libraries your code interfaces with define the same name, and the result 210 * will be name collisions (see 211 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 212 * this macro, as well as all other macros defined by deal.II that are not 213 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 214 * the header <code>deal.II/base/undefine_macros.h</code> after all other 215 * deal.II headers have been included. 216 * 217 * @ingroup Exceptions 218 */ 219 # define DeclExceptionMsg(Exception, defaulttext) \ 220 class Exception : public dealii::ExceptionBase \ 221 { \ 222 public: \ 223 Exception(const std::string &msg = defaulttext) \ 224 : arg(msg) \ 225 {} \ 226 virtual ~Exception() noexcept \ 227 {} \ 228 virtual void \ 229 print_info(std::ostream &out) const override \ 230 { \ 231 out << " " << arg << std::endl; \ 232 } \ 233 \ 234 private: \ 235 const std::string arg; \ 236 } 237 238 /** 239 * Declare an exception class derived from ExceptionBase with one additional 240 * parameter. 241 * 242 * @note This and similar macro names are examples of preprocessor definitions 243 * in the deal.II library that are not prefixed by a string that likely makes 244 * them unique to deal.II. As a consequence, it is possible that other 245 * libraries your code interfaces with define the same name, and the result 246 * will be name collisions (see 247 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 248 * this macro, as well as all other macros defined by deal.II that are not 249 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 250 * the header <code>deal.II/base/undefine_macros.h</code> after all other 251 * deal.II headers have been included. 252 * 253 * @ingroup Exceptions 254 */ 255 # define DeclException1(Exception1, type1, outsequence) \ 256 class Exception1 : public dealii::ExceptionBase \ 257 { \ 258 public: \ 259 Exception1(type1 const &a1) \ 260 : arg1(a1) \ 261 {} \ 262 virtual ~Exception1() noexcept \ 263 {} \ 264 virtual void \ 265 print_info(std::ostream &out) const override \ 266 { \ 267 out << " " outsequence << std::endl; \ 268 } \ 269 \ 270 private: \ 271 type1 const arg1; \ 272 } 273 274 275 /** 276 * Declare an exception class derived from ExceptionBase with two additional 277 * parameters. 278 * 279 * @note This and similar macro names are examples of preprocessor definitions 280 * in the deal.II library that are not prefixed by a string that likely makes 281 * them unique to deal.II. As a consequence, it is possible that other 282 * libraries your code interfaces with define the same name, and the result 283 * will be name collisions (see 284 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 285 * this macro, as well as all other macros defined by deal.II that are not 286 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 287 * the header <code>deal.II/base/undefine_macros.h</code> after all other 288 * deal.II headers have been included. 289 * 290 * @ingroup Exceptions 291 */ 292 # define DeclException2(Exception2, type1, type2, outsequence) \ 293 class Exception2 : public dealii::ExceptionBase \ 294 { \ 295 public: \ 296 Exception2(type1 const &a1, type2 const &a2) \ 297 : arg1(a1) \ 298 , arg2(a2) \ 299 {} \ 300 virtual ~Exception2() noexcept \ 301 {} \ 302 virtual void \ 303 print_info(std::ostream &out) const override \ 304 { \ 305 out << " " outsequence << std::endl; \ 306 } \ 307 \ 308 private: \ 309 type1 const arg1; \ 310 type2 const arg2; \ 311 } 312 313 314 /** 315 * Declare an exception class derived from ExceptionBase with three additional 316 * parameters. 317 * 318 * @note This and similar macro names are examples of preprocessor definitions 319 * in the deal.II library that are not prefixed by a string that likely makes 320 * them unique to deal.II. As a consequence, it is possible that other 321 * libraries your code interfaces with define the same name, and the result 322 * will be name collisions (see 323 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 324 * this macro, as well as all other macros defined by deal.II that are not 325 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 326 * the header <code>deal.II/base/undefine_macros.h</code> after all other 327 * deal.II headers have been included. 328 * 329 * @ingroup Exceptions 330 */ 331 # define DeclException3(Exception3, type1, type2, type3, outsequence) \ 332 class Exception3 : public dealii::ExceptionBase \ 333 { \ 334 public: \ 335 Exception3(type1 const &a1, type2 const &a2, type3 const &a3) \ 336 : arg1(a1) \ 337 , arg2(a2) \ 338 , arg3(a3) \ 339 {} \ 340 virtual ~Exception3() noexcept \ 341 {} \ 342 virtual void \ 343 print_info(std::ostream &out) const override \ 344 { \ 345 out << " " outsequence << std::endl; \ 346 } \ 347 \ 348 private: \ 349 type1 const arg1; \ 350 type2 const arg2; \ 351 type3 const arg3; \ 352 } 353 354 355 /** 356 * Declare an exception class derived from ExceptionBase with four additional 357 * parameters. 358 * 359 * @note This and similar macro names are examples of preprocessor definitions 360 * in the deal.II library that are not prefixed by a string that likely makes 361 * them unique to deal.II. As a consequence, it is possible that other 362 * libraries your code interfaces with define the same name, and the result 363 * will be name collisions (see 364 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 365 * this macro, as well as all other macros defined by deal.II that are not 366 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 367 * the header <code>deal.II/base/undefine_macros.h</code> after all other 368 * deal.II headers have been included. 369 * 370 * @ingroup Exceptions 371 */ 372 # define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \ 373 class Exception4 : public dealii::ExceptionBase \ 374 { \ 375 public: \ 376 Exception4(type1 const &a1, \ 377 type2 const &a2, \ 378 type3 const &a3, \ 379 type4 const &a4) \ 380 : arg1(a1) \ 381 , arg2(a2) \ 382 , arg3(a3) \ 383 , arg4(a4) \ 384 {} \ 385 virtual ~Exception4() noexcept \ 386 {} \ 387 virtual void \ 388 print_info(std::ostream &out) const override \ 389 { \ 390 out << " " outsequence << std::endl; \ 391 } \ 392 \ 393 private: \ 394 type1 const arg1; \ 395 type2 const arg2; \ 396 type3 const arg3; \ 397 type4 const arg4; \ 398 } 399 400 401 /** 402 * Declare an exception class derived from ExceptionBase with five additional 403 * parameters. 404 * 405 * @note This and similar macro names are examples of preprocessor definitions 406 * in the deal.II library that are not prefixed by a string that likely makes 407 * them unique to deal.II. As a consequence, it is possible that other 408 * libraries your code interfaces with define the same name, and the result 409 * will be name collisions (see 410 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 411 * this macro, as well as all other macros defined by deal.II that are not 412 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 413 * the header <code>deal.II/base/undefine_macros.h</code> after all other 414 * deal.II headers have been included. 415 * 416 * @ingroup Exceptions 417 */ 418 # define DeclException5( \ 419 Exception5, type1, type2, type3, type4, type5, outsequence) \ 420 class Exception5 : public dealii::ExceptionBase \ 421 { \ 422 public: \ 423 Exception5(type1 const &a1, \ 424 type2 const &a2, \ 425 type3 const &a3, \ 426 type4 const &a4, \ 427 type5 const &a5) \ 428 : arg1(a1) \ 429 , arg2(a2) \ 430 , arg3(a3) \ 431 , arg4(a4) \ 432 , arg5(a5) \ 433 {} \ 434 virtual ~Exception5() noexcept \ 435 {} \ 436 virtual void \ 437 print_info(std::ostream &out) const override \ 438 { \ 439 out << " " outsequence << std::endl; \ 440 } \ 441 \ 442 private: \ 443 type1 const arg1; \ 444 type2 const arg2; \ 445 type3 const arg3; \ 446 type4 const arg4; \ 447 type5 const arg5; \ 448 } 449 450 #else /*ifndef DOXYGEN*/ 451 452 // Dummy definitions for doxygen: 453 454 /** 455 * Declare an exception class derived from ExceptionBase without parameters. 456 * 457 * @note This and similar macro names are examples of preprocessor definitions 458 * in the deal.II library that are not prefixed by a string that likely makes 459 * them unique to deal.II. As a consequence, it is possible that other 460 * libraries your code interfaces with define the same name, and the result 461 * will be name collisions (see 462 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 463 * this macro, as well as all other macros defined by deal.II that are not 464 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 465 * the header <code>deal.II/base/undefine_macros.h</code> after all other 466 * deal.II headers have been included. 467 * 468 * @ingroup Exceptions 469 */ 470 # define DeclException0(Exception0) \ 471 /** @ingroup Exceptions */ \ 472 static dealii::ExceptionBase &Exception0() 473 474 /** 475 * Declare an exception class derived from ExceptionBase that can take one 476 * runtime argument, but if none is given in the place where you want to throw 477 * the exception, it simply reverts to the default text provided when 478 * declaring the exception class through this macro. 479 * 480 * @note This and similar macro names are examples of preprocessor definitions 481 * in the deal.II library that are not prefixed by a string that likely makes 482 * them unique to deal.II. As a consequence, it is possible that other 483 * libraries your code interfaces with define the same name, and the result 484 * will be name collisions (see 485 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 486 * this macro, as well as all other macros defined by deal.II that are not 487 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 488 * the header <code>deal.II/base/undefine_macros.h</code> after all other 489 * deal.II headers have been included. 490 * 491 * @ingroup Exceptions 492 */ 493 # define DeclExceptionMsg(Exception, defaulttext) \ 494 /** @ingroup Exceptions */ \ 495 /** @dealiiExceptionMessage{defaulttext} */ \ 496 static dealii::ExceptionBase &Exception() 497 498 /** 499 * Declare an exception class derived from ExceptionBase with one additional 500 * parameter. 501 * 502 * @note This and similar macro names are examples of preprocessor definitions 503 * in the deal.II library that are not prefixed by a string that likely makes 504 * them unique to deal.II. As a consequence, it is possible that other 505 * libraries your code interfaces with define the same name, and the result 506 * will be name collisions (see 507 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 508 * this macro, as well as all other macros defined by deal.II that are not 509 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 510 * the header <code>deal.II/base/undefine_macros.h</code> after all other 511 * deal.II headers have been included. 512 * 513 * @ingroup Exceptions 514 */ 515 # define DeclException1(Exception1, type1, outsequence) \ 516 /** @ingroup Exceptions */ \ 517 /** @dealiiExceptionMessage{outsequence} */ \ 518 static dealii::ExceptionBase &Exception1(type1 arg1) 519 520 521 /** 522 * Declare an exception class derived from ExceptionBase with two additional 523 * parameters. 524 * 525 * @note This and similar macro names are examples of preprocessor definitions 526 * in the deal.II library that are not prefixed by a string that likely makes 527 * them unique to deal.II. As a consequence, it is possible that other 528 * libraries your code interfaces with define the same name, and the result 529 * will be name collisions (see 530 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 531 * this macro, as well as all other macros defined by deal.II that are not 532 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 533 * the header <code>deal.II/base/undefine_macros.h</code> after all other 534 * deal.II headers have been included. 535 * 536 * @ingroup Exceptions 537 */ 538 # define DeclException2(Exception2, type1, type2, outsequence) \ 539 /** @ingroup Exceptions */ \ 540 /** @dealiiExceptionMessage{outsequence} */ \ 541 static dealii::ExceptionBase &Exception2(type1 arg1, type2 arg2) 542 543 544 /** 545 * Declare an exception class derived from ExceptionBase with three additional 546 * parameters. 547 * 548 * @note This and similar macro names are examples of preprocessor definitions 549 * in the deal.II library that are not prefixed by a string that likely makes 550 * them unique to deal.II. As a consequence, it is possible that other 551 * libraries your code interfaces with define the same name, and the result 552 * will be name collisions (see 553 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 554 * this macro, as well as all other macros defined by deal.II that are not 555 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 556 * the header <code>deal.II/base/undefine_macros.h</code> after all other 557 * deal.II headers have been included. 558 * 559 * @ingroup Exceptions 560 */ 561 # define DeclException3(Exception3, type1, type2, type3, outsequence) \ 562 /** @ingroup Exceptions */ \ 563 /** @dealiiExceptionMessage{outsequence} */ \ 564 static dealii::ExceptionBase &Exception3(type1 arg1, type2 arg2, type3 arg3) 565 566 567 /** 568 * Declare an exception class derived from ExceptionBase with four additional 569 * parameters. 570 * 571 * @note This and similar macro names are examples of preprocessor definitions 572 * in the deal.II library that are not prefixed by a string that likely makes 573 * them unique to deal.II. As a consequence, it is possible that other 574 * libraries your code interfaces with define the same name, and the result 575 * will be name collisions (see 576 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 577 * this macro, as well as all other macros defined by deal.II that are not 578 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 579 * the header <code>deal.II/base/undefine_macros.h</code> after all other 580 * deal.II headers have been included. 581 * 582 * @ingroup Exceptions 583 */ 584 # define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \ 585 /** @ingroup Exceptions */ \ 586 /** @dealiiExceptionMessage{outsequence} */ \ 587 static dealii::ExceptionBase &Exception4(type1 arg1, \ 588 type2 arg2, \ 589 type3 arg3, \ 590 type4 arg4) 591 592 593 /** 594 * Declare an exception class derived from ExceptionBase with five additional 595 * parameters. 596 * 597 * @note This and similar macro names are examples of preprocessor definitions 598 * in the deal.II library that are not prefixed by a string that likely makes 599 * them unique to deal.II. As a consequence, it is possible that other 600 * libraries your code interfaces with define the same name, and the result 601 * will be name collisions (see 602 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 603 * this macro, as well as all other macros defined by deal.II that are not 604 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 605 * the header <code>deal.II/base/undefine_macros.h</code> after all other 606 * deal.II headers have been included. 607 * 608 * @ingroup Exceptions 609 */ 610 # define DeclException5( \ 611 Exception5, type1, type2, type3, type4, type5, outsequence) \ 612 /** @ingroup Exceptions */ \ 613 /** @dealiiExceptionMessage{outsequence} */ \ 614 static dealii::ExceptionBase &Exception5( \ 615 type1 arg1, type2 arg2, type3 arg3, type4 arg4, type5 arg5) 616 617 #endif /*ifndef DOXYGEN*/ 618 619 620 /** 621 * Declare some exceptions that occur over and over. This way, you can simply 622 * use these exceptions, instead of having to declare them locally in your 623 * class. The namespace in which these exceptions are declared is later 624 * included into the global namespace by 625 * @code 626 * using namespace StandardExceptions; 627 * @endcode 628 * 629 * @ingroup Exceptions 630 */ 631 namespace StandardExceptions 632 { 633 /** 634 * @addtogroup Exceptions 635 */ 636 //@{ 637 638 /** 639 * Exception denoting a division by zero. 640 */ 641 DeclExceptionMsg(ExcDivideByZero, 642 "A piece of code is attempting a division by zero. This is " 643 "likely going to lead to results that make no sense."); 644 645 /** 646 * Exception raised if a number is not finite. 647 * 648 * This exception should be used to catch infinite or not a number results 649 * of arithmetic operations that do not result from a division by zero (use 650 * ExcDivideByZero for those). 651 * 652 * The exception uses std::complex as its argument to ensure that we can use 653 * it for all scalar arguments (real or complex-valued). 654 */ 655 DeclException1( 656 ExcNumberNotFinite, 657 std::complex<double>, 658 << "In a significant number of places, deal.II checks that some intermediate " 659 << "value is a finite number (as opposed to plus or minus infinity, or " 660 << "NaN/Not a Number). In the current function, we encountered a number " 661 << "that is not finite (its value is " << arg1 << " and therefore " 662 << "violates the current assertion).\n\n" 663 << "This may be due to the fact that some operation in this function " 664 << "created such a value, or because one of the arguments you passed " 665 << "to the function already had this value from some previous " 666 << "operation. In the latter case, this function only triggered the " 667 << "error but may not actually be responsible for the computation of " 668 << "the number that is not finite.\n\n" 669 << "There are two common cases where this situation happens. First, your " 670 << "code (or something in deal.II) divides by zero in a place where this " 671 << "should not happen. Or, you are trying to solve a linear system " 672 << "with an unsuitable solver (such as an indefinite or non-symmetric " 673 << "linear system using a Conjugate Gradient solver); such attempts " 674 << "oftentimes yield an operation somewhere that tries to divide " 675 << "by zero or take the square root of a negative value.\n\n" 676 << "In any case, when trying to find the source of the error, " 677 << "recall that the location where you are getting this error is " 678 << "simply the first place in the program where there is a check " 679 << "that a number (e.g., an element of a solution vector) is in fact " 680 << "finite, but that the actual error that computed the number " 681 << "may have happened far earlier. To find this location, you " 682 << "may want to add checks for finiteness in places of your " 683 << "program visited before the place where this error is produced. " 684 << "One way to check for finiteness is to use the 'AssertIsFinite' " 685 << "macro."); 686 687 /** 688 * Trying to allocate a new object failed due to lack of free memory. 689 */ 690 DeclException1(ExcOutOfMemory, 691 std::size_t, 692 "Your program tried to allocate some memory but this " 693 "allocation failed. Typically, this either means that " 694 "you simply do not have enough memory in your system, " 695 "or that you are (erroneously) trying to allocate " 696 "a chunk of memory that is simply beyond all reasonable " 697 "size, for example because the size of the object has " 698 "been computed incorrectly." 699 "\n\n" 700 "In the current case, the request was for " 701 << arg1 << " bytes."); 702 703 /** 704 * A memory handler reached a point where all allocated objects should have 705 * been released. Since this exception is thrown, some were still allocated. 706 */ 707 DeclException1(ExcMemoryLeak, 708 int, 709 << "Destroying memory handler while " << arg1 710 << " objects are still allocated."); 711 712 /** 713 * An error occurred reading or writing a file. 714 */ 715 DeclExceptionMsg(ExcIO, 716 "An input/output error has occurred. There are a number of " 717 "reasons why this may be happening, both for reading and " 718 "writing operations." 719 "\n\n" 720 "If this happens during an operation that tries to read " 721 "data: First, you may be " 722 "trying to read from a file that doesn't exist or that is " 723 "not readable given its file permissions. Second, deal.II " 724 "uses this error at times if it tries to " 725 "read information from a file but where the information " 726 "in the file does not correspond to the expected format. " 727 "An example would be a truncated file, or a mesh file " 728 "that contains not only sections that describe the " 729 "vertices and cells, but also sections for additional " 730 "data that deal.II does not understand." 731 "\n\n" 732 "If this happens during an operation that tries to write " 733 "data: you may be trying to write to a file to which file " 734 "or directory permissions do not allow you to write. A " 735 "typical example is where you specify an output file in " 736 "a directory that does not exist."); 737 738 /** 739 * An error occurred opening the named file. 740 * 741 * The constructor takes a single argument of type <tt>std::string</tt> naming 742 * the file. 743 */ 744 DeclException1(ExcFileNotOpen, 745 std::string, 746 << "Could not open file " << arg1 << "."); 747 748 /** 749 * Exception denoting a part of the library or application program that has 750 * not yet been implemented. In many cases, this only indicates that there 751 * wasn't much need for something yet, not that this is difficult to 752 * implement. It is therefore quite worth the effort to take a look at the 753 * corresponding place and see whether it can be implemented without too 754 * much effort. 755 */ 756 DeclExceptionMsg(ExcNotImplemented, 757 "You are trying to use functionality in deal.II that is " 758 "currently not implemented. In many cases, this indicates " 759 "that there simply didn't appear much of a need for it, or " 760 "that the author of the original code did not have the " 761 "time to implement a particular case. If you hit this " 762 "exception, it is therefore worth the time to look into " 763 "the code to find out whether you may be able to " 764 "implement the missing functionality. If you do, please " 765 "consider providing a patch to the deal.II development " 766 "sources (see the deal.II website on how to contribute)."); 767 768 /** 769 * This exception usually indicates that some condition which the programmer 770 * thinks must be satisfied at a certain point in an algorithm, is not 771 * fulfilled. This might be due to some programming error above, due to 772 * changes to the algorithm that did not preserve this assertion, or due to 773 * assumptions the programmer made that are not valid at all (i.e. the 774 * exception is thrown although there is no error here). Within the library, 775 * this exception is most often used when we write some kind of complicated 776 * algorithm and are not yet sure whether we got it right; we then put in 777 * assertions after each part of the algorithm that check for some 778 * conditions that should hold there, and throw an exception if they do not. 779 * 780 * We usually leave in these assertions even after we are confident that the 781 * implementation is correct, since if someone later changes or extends the 782 * algorithm, these exceptions will indicate to them if they violate 783 * assumptions that are used later in the algorithm. Furthermore, it 784 * sometimes happens that an algorithm does not work in very rare corner 785 * cases. These cases will then be trapped sooner or later by the exception, 786 * so that the algorithm can then be fixed for these cases as well. 787 */ 788 DeclExceptionMsg(ExcInternalError, 789 "This exception -- which is used in many places in the " 790 "library -- usually indicates that some condition which " 791 "the author of the code thought must be satisfied at a " 792 "certain point in an algorithm, is not fulfilled. An " 793 "example would be that the first part of an algorithm " 794 "sorts elements of an array in ascending order, and " 795 "a second part of the algorithm later encounters an " 796 "element that is not larger than the previous one." 797 "\n\n" 798 "There is usually not very much you can do if you " 799 "encounter such an exception since it indicates an error " 800 "in deal.II, not in your own program. Try to come up with " 801 "the smallest possible program that still demonstrates " 802 "the error and contact the deal.II mailing lists with it " 803 "to obtain help."); 804 805 /** 806 * This exception is used in functions that may not be called (i.e. in pure 807 * functions) but could not be declared pure since the class is intended to 808 * be used anyway, even though the respective function may only be called if 809 * a derived class is used. 810 */ 811 DeclExceptionMsg( 812 ExcPureFunctionCalled, 813 "You (or a place in the library) are trying to call a " 814 "function that is declared as a virtual function in a " 815 "base class but that has not been overridden in your " 816 "derived class." 817 "\n\n" 818 "This exception happens in cases where the base class " 819 "cannot provide a useful default implementation for " 820 "the virtual function, but where we also do not want " 821 "to mark the function as abstract (i.e., with '=0' at the end) " 822 "because the function is not essential to the class in many " 823 "contexts. In cases like this, the base class provides " 824 "a dummy implementation that makes the compiler happy, but " 825 "that then throws the current exception." 826 "\n\n" 827 "A concrete example would be the 'Function' class. It declares " 828 "the existence of 'value()' and 'gradient()' member functions, " 829 "and both are marked as 'virtual'. Derived classes have to " 830 "override these functions for the values and gradients of a " 831 "particular function. On the other hand, not every function " 832 "has a gradient, and even for those that do, not every program " 833 "actually needs to evaluate it. Consequently, there is no " 834 "*requirement* that a derived class actually override the " 835 "'gradient()' function (as there would be had it been marked " 836 "as abstract). But, since the base class cannot know how to " 837 "compute the gradient, if a derived class does not override " 838 "the 'gradient()' function and it is called anyway, then the " 839 "default implementation in the base class will simply throw " 840 "an exception." 841 "\n\n" 842 "The exception you see is what happens in cases such as the " 843 "one just illustrated. To fix the problem, you need to " 844 "investigate whether the function being called should indeed have " 845 "been called; if the answer is 'yes', then you need to " 846 "implement the missing override in your class."); 847 848 /** 849 * This exception is used if some object is found uninitialized. 850 */ 851 DeclException0(ExcNotInitialized); 852 853 /** 854 * The object is in a state not suitable for this operation. 855 */ 856 DeclException0(ExcInvalidState); 857 858 /** 859 * This exception is raised if a functionality is not possible in the given 860 * dimension. Mostly used to throw function calls in 1d. 861 * 862 * The constructor takes a single <tt>int</tt>, denoting the dimension. 863 */ 864 DeclException1(ExcImpossibleInDim, 865 int, 866 << "You are trying to execute functionality that is " 867 << "impossible in " << arg1 868 << "d or simply does not make any sense."); 869 870 /** 871 * This exception is raised if a functionality is not possible in the given 872 * combination of dimension and space-dimension. 873 * 874 * The constructor takes two <tt>int</tt>, denoting the dimension and the 875 * space dimension. 876 */ 877 DeclException2(ExcImpossibleInDimSpacedim, 878 int, 879 int, 880 << "You are trying to execute functionality that is " 881 << "impossible in dimensions <" << arg1 << "," << arg2 882 << "> or simply does not make any sense."); 883 884 885 /** 886 * A number is zero, but it should not be here. 887 */ 888 DeclExceptionMsg(ExcZero, 889 "In a check in the code, deal.II encountered a zero in " 890 "a place where this does not make sense. See the condition " 891 "that was being checked and that is printed further up " 892 "in the error message to get more information on what " 893 "the erroneous zero corresponds to."); 894 895 /** 896 * The object should have been filled with something before this member 897 * function is called. 898 */ 899 DeclExceptionMsg(ExcEmptyObject, 900 "The object you are trying to access is empty but it makes " 901 "no sense to attempt the operation you are trying on an " 902 "empty object."); 903 904 /** 905 * This exception is raised whenever the sizes of two objects were assumed 906 * to be equal, but were not. 907 * 908 * Parameters to the constructor are the first and second size, both of type 909 * <tt>int</tt>. 910 */ 911 DeclException2(ExcDimensionMismatch, 912 std::size_t, 913 std::size_t, 914 << "Dimension " << arg1 << " not equal to " << arg2 << "."); 915 916 /** 917 * The first dimension should be either equal to the second or the third, 918 * but it is neither. 919 */ 920 DeclException3(ExcDimensionMismatch2, 921 int, 922 int, 923 int, 924 << "Dimension " << arg1 << " neither equal to " << arg2 925 << " nor to " << arg3 << "."); 926 927 /** 928 * This exception indicates that an index is not within the expected range. 929 * For example, it may be that you are trying to access an element of a 930 * vector which does not exist. 931 * 932 * The constructor takes three <tt>int</tt> arguments, namely 933 * <ol> 934 * <li> the violating index 935 * <li> the lower bound 936 * <li> the upper bound plus one 937 * </ol> 938 */ 939 DeclException3( 940 ExcIndexRange, 941 int, 942 int, 943 int, 944 << "Index " << arg1 << " is not in the half-open range [" << arg2 << "," 945 << arg3 << ")." 946 << (arg2 == arg3 ? 947 " In the current case, this half-open range is in fact empty, " 948 "suggesting that you are accessing an element of an empty " 949 "collection such as a vector that has not been set to the " 950 "correct size." : 951 "")); 952 953 /** 954 * This exception indicates that an index is not within the expected range. 955 * For example, it may be that you are trying to access an element of a 956 * vector which does not exist. 957 * 958 * The constructor takes three arguments, namely 959 * <ol> 960 * <li> the violating index 961 * <li> the lower bound 962 * <li> the upper bound plus one 963 * </ol> 964 * 965 * This generic exception differs from ExcIndexRange by allowing to specify 966 * the type of indices. 967 */ 968 template <typename T> 969 DeclException3( 970 ExcIndexRangeType, 971 T, 972 T, 973 T, 974 << "Index " << arg1 << " is not in the half-open range [" << arg2 << "," 975 << arg3 << ")." 976 << (arg2 == arg3 ? 977 " In the current case, this half-open range is in fact empty, " 978 "suggesting that you are accessing an element of an empty " 979 "collection such as a vector that has not been set to the " 980 "correct size." : 981 "")); 982 983 /** 984 * A number is too small. 985 */ 986 DeclException2(ExcLowerRange, 987 int, 988 int, 989 << "Number " << arg1 << " must be larger than or equal " 990 << arg2 << "."); 991 992 /** 993 * A generic exception definition for the ExcLowerRange above. 994 */ 995 template <typename T> 996 DeclException2(ExcLowerRangeType, 997 T, 998 T, 999 << "Number " << arg1 << " must be larger than or equal " 1000 << arg2 << "."); 1001 1002 /** 1003 * This exception indicates that the first argument should be an integer 1004 * multiple of the second, but is not. 1005 */ 1006 DeclException2(ExcNotMultiple, 1007 int, 1008 int, 1009 << "Division " << arg1 << " by " << arg2 1010 << " has remainder different from zero."); 1011 1012 /** 1013 * This exception is thrown if the iterator you access has corrupted data. 1014 * It might for instance be, that the container it refers does not have an 1015 * entry at the point the iterator refers. 1016 * 1017 * Typically, this will be an internal error of deal.II, because the 1018 * increment and decrement operators should never yield an invalid iterator. 1019 */ 1020 DeclExceptionMsg(ExcInvalidIterator, 1021 "You are trying to use an iterator, but the iterator is " 1022 "in an invalid state. This may indicate that the iterator " 1023 "object has not been initialized, or that it has been " 1024 "moved beyond the end of the range of valid elements."); 1025 1026 /** 1027 * This exception is thrown if the iterator you incremented or decremented 1028 * was already at its final state. 1029 */ 1030 DeclExceptionMsg(ExcIteratorPastEnd, 1031 "You are trying to use an iterator, but the iterator is " 1032 "pointing past the end of the range of valid elements. " 1033 "It is not valid to dereference the iterator in this " 1034 "case."); 1035 1036 /** 1037 * This exception works around a design flaw in the <tt>DeclException0</tt> 1038 * macro: exceptions declared through DeclException0 do not allow one to 1039 * specify a message that is displayed when the exception is raised, as 1040 * opposed to the other exceptions which allow to show a text along with the 1041 * given parameters. 1042 * 1043 * When throwing this exception, you can give a message as a 1044 * <tt>std::string</tt> as argument to the exception that is then displayed. 1045 * The argument can, of course, be constructed at run-time, for example 1046 * including the name of a file that can't be opened, or any other text you 1047 * may want to assemble from different pieces. 1048 */ 1049 DeclException1(ExcMessage, std::string, << arg1); 1050 1051 /** 1052 * Parallel vectors with ghost elements are read-only vectors. 1053 */ 1054 DeclExceptionMsg(ExcGhostsPresent, 1055 "You are trying an operation on a vector that is only " 1056 "allowed if the vector has no ghost elements, but the " 1057 "vector you are operating on does have ghost elements. " 1058 "Specifically, vectors with ghost elements are read-only " 1059 "and cannot appear in operations that write into these " 1060 "vectors." 1061 "\n\n" 1062 "See the glossary entry on 'Ghosted vectors' for more " 1063 "information."); 1064 1065 /** 1066 * Some of our numerical classes allow for setting all entries to zero using 1067 * the assignment operator <tt>=</tt>. 1068 * 1069 * In many cases, this assignment operator makes sense <b>only</b> for the 1070 * argument zero. In other cases, this exception is thrown. 1071 */ 1072 DeclExceptionMsg(ExcScalarAssignmentOnlyForZeroValue, 1073 "You are trying an operation of the form 'vector=s' with " 1074 "a nonzero scalar value 's'. However, such assignments " 1075 "are only allowed if the right hand side is zero."); 1076 1077 /** 1078 * This function requires support for the LAPACK library. 1079 */ 1080 DeclExceptionMsg( 1081 ExcNeedsLAPACK, 1082 "You are attempting to use functionality that is only available " 1083 "if deal.II was configured to use LAPACK, but cmake did not " 1084 "find a valid LAPACK library."); 1085 1086 /** 1087 * This function requires support for the MPI library. 1088 */ 1089 DeclExceptionMsg( 1090 ExcNeedsMPI, 1091 "You are attempting to use functionality that is only available " 1092 "if deal.II was configured to use MPI."); 1093 1094 /** 1095 * This function requires simplex support. 1096 */ 1097 DeclExceptionMsg( 1098 ExcNeedsSimplexSupport, 1099 "You are attempting to use functionality that is only available " 1100 "if deal.II was configured with DEAL_II_WITH_SIMPLEX_SUPPORT enabled."); 1101 1102 /** 1103 * This function requires support for the FunctionParser library. 1104 */ 1105 DeclExceptionMsg( 1106 ExcNeedsFunctionparser, 1107 "You are attempting to use functionality that is only available " 1108 "if deal.II was configured to use the function parser which " 1109 "relies on the muparser library, but cmake did not " 1110 "find a valid muparser library on your system and also did " 1111 "not choose the one that comes bundled with deal.II."); 1112 1113 /** 1114 * This function requires support for the Assimp library. 1115 */ 1116 DeclExceptionMsg( 1117 ExcNeedsAssimp, 1118 "You are attempting to use functionality that is only available " 1119 "if deal.II was configured to use Assimp, but cmake did not " 1120 "find a valid Assimp library."); 1121 1122 #ifdef DEAL_II_WITH_CUDA 1123 /** 1124 * This exception is raised if an error happened in a CUDA kernel. 1125 * 1126 * The constructor takes a single <tt>char*</tt>, the output of 1127 * cudaGetErrorString. 1128 */ 1129 DeclException1(ExcCudaError, const char *, << arg1); 1130 /** 1131 * This exception is raised if an error happened in a cuSPARSE function. 1132 */ 1133 DeclException1(ExcCusparseError, 1134 std::string, 1135 << "There was an error in a cuSPARSE function: " << arg1); 1136 #endif 1137 //@} 1138 1139 #ifdef DEAL_II_WITH_MPI 1140 /** 1141 * Exception for MPI errors. This exception is only defined if 1142 * <code>deal.II</code> is compiled with MPI support. This exception should 1143 * be used with <code>AssertThrow</code> to check error codes of MPI 1144 * functions. For example: 1145 * @code 1146 * const int ierr = MPI_Isend(...); 1147 * AssertThrow(ierr == MPI_SUCCESS, ExcMPI(ierr)); 1148 * @endcode 1149 * or, using the convenience macro <code>AssertThrowMPI</code>, 1150 * @code 1151 * const int ierr = MPI_Irecv(...); 1152 * AssertThrowMPI(ierr); 1153 * @endcode 1154 * 1155 * If the assertion fails then the error code will be used to print a helpful 1156 * message to the screen by utilizing the <code>MPI_Error_string</code> 1157 * function. 1158 * 1159 * @ingroup Exceptions 1160 */ 1161 class ExcMPI : public dealii::ExceptionBase 1162 { 1163 public: 1164 ExcMPI(const int error_code); 1165 1166 virtual void 1167 print_info(std::ostream &out) const override; 1168 1169 const int error_code; 1170 }; 1171 #endif // DEAL_II_WITH_MPI 1172 } /*namespace StandardExceptions*/ 1173 1174 1175 1176 /** 1177 * In this namespace, functions in connection with the Assert and AssertThrow 1178 * mechanism are declared. 1179 * 1180 * @ingroup Exceptions 1181 */ 1182 namespace deal_II_exceptions 1183 { 1184 namespace internals 1185 { 1186 /** 1187 * Setting this variable to false will disable deal.II's exception mechanism 1188 * to abort the problem. The Assert() macro will throw the exception instead 1189 * and the AssertNothrow() macro will just print the error message. This 1190 * variable should not be changed directly. Use disable_abort_on_exception() 1191 * instead. 1192 */ 1193 extern bool allow_abort_on_exception; 1194 } // namespace internals 1195 1196 /** 1197 * Set a string that is printed upon output of the message indicating a 1198 * triggered <tt>Assert</tt> statement. This string, which is printed in 1199 * addition to the usual output may indicate information that is otherwise 1200 * not readily available unless we are using a debugger. For example, with 1201 * distributed programs on cluster computers, the output of all processes is 1202 * redirected to the same console window. In this case, it is convenient to 1203 * set as additional name the name of the host on which the program runs, so 1204 * that one can see in which instance of the program the exception occurred. 1205 * 1206 * The string pointed to by the argument is copied, so doesn't need to be 1207 * stored after the call to this function. 1208 * 1209 * Previously set additional output is replaced by the argument given to 1210 * this function. 1211 * 1212 * @see Exceptions 1213 */ 1214 void 1215 set_additional_assert_output(const char *const p); 1216 1217 /** 1218 * Calling this function disables printing a stacktrace along with the other 1219 * output printed when an exception occurs. Most of the time, you will want 1220 * to see such a stacktrace; suppressing it, however, is useful if one wants 1221 * to compare the output of a program across different machines and systems, 1222 * since the stacktrace shows memory addresses and library names/paths that 1223 * depend on the exact setup of a machine. 1224 * 1225 * @see Exceptions 1226 */ 1227 void 1228 suppress_stacktrace_in_exceptions(); 1229 1230 /** 1231 * Calling this function switches off the use of <tt>std::abort()</tt> when 1232 * an exception is created using the Assert() macro. Instead, the Exception 1233 * will be thrown using 'throw', so it can be caught if desired. Generally, 1234 * you want to abort the execution of a program when Assert() is called, but 1235 * it needs to be switched off if you want to log all exceptions created, or 1236 * if you want to test if an assertion is working correctly. This is done 1237 * for example in regression tests. Please note that some fatal errors will 1238 * still call abort(), e.g. when an exception is caught during exception 1239 * handling. 1240 * 1241 * @see Exceptions 1242 */ 1243 void 1244 disable_abort_on_exception(); 1245 1246 /** 1247 * The functions in this namespace are in connection with the Assert and 1248 * AssertThrow mechanism but are solely for internal purposes and are not 1249 * for use outside the exception handling and throwing mechanism. 1250 * 1251 * @ingroup Exceptions 1252 */ 1253 namespace internals 1254 { 1255 /** 1256 * Abort the program by printing the 1257 * error message provided by @p exc and calling <tt>std::abort()</tt>. 1258 */ 1259 [[noreturn]] void 1260 abort(const ExceptionBase &exc) noexcept; 1261 1262 /** 1263 * An enum describing how to treat an exception in issue_error_noreturn. 1264 */ 1265 enum ExceptionHandling 1266 { 1267 /** 1268 * Abort the program by calling <code>std::abort</code> unless 1269 * deal_II_exceptions::disable_abort_on_exception has been called: in 1270 * that case the program will throw an exception. 1271 */ 1272 abort_or_throw_on_exception, 1273 /** 1274 * Throw the exception normally. 1275 */ 1276 throw_on_exception 1277 }; 1278 1279 /** 1280 * This routine does the main work for the exception generation mechanism 1281 * used in the <tt>Assert</tt> and <tt>AssertThrow</tt> macros: as the 1282 * name implies, this function either ends by throwing an exception (if 1283 * @p handling is throw_on_exception, or @p handling is try_abort_exception 1284 * and deal_II_exceptions::disable_abort_on_exception is false) or with a 1285 * call to <tt>abort</tt> (if @p handling is try_abort_exception and 1286 * deal_II_exceptions::disable_abort_on_exception is true). 1287 * 1288 * The actual exception object (the last argument) is typically an unnamed 1289 * object created in place; because we modify it, we can't take it by 1290 * const reference, and temporaries don't bind to non-const references. 1291 * So take it by value (=copy it) with a templated type to avoid slicing 1292 * -- the performance implications are pretty minimal anyway. 1293 * 1294 * @ref ExceptionBase 1295 */ 1296 template <class ExceptionType> 1297 [[noreturn]] void issue_error_noreturn(ExceptionHandling handling,const char * file,int line,const char * function,const char * cond,const char * exc_name,ExceptionType e)1298 issue_error_noreturn(ExceptionHandling handling, 1299 const char * file, 1300 int line, 1301 const char * function, 1302 const char * cond, 1303 const char * exc_name, 1304 ExceptionType e) { 1305 // Fill the fields of the exception object 1306 e.set_fields(file, line, function, cond, exc_name); 1307 1308 switch (handling) 1309 { 1310 case abort_or_throw_on_exception: 1311 { 1312 if (dealii::deal_II_exceptions::internals:: 1313 allow_abort_on_exception) 1314 internals::abort(e); 1315 else 1316 { 1317 // We are not allowed to abort, so just throw the error: 1318 throw e; 1319 } 1320 } 1321 case throw_on_exception: 1322 throw e; 1323 // this function should never return (and AssertNothrow can); 1324 // something must have gone wrong in the error handling code for us 1325 // to get this far, so throw an exception. 1326 default: 1327 throw ::dealii::StandardExceptions::ExcInternalError(); 1328 } 1329 } 1330 1331 /** 1332 * Internal function that does the work of issue_error_nothrow. 1333 */ 1334 void do_issue_error_nothrow(const ExceptionBase &e) noexcept; 1335 1336 /** 1337 * Exception generation mechanism in case we must not throw. 1338 * 1339 * @ref ExceptionBase 1340 * 1341 * @note This function is defined with a template for the same reasons as 1342 * issue_error_noreturn(). 1343 */ 1344 template <class ExceptionType> 1345 void issue_error_nothrow(const char * file,int line,const char * function,const char * cond,const char * exc_name,ExceptionType e)1346 issue_error_nothrow(const char * file, 1347 int line, 1348 const char * function, 1349 const char * cond, 1350 const char * exc_name, 1351 ExceptionType e) noexcept 1352 { 1353 static_assert(std::is_base_of<ExceptionBase, ExceptionType>::value, 1354 "The provided exception must inherit from ExceptionBase."); 1355 // Fill the fields of the exception object 1356 e.set_fields(file, line, function, cond, exc_name); 1357 // avoid moving a bunch of code into the header by dispatching to 1358 // another function: 1359 do_issue_error_nothrow(e); 1360 } 1361 #ifdef DEAL_II_WITH_CUDA 1362 /** 1363 * Return a string given an error code. This is similar to the 1364 * cudaGetErrorString function but there is no equivalent function for 1365 * cuSPARSE. 1366 */ 1367 std::string 1368 get_cusparse_error_string(const cusparseStatus_t error_code); 1369 1370 /** 1371 * Return a string given an error code. This is similar to the 1372 * cudaGetErrorString function but there is no equivalent function for 1373 * cuSOLVER. 1374 */ 1375 std::string 1376 get_cusolver_error_string(const cusolverStatus_t error_code); 1377 #endif 1378 } /*namespace internals*/ 1379 1380 } /*namespace deal_II_exceptions*/ 1381 1382 1383 1384 /** 1385 * A macro that serves as the main routine in the exception mechanism for debug 1386 * mode error checking. It asserts that a certain condition is fulfilled, 1387 * otherwise issues an error and aborts the program. 1388 * 1389 * A more detailed description can be found in the 1390 * @ref Exceptions 1391 * module. It is first used in step-5 and step-6. 1392 * See also the <tt>ExceptionBase</tt> class for more information. 1393 * 1394 * @note Active in DEBUG mode only 1395 * 1396 * @note This and similar macro names are examples of preprocessor definitions 1397 * in the deal.II library that are not prefixed by a string that likely makes 1398 * them unique to deal.II. As a consequence, it is possible that other 1399 * libraries your code interfaces with define the same name, and the result 1400 * will be name collisions (see 1401 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1402 * this macro, as well as all other macros defined by deal.II that are not 1403 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1404 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1405 * deal.II headers have been included. 1406 * 1407 * @ingroup Exceptions 1408 */ 1409 #ifdef DEBUG 1410 # ifdef DEAL_II_HAVE_BUILTIN_EXPECT 1411 # define Assert(cond, exc) \ 1412 { \ 1413 if (__builtin_expect(!(cond), false)) \ 1414 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \ 1415 ::dealii::deal_II_exceptions::internals:: \ 1416 abort_or_throw_on_exception, \ 1417 __FILE__, \ 1418 __LINE__, \ 1419 __PRETTY_FUNCTION__, \ 1420 #cond, \ 1421 #exc, \ 1422 exc); \ 1423 } 1424 # else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1425 # define Assert(cond, exc) \ 1426 { \ 1427 if (!(cond)) \ 1428 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \ 1429 ::dealii::deal_II_exceptions::internals:: \ 1430 abort_or_throw_on_exception, \ 1431 __FILE__, \ 1432 __LINE__, \ 1433 __PRETTY_FUNCTION__, \ 1434 #cond, \ 1435 #exc, \ 1436 exc); \ 1437 } 1438 # endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1439 #else 1440 # define Assert(cond, exc) \ 1441 {} 1442 #endif 1443 1444 1445 1446 /** 1447 * A variant of the <tt>Assert</tt> macro above that exhibits the same runtime 1448 * behavior as long as disable_abort_on_exception was not called. 1449 * 1450 * However, if disable_abort_on_exception was called, this macro merely prints 1451 * the exception that would be thrown to deallog and continues normally 1452 * without throwing an exception. 1453 * 1454 * A more detailed description can be found in the 1455 * @ref Exceptions 1456 * module, in the discussion about the corner case at the bottom of the page. 1457 * 1458 * @note This and similar macro names are examples of preprocessor definitions 1459 * in the deal.II library that are not prefixed by a string that likely makes 1460 * them unique to deal.II. As a consequence, it is possible that other 1461 * libraries your code interfaces with define the same name, and the result 1462 * will be name collisions (see 1463 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1464 * this macro, as well as all other macros defined by deal.II that are not 1465 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1466 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1467 * deal.II headers have been included. 1468 * 1469 * @note Active in DEBUG mode only 1470 * @ingroup Exceptions 1471 */ 1472 #ifdef DEBUG 1473 # ifdef DEAL_II_HAVE_BUILTIN_EXPECT 1474 # define AssertNothrow(cond, exc) \ 1475 { \ 1476 if (__builtin_expect(!(cond), false)) \ 1477 ::dealii::deal_II_exceptions::internals::issue_error_nothrow( \ 1478 __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \ 1479 } 1480 # else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1481 # define AssertNothrow(cond, exc) \ 1482 { \ 1483 if (!(cond)) \ 1484 ::dealii::deal_II_exceptions::internals::issue_error_nothrow( \ 1485 __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \ 1486 } 1487 # endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1488 #else 1489 # define AssertNothrow(cond, exc) \ 1490 {} 1491 #endif 1492 1493 /** 1494 * A macro that serves as the main routine in the exception mechanism for 1495 * dynamic error checking. It asserts that a certain condition is fulfilled, 1496 * otherwise 1497 * throws an exception via the C++ @p throw mechanism. This exception can 1498 * be caught via a @p catch clause, as is shown in step-6 and all following 1499 * tutorial programs. 1500 * 1501 * A more detailed description can be found in the 1502 * @ref Exceptions 1503 * module. It is first used in step-9 and step-13. 1504 * See also the <tt>ExceptionBase</tt> class for more information. 1505 * 1506 * @note This and similar macro names are examples of preprocessor definitions 1507 * in the deal.II library that are not prefixed by a string that likely makes 1508 * them unique to deal.II. As a consequence, it is possible that other 1509 * libraries your code interfaces with define the same name, and the result 1510 * will be name collisions (see 1511 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1512 * this macro, as well as all other macros defined by deal.II that are not 1513 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1514 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1515 * deal.II headers have been included. 1516 * 1517 * @note Active in both DEBUG and RELEASE modes 1518 * @ingroup Exceptions 1519 */ 1520 #ifdef DEAL_II_HAVE_BUILTIN_EXPECT 1521 # define AssertThrow(cond, exc) \ 1522 { \ 1523 if (__builtin_expect(!(cond), false)) \ 1524 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \ 1525 ::dealii::deal_II_exceptions::internals::throw_on_exception, \ 1526 __FILE__, \ 1527 __LINE__, \ 1528 __PRETTY_FUNCTION__, \ 1529 #cond, \ 1530 #exc, \ 1531 exc); \ 1532 } 1533 #else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1534 # define AssertThrow(cond, exc) \ 1535 { \ 1536 if (!(cond)) \ 1537 ::dealii::deal_II_exceptions::internals::issue_error_noreturn( \ 1538 ::dealii::deal_II_exceptions::internals::throw_on_exception, \ 1539 __FILE__, \ 1540 __LINE__, \ 1541 __PRETTY_FUNCTION__, \ 1542 #cond, \ 1543 #exc, \ 1544 exc); \ 1545 } 1546 #endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/ 1547 1548 /** 1549 * Special assertion for dimension mismatch. 1550 * 1551 * Since this is used very often and always repeats the arguments, we 1552 * introduce this special assertion for ExcDimensionMismatch in order to keep 1553 * the user codes shorter. 1554 * 1555 * @note This and similar macro names are examples of preprocessor definitions 1556 * in the deal.II library that are not prefixed by a string that likely makes 1557 * them unique to deal.II. As a consequence, it is possible that other 1558 * libraries your code interfaces with define the same name, and the result 1559 * will be name collisions (see 1560 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1561 * this macro, as well as all other macros defined by deal.II that are not 1562 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1563 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1564 * deal.II headers have been included. 1565 * 1566 * @ingroup Exceptions 1567 */ 1568 #define AssertDimension(dim1, dim2) \ 1569 Assert(static_cast<typename ::dealii::internal::argument_type<void( \ 1570 typename std::common_type<decltype(dim1), \ 1571 decltype(dim2)>::type)>::type>(dim1) == \ 1572 static_cast<typename ::dealii::internal::argument_type<void( \ 1573 typename std::common_type<decltype(dim1), \ 1574 decltype(dim2)>::type)>::type>(dim2), \ 1575 dealii::ExcDimensionMismatch((dim1), (dim2))) 1576 1577 1578 /** 1579 * An assertion that tests whether <tt>vec</tt> has size <tt>dim1</tt>, and 1580 * each entry of the vector is itself an array that has the size <tt>dim2</tt>. 1581 * 1582 * @note This and similar macro names are examples of preprocessor definitions 1583 * in the deal.II library that are not prefixed by a string that likely makes 1584 * them unique to deal.II. As a consequence, it is possible that other 1585 * libraries your code interfaces with define the same name, and the result 1586 * will be name collisions (see 1587 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1588 * this macro, as well as all other macros defined by deal.II that are not 1589 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1590 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1591 * deal.II headers have been included. 1592 * 1593 * @ingroup Exceptions 1594 */ 1595 #define AssertVectorVectorDimension(VEC, DIM1, DIM2) \ 1596 AssertDimension(VEC.size(), DIM1); \ 1597 for (const auto &subvector : VEC) \ 1598 { \ 1599 (void)subvector; \ 1600 AssertDimension(subvector.size(), DIM2); \ 1601 } 1602 1603 namespace internal 1604 { 1605 // Workaround to allow for commas in template parameter lists 1606 // in preprocessor macros as found in 1607 // https://stackoverflow.com/questions/13842468/comma-in-c-c-macro 1608 template <typename T> 1609 struct argument_type; 1610 template <typename T, typename U> 1611 struct argument_type<T(U)> 1612 { 1613 using type = U; 1614 }; 1615 } // namespace internal 1616 1617 /** 1618 * An assertion that tests that a given index is within the half-open 1619 * range <code>[0,range)</code>. It throws an exception object 1620 * <code>ExcIndexRange(index,0,range)</code> if the assertion 1621 * fails. 1622 * 1623 * @note This and similar macro names are examples of preprocessor definitions 1624 * in the deal.II library that are not prefixed by a string that likely makes 1625 * them unique to deal.II. As a consequence, it is possible that other 1626 * libraries your code interfaces with define the same name, and the result 1627 * will be name collisions (see 1628 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1629 * this macro, as well as all other macros defined by deal.II that are not 1630 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1631 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1632 * deal.II headers have been included. 1633 * 1634 * @ingroup Exceptions 1635 */ 1636 #define AssertIndexRange(index, range) \ 1637 Assert( \ 1638 static_cast<typename ::dealii::internal::argument_type<void( \ 1639 typename std::common_type<decltype(index), decltype(range)>::type)>:: \ 1640 type>(index) < \ 1641 static_cast<typename ::dealii::internal::argument_type<void( \ 1642 typename std::common_type<decltype(index), decltype(range)>::type)>:: \ 1643 type>(range), \ 1644 dealii::ExcIndexRangeType<typename ::dealii::internal::argument_type<void( \ 1645 typename std::common_type<decltype(index), decltype(range)>::type)>:: \ 1646 type>((index), 0, (range))) 1647 1648 /** 1649 * An assertion that checks whether a number is finite or not. We explicitly 1650 * cast the number to std::complex to match the signature of the exception 1651 * (see there for an explanation of why we use std::complex at all) and to 1652 * satisfy the fact that std::complex has no implicit conversions. 1653 * 1654 * @note This and similar macro names are examples of preprocessor definitions 1655 * in the deal.II library that are not prefixed by a string that likely makes 1656 * them unique to deal.II. As a consequence, it is possible that other 1657 * libraries your code interfaces with define the same name, and the result 1658 * will be name collisions (see 1659 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1660 * this macro, as well as all other macros defined by deal.II that are not 1661 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1662 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1663 * deal.II headers have been included. 1664 * 1665 * @ingroup Exceptions 1666 */ 1667 #define AssertIsFinite(number) \ 1668 Assert(dealii::numbers::is_finite(number), \ 1669 dealii::ExcNumberNotFinite(std::complex<double>(number))) 1670 1671 #ifdef DEAL_II_WITH_MPI 1672 /** 1673 * An assertion that checks whether or not an error code returned by an MPI 1674 * function is equal to <code>MPI_SUCCESS</code>. If the check fails then an 1675 * exception of type ExcMPI is thrown with the given error code as an 1676 * argument. 1677 * 1678 * @note This and similar macro names are examples of preprocessor definitions 1679 * in the deal.II library that are not prefixed by a string that likely makes 1680 * them unique to deal.II. As a consequence, it is possible that other 1681 * libraries your code interfaces with define the same name, and the result 1682 * will be name collisions (see 1683 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1684 * this macro, as well as all other macros defined by deal.II that are not 1685 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1686 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1687 * deal.II headers have been included. 1688 * 1689 * @note Active only if deal.II is compiled with MPI 1690 * @ingroup Exceptions 1691 */ 1692 # define AssertThrowMPI(error_code) \ 1693 AssertThrow(error_code == MPI_SUCCESS, dealii::ExcMPI(error_code)) 1694 #else 1695 # define AssertThrowMPI(error_code) \ 1696 {} 1697 #endif // DEAL_II_WITH_MPI 1698 1699 #ifdef DEAL_II_WITH_CUDA 1700 /** 1701 * An assertion that checks that the error code produced by calling a CUDA 1702 * routine is equal to cudaSuccess. 1703 * 1704 * @note This and similar macro names are examples of preprocessor definitions 1705 * in the deal.II library that are not prefixed by a string that likely makes 1706 * them unique to deal.II. As a consequence, it is possible that other 1707 * libraries your code interfaces with define the same name, and the result 1708 * will be name collisions (see 1709 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1710 * this macro, as well as all other macros defined by deal.II that are not 1711 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1712 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1713 * deal.II headers have been included. 1714 * 1715 * @ingroup Exceptions 1716 */ 1717 # ifdef DEBUG 1718 # define AssertCuda(error_code) \ 1719 Assert(error_code == cudaSuccess, \ 1720 dealii::ExcCudaError(cudaGetErrorString(error_code))) 1721 # else 1722 # define AssertCuda(error_code) \ 1723 { \ 1724 (void)(error_code); \ 1725 } 1726 # endif 1727 1728 /** 1729 * The non-throwing equivalent of AssertCuda. 1730 * 1731 * @note This and similar macro names are examples of preprocessor definitions 1732 * in the deal.II library that are not prefixed by a string that likely makes 1733 * them unique to deal.II. As a consequence, it is possible that other 1734 * libraries your code interfaces with define the same name, and the result 1735 * will be name collisions (see 1736 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1737 * this macro, as well as all other macros defined by deal.II that are not 1738 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1739 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1740 * deal.II headers have been included. 1741 * 1742 * @ingroup Exceptions 1743 */ 1744 # ifdef DEBUG 1745 # define AssertNothrowCuda(error_code) \ 1746 AssertNothrow(error_code == cudaSuccess, \ 1747 dealii::ExcCudaError(cudaGetErrorString(error_code))) 1748 # else 1749 # define AssertNothrowCuda(error_code) \ 1750 { \ 1751 (void)(error_code); \ 1752 } 1753 # endif 1754 1755 /** 1756 * An assertion that checks that the kernel was launched and executed 1757 * successfully. 1758 * 1759 * @note This and similar macro names are examples of preprocessor definitions 1760 * in the deal.II library that are not prefixed by a string that likely makes 1761 * them unique to deal.II. As a consequence, it is possible that other 1762 * libraries your code interfaces with define the same name, and the result 1763 * will be name collisions (see 1764 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1765 * this macro, as well as all other macros defined by deal.II that are not 1766 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1767 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1768 * deal.II headers have been included. 1769 * 1770 * @ingroup Exceptions 1771 */ 1772 # ifdef DEBUG 1773 # define AssertCudaKernel() \ 1774 { \ 1775 cudaError_t local_error_code = cudaPeekAtLastError(); \ 1776 AssertCuda(local_error_code); \ 1777 local_error_code = cudaDeviceSynchronize(); \ 1778 AssertCuda(local_error_code) \ 1779 } 1780 # else 1781 # define AssertCudaKernel() \ 1782 {} 1783 # endif 1784 1785 /** 1786 * An assertion that checks that the error code produced by calling a cuSPARSE 1787 * routine is equal to CUSPARSE_STATUS_SUCCESS. 1788 * 1789 * @note This and similar macro names are examples of preprocessor definitions 1790 * in the deal.II library that are not prefixed by a string that likely makes 1791 * them unique to deal.II. As a consequence, it is possible that other 1792 * libraries your code interfaces with define the same name, and the result 1793 * will be name collisions (see 1794 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1795 * this macro, as well as all other macros defined by deal.II that are not 1796 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1797 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1798 * deal.II headers have been included. 1799 * 1800 * @ingroup Exceptions 1801 */ 1802 # ifdef DEBUG 1803 # define AssertCusparse(error_code) \ 1804 Assert( \ 1805 error_code == CUSPARSE_STATUS_SUCCESS, \ 1806 dealii::ExcCusparseError( \ 1807 dealii::deal_II_exceptions::internals::get_cusparse_error_string( \ 1808 error_code))) 1809 # else 1810 # define AssertCusparse(error_code) \ 1811 { \ 1812 (void)(error_code); \ 1813 } 1814 # endif 1815 1816 /** 1817 * The non-throwing equivalent of AssertCusparse. 1818 * 1819 * @note This and similar macro names are examples of preprocessor definitions 1820 * in the deal.II library that are not prefixed by a string that likely makes 1821 * them unique to deal.II. As a consequence, it is possible that other 1822 * libraries your code interfaces with define the same name, and the result 1823 * will be name collisions (see 1824 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1825 * this macro, as well as all other macros defined by deal.II that are not 1826 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1827 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1828 * deal.II headers have been included. 1829 * 1830 * @ingroup Exceptions 1831 */ 1832 # ifdef DEBUG 1833 # define AssertNothrowCusparse(error_code) \ 1834 AssertNothrow( \ 1835 error_code == CUSPARSE_STATUS_SUCCESS, \ 1836 dealii::ExcCusparseError( \ 1837 dealii::deal_II_exceptions::internals::get_cusparse_error_string( \ 1838 error_code))) 1839 # else 1840 # define AssertNothrowCusparse(error_code) \ 1841 { \ 1842 (void)(error_code); \ 1843 } 1844 # endif 1845 1846 /** 1847 * An assertion that checks that the error code produced by calling a cuSOLVER 1848 * routine is equal to CUSOLVER_STATUS_SUCCESS. 1849 * 1850 * @note This and similar macro names are examples of preprocessor definitions 1851 * in the deal.II library that are not prefixed by a string that likely makes 1852 * them unique to deal.II. As a consequence, it is possible that other 1853 * libraries your code interfaces with define the same name, and the result 1854 * will be name collisions (see 1855 * https://en.wikipedia.org/wiki/Name_collision). One can <code>\#undef</code> 1856 * this macro, as well as all other macros defined by deal.II that are not 1857 * prefixed with either <code>DEAL</code> or <code>deal</code>, by including 1858 * the header <code>deal.II/base/undefine_macros.h</code> after all other 1859 * deal.II headers have been included. 1860 * 1861 * @ingroup Exceptions 1862 */ 1863 # ifdef DEBUG 1864 # define AssertCusolver(error_code) \ 1865 Assert( \ 1866 error_code == CUSOLVER_STATUS_SUCCESS, \ 1867 dealii::ExcCusparseError( \ 1868 dealii::deal_II_exceptions::internals::get_cusolver_error_string( \ 1869 error_code))) 1870 # else 1871 # define AssertCusolver(error_code) \ 1872 { \ 1873 (void)(error_code); \ 1874 } 1875 # endif 1876 1877 #endif 1878 1879 using namespace StandardExceptions; 1880 1881 DEAL_II_NAMESPACE_CLOSE 1882 1883 #endif 1884