Reference documentation for deal.II version 8.4.1
exceptions.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2016 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 at
12 // the top level of the deal.II distribution.
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 <string>
23 #include <ostream>
24 
25 DEAL_II_NAMESPACE_OPEN
26 
27 
42 class ExceptionBase : public std::exception
43 {
44 public:
48  ExceptionBase ();
49 
54 
58  virtual ~ExceptionBase () throw();
59 
65  void set_fields (const char *file,
66  const int line,
67  const char *function,
68  const char *cond,
69  const char *exc_name);
70 
71 
75  virtual const char *what() const throw();
76 
80  const char *get_exc_name() const;
81 
85  void print_exc_data (std::ostream &out) const;
86 
91  virtual void print_info (std::ostream &out) const;
92 
97  void print_stack_trace (std::ostream &out) const;
98 
99 protected:
103  const char *file;
104 
108  unsigned int line;
109 
113  const char *function;
114 
118  const char *cond;
119 
123  const char *exc;
124 
129  mutable char **stacktrace;
130 
136 
137 #ifdef DEAL_II_HAVE_GLIBC_STACKTRACE
138 
141  void *raw_stacktrace[25];
142 #endif
143 
144 private:
148  void generate_message() const;
149 
154  mutable std::string what_str;
155 };
156 
157 
158 
166 {
167 
184  void set_additional_assert_output (const char *const p);
185 
195 
208 
216  namespace internals
217  {
218 
233  void abort (const ExceptionBase &exc, bool nothrow = false);
234 
239  {
240  abort_on_exception,
241  throw_on_exception,
242  abort_nothrow_on_exception
243  };
244 
251  template <class exc>
253  const char *file,
254  int line,
255  const char *function,
256  const char *cond,
257  const char *exc_name,
258  exc e)
259  {
260  // Fill the fields of the exception object
261  e.set_fields (file, line, function, cond, exc_name);
262 
263  switch (handling)
264  {
265  case abort_on_exception:
266  ::deal_II_exceptions::internals::abort(e);
267  break;
268  case abort_nothrow_on_exception:
269  ::deal_II_exceptions::internals::abort(e, /*nothrow =*/ true);
270  break;
271  case throw_on_exception:
272  throw e;
273  }
274  }
275 
276  } /*namespace internals*/
277 
278 } /*namespace deal_II_exceptions*/
279 
280 
281 
293 #ifdef DEBUG
294 #define Assert(cond, exc) \
295  { \
296  if (!(cond)) \
297  ::deal_II_exceptions::internals:: \
298  issue_error(::deal_II_exceptions::internals::abort_on_exception,\
299  __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
300  }
301 #else
302 #define Assert(cond, exc) \
303  {}
304 #endif
305 
306 
307 
322 #ifdef DEBUG
323 #define AssertNothrow(cond, exc) \
324  { \
325  if (!(cond)) \
326  ::deal_II_exceptions::internals:: \
327  issue_error( \
328  ::deal_II_exceptions::internals::abort_nothrow_on_exception, \
329  __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
330  }
331 #else
332 #define AssertNothrow(cond, exc) \
333  {}
334 #endif
335 
336 
337 
349 #ifdef DEAL_II_HAVE_BUILTIN_EXPECT
350 #define AssertThrow(cond, exc) \
351  { \
352  if (__builtin_expect(!(cond), false)) \
353  ::deal_II_exceptions::internals:: \
354  issue_error(::deal_II_exceptions::internals::throw_on_exception,\
355  __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
356  }
357 #else /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
358 #define AssertThrow(cond, exc) \
359  { \
360  if (!(cond)) \
361  ::deal_II_exceptions::internals:: \
362  issue_error(::deal_II_exceptions::internals::throw_on_exception,\
363  __FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #exc, exc); \
364  }
365 #endif /*ifdef DEAL_II_HAVE_BUILTIN_EXPECT*/
366 
367 
368 
369 #ifndef DOXYGEN
370 
377 #define DeclException0(Exception0) \
378  class Exception0 : public ::ExceptionBase {}
379 
380 
389 #define DeclExceptionMsg(Exception, defaulttext) \
390  class Exception : public ::ExceptionBase \
391  { \
392  public: \
393  Exception (const std::string &msg = defaulttext) : arg (msg) {} \
394  virtual ~Exception () throw () {} \
395  virtual void print_info (std::ostream &out) const { \
396  out << arg << std::endl; \
397  } \
398  private: \
399  const std::string arg; \
400  }
401 
408 #define DeclException1(Exception1, type1, outsequence) \
409  class Exception1 : public ::ExceptionBase { \
410  public: \
411  Exception1 (const type1 a1) : arg1 (a1) {} \
412  virtual ~Exception1 () throw () {} \
413  virtual void print_info (std::ostream &out) const { \
414  out outsequence << std::endl; \
415  } \
416  private: \
417  const type1 arg1; \
418  }
419 
420 
427 #define DeclException2(Exception2, type1, type2, outsequence) \
428  class Exception2 : public ::ExceptionBase { \
429  public: \
430  Exception2 (const type1 a1, const type2 a2) : \
431  arg1 (a1), arg2(a2) {} \
432  virtual ~Exception2 () throw () {} \
433  virtual void print_info (std::ostream &out) const { \
434  out outsequence << std::endl; \
435  } \
436  private: \
437  const type1 arg1; \
438  const type2 arg2; \
439  }
440 
441 
448 #define DeclException3(Exception3, type1, type2, type3, outsequence) \
449  class Exception3 : public ::ExceptionBase { \
450  public: \
451  Exception3 (const type1 a1, const type2 a2, const type3 a3) : \
452  arg1 (a1), arg2(a2), arg3(a3) {} \
453  virtual ~Exception3 () throw () {} \
454  virtual void print_info (std::ostream &out) const { \
455  out outsequence << std::endl; \
456  } \
457  private: \
458  const type1 arg1; \
459  const type2 arg2; \
460  const type3 arg3; \
461  }
462 
463 
470 #define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
471  class Exception4 : public ::ExceptionBase { \
472  public: \
473  Exception4 (const type1 a1, const type2 a2, \
474  const type3 a3, const type4 a4) : \
475  arg1 (a1), arg2(a2), arg3(a3), arg4(a4) {} \
476  virtual ~Exception4 () throw () {} \
477  virtual void print_info (std::ostream &out) const { \
478  out outsequence << std::endl; \
479  } \
480  private: \
481  const type1 arg1; \
482  const type2 arg2; \
483  const type3 arg3; \
484  const type4 arg4; \
485  }
486 
487 
494 #define DeclException5(Exception5, type1, type2, type3, type4, type5, outsequence) \
495  class Exception5 : public ::ExceptionBase { \
496  public: \
497  Exception5 (const type1 a1, const type2 a2, const type3 a3, \
498  const type4 a4, const type5 a5) : \
499  arg1 (a1), arg2(a2), arg3(a3), arg4(a4), arg5(a5) {} \
500  virtual ~Exception5 () throw () {} \
501  virtual void print_info (std::ostream &out) const { \
502  out outsequence << std::endl; \
503  } \
504  private: \
505  const type1 arg1; \
506  const type2 arg2; \
507  const type3 arg3; \
508  const type4 arg4; \
509  const type5 arg5; \
510  }
511 
512 #else /*ifndef DOXYGEN*/
513 
514 // Dummy definitions for doxygen:
515 
522 #define DeclException0(Exception0) \
523  static ::ExceptionBase& Exception0 ()
524 
533 #define DeclExceptionMsg(Exception, defaulttext) \
534  static ::ExceptionBase& Exception ()
535 
542 #define DeclException1(Exception1, type1, outsequence) \
543  static ::ExceptionBase& Exception1 (type1 arg1) throw (errortext outsequence)
544 
545 
552 #define DeclException2(Exception2, type1, type2, outsequence) \
553  static ::ExceptionBase& Exception2 (type1 arg1, type2 arg2) throw (errortext outsequence)
554 
555 
562 #define DeclException3(Exception3, type1, type2, type3, outsequence) \
563  static ::ExceptionBase& Exception3 (type1 arg1, type2 arg2, type3 arg3) throw (errortext outsequence)
564 
565 
572 #define DeclException4(Exception4, type1, type2, type3, type4, outsequence) \
573  static ::ExceptionBase& Exception4 (type1 arg1, type2 arg2, type3 arg3, type4 arg4) throw (errortext outsequence)
574 
575 
582 #define DeclException5(Exception5, type1, type2, type3, type4, type5, outsequence) \
583  static ::ExceptionBase& Exception5 (type1 arg1, type2 arg2, type3 arg3, type4 arg4, type5 arg5) throw (errortext outsequence)
584 
585 #endif /*ifndef DOXYGEN*/
586 
587 
600 {
605 
609  DeclExceptionMsg (ExcDivideByZero,
610  "A piece of code is attempting a division by zero. This is "
611  "likely going to lead to results that make no sense.");
612 
624  std::complex<double>,
625  << "In a significant number of places, deal.II checks that some intermediate "
626  << "value is a finite number (as opposed to plus or minus infinity, or "
627  << "NaN/Not a Number). In the current function, we encountered a number "
628  << "that is not finite (its value is " << arg1 << " and therefore "
629  << "violates the current assertion.\n\n"
630  << "This may be due to the fact that some operation in this function "
631  << "created such a value, or because one of the arguments you passed "
632  << "to the function already had this value from some previous "
633  << "operation. In the latter case, this function only triggered the "
634  << "error but may not actually be responsible for the computation of "
635  << "the number that is not finite.\n\n"
636  << "There are two common cases where this situation happens. First, your "
637  << "code (or something in deal.II) divides by zero in a place where this "
638  << "should not happen. Or, you are trying to solve a linear system "
639  << "with an unsuitable solver (such as an indefinite or non-symmetric "
640  << "linear system using a Conjugate Gradient solver); such attempts "
641  << "oftentimes yield an operation somewhere that tries to divide "
642  << "by zero or take the square root of a negative value.\n\n"
643  << "In any case, when trying to find the source of the error, "
644  << "recall that the location where you are getting this error is "
645  << "simply the first place in the program where there is a check "
646  << "that a number (e.g., an element of a solution vector) is in fact "
647  << "finite, but that the actual error that computed the number "
648  << "may have happened far earlier. To find this location, you "
649  << "may want to add checks for finiteness in places of your "
650  << "program visited before the place where this error is produced."
651  << "One way to check for finiteness is to use the 'AssertIsFinite' "
652  << "macro.");
653 
657  DeclExceptionMsg (ExcOutOfMemory,
658  "Your program tried to allocate some memory but this "
659  "allocation failed. Typically, this either means that "
660  "you simply do not have enough memory in your system, "
661  "or that you are (erroneously) trying to allocate "
662  "a chunk of memory that is simply beyond all reasonable "
663  "size, for example because the size of the object has "
664  "been computed incorrectly.");
665 
670  DeclException1 (ExcMemoryLeak, int,
671  << "Destroying memory handler while " << arg1
672  << " objects are still allocated");
673 
677  DeclExceptionMsg (ExcIO,
678  "An input/output error has occurred. There are a number of "
679  "reasons why this may be happening, both for reading and "
680  "writing operations."
681  "\n\n"
682  "If this happens during an operation that tries to read "
683  "data: First, you may be "
684  "trying to read from a file that doesn't exist or that is "
685  "not readable given its file permissions. Second, deal.II "
686  "uses this error at times if it tries to "
687  "read information from a file but where the information "
688  "in the file does not correspond to the expected format. "
689  "An example would be a truncated file, or a mesh file "
690  "that contains not only sections that describe the "
691  "vertices and cells, but also sections for additional "
692  "data that deal.II does not understand."
693  "\n\n"
694  "If this happens during an operation that tries to write "
695  "data: you may be trying to write to a file to which file "
696  "or directory permissions do not allow you to write. A "
697  "typical example is where you specify an output file in "
698  "a directory that does not exist.");
699 
706  DeclException1 (ExcFileNotOpen,
707  char *,
708  << "Could not open file " << arg1);
709 
718  DeclExceptionMsg (ExcNotImplemented,
719  "You are trying to use functionality in deal.II that is "
720  "currently not implemented. In many cases, this indicates "
721  "that there simply didn't appear much of a need for it, or "
722  "that the author of the original code did not have the "
723  "time to implement a particular case. If you hit this "
724  "exception, it is therefore worth the time to look into "
725  "the code to find out whether you may be able to "
726  "implement the missing functionality. If you do, please "
727  "consider providing a patch to the deal.II development "
728  "sources (see the deal.II website on how to contribute).");
729 
750  DeclExceptionMsg (ExcInternalError,
751  "This exception -- which is used in many places in the "
752  "library -- usually indicates that some condition which "
753  "the author of the code thought must be satisfied at a "
754  "certain point in an algorithm, is not fulfilled. An "
755  "example would be that the first part of an algorithm "
756  "sorts elements of an array in ascending order, and "
757  "a second part of the algorithm later encounters an "
758  "an element that is not larger than the previous one."
759  "\n\n"
760  "There is usually not very much you can do if you "
761  "encounter such an exception since it indicates an error "
762  "in deal.II, not in your own program. Try to come up with "
763  "the smallest possible program that still demonstrates "
764  "the error and contact the deal.II mailing lists with it "
765  "to obtain help.");
766 
773  DeclExceptionMsg (ExcPureFunctionCalled,
774  "You (or a place in the library) are trying to call a "
775  "function that is declared as a virtual function in a "
776  "base class but that has not been overridden in your "
777  "derived class."
778  "\n\n"
779  "This exception happens in cases where the base class "
780  "cannot provide a useful default implementation for "
781  "the virtual function, but where we also do not want "
782  "to mark the function as abstract (i.e., with '=0' at the end) "
783  "because the function is not essential to the class in many "
784  "contexts. In cases like this, the base class provides "
785  "a dummy implementation that makes the compiler happy, but "
786  "that then throws the current exception."
787  "\n\n"
788  "A concrete example would be the 'Function' class. It declares "
789  "the existence of 'value()' and 'gradient()' member functions, "
790  "and both are marked as 'virtual'. Derived classes have to "
791  "override these functions for the values and gradients of a "
792  "particular function. On the other hand, not every function "
793  "has a gradient, and even for those that do, not every program "
794  "actually needs to evaluate it. Consequently, there is no "
795  "*requirement* that a derived class actually override the "
796  "'gradient()' function (as there would be had it been marked "
797  "as abstract). But, since the base class cannot know how to "
798  "compute the gradient, if a derived class does not override "
799  "the 'gradient()' function and it is called anyway, then the "
800  "default implementation in the base class will simply throw "
801  "an exception."
802  "\n\n"
803  "The exception you see is what happens in cases such as the "
804  "one just illustrated. To fix the problem, you need to "
805  "investigate whether the function being called should indeed have "
806  "been called; if the answer is 'yes', then you need to "
807  "implement the missing override in your class.");
808 
814  DeclException0 (ExcInvalidConstructorCall);
815 
819  DeclException0 (ExcNotInitialized);
820 
824  DeclException0 (ExcInvalidState);
825 
832  DeclException1 (ExcImpossibleInDim,
833  int,
834  << "You are trying to execute functionality that is "
835  << "impossible in " << arg1
836  << "d or simply does not make any sense.");
837 
841  DeclExceptionMsg(ExcZero,
842  "In a check in the code, deal.II encountered a zero in "
843  "a place where this does not make sense. See the condition "
844  "that was being checked and that is printed further up "
845  "in the error message to get more information on what "
846  "the erroneous zero corresponds to.");
847 
852  DeclExceptionMsg(ExcEmptyObject,
853  "The object you are trying to access is empty but it makes "
854  "no sense to attempt the operation you are trying on an "
855  "empty object.");
856 
864  DeclException2 (ExcDimensionMismatch,
865  std::size_t, std::size_t,
866  << "Dimension " << arg1 << " not equal to " << arg2);
867 
872  DeclException3 (ExcDimensionMismatch2,
873  int, int, int,
874  << "Dimension " << arg1 << " neither equal to " << arg2
875  << " nor to " << arg3);
876 
889  DeclException3 (ExcIndexRange,
890  int, int, int,
891  << "Index " << arg1 << " is not in the half-open range [" << arg2 << ","
892  << arg3 << ")."
893  << (arg2==arg3 ?
894  " In the current case, this half-open range is in fact empty, "
895  "suggesting that you are accessing an element of an empty "
896  "collection such as a vector that has not been set to the "
897  "correct size."
898  :
899  ""));
900 
916  template <typename T>
918  T,T,T,
919  << "Index " << arg1 << " is not in the half-open range [" << arg2 << ","
920  << arg3 << ")."
921  << (arg2==arg3 ?
922  " In the current case, this half-open range is in fact empty, "
923  "suggesting that you are accessing an element of an empty "
924  "collection such as a vector that has not been set to the "
925  "correct size."
926  :
927  ""));
928 
933  int, int,
934  << "Number " << arg1 << " must be larger than or equal "
935  << arg2 << ").");
936 
940  template <typename T>
942  T, T,
943  << "Number " << arg1 << " must be larger than or equal "
944  << arg2 << ".");
945 
951  int, int,
952  << "Division " << arg1 << " by " << arg2
953  << " has remainder different from zero");
954 
963  DeclExceptionMsg (ExcInvalidIterator,
964  "You are trying to use an iterator, but the iterator is "
965  "in an invalid state. This may indicate that the iterator "
966  "object has not been initialized, or that it has been "
967  "moved beyond the end of the range of valid elements.");
968 
973  DeclExceptionMsg (ExcIteratorPastEnd,
974  "You are trying to use an iterator, but the iterator is "
975  "pointing past the end of the range of valid elements. "
976  "It is not valid to dereference the iterator in this "
977  "case.");
978 
993  std::string,
994  << arg1);
995 
999  DeclExceptionMsg (ExcGhostsPresent,
1000  "You are trying an operation on a vector that is only "
1001  "allowed if the vector has no ghost elements, but the "
1002  "vector you are operating on does have ghost elements. "
1003  "Specifically, vectors with ghost elements are read-only "
1004  "and cannot appear in operations that write into these "
1005  "vectors."
1006  "\n\n"
1007  "See the glossary entry on 'Ghosted vectors' for more "
1008  "information.");
1009 
1017  DeclExceptionMsg (ExcScalarAssignmentOnlyForZeroValue,
1018  "You are trying an operation of the form 'vector=s' with "
1019  "a nonzero scalar value 's'. However, such assignments "
1020  "are only allowed if the right hand side is zero.");
1021 
1026 
1031 
1036 
1037 
1039 } /*namespace StandardExceptions*/
1040 
1041 
1052 #define AssertDimension(dim1,dim2) Assert((dim1) == (dim2), \
1053  ::ExcDimensionMismatch((dim1),(dim2)))
1054 
1055 
1063 #define AssertVectorVectorDimension(vec,dim1,dim2) AssertDimension((vec).size(), (dim1)) \
1064  for (unsigned int i=0;i<dim1;++i) { AssertDimension((vec)[i].size(), (dim2)); }
1065 
1066 
1081 #define AssertIndexRange(index,range) Assert((index) < (range), \
1082  ::ExcIndexRange((index),0,(range)))
1083 
1084 #define AssertGlobalIndexRange(index,range) Assert((index) < (range), \
1085  ExcIndexRange<types::global_dof_index>((index),0,(range)))
1086 
1096 #define AssertIsFinite(number) Assert(::numbers::is_finite(number), \
1097  ExcNumberNotFinite(std::complex<double>(number)))
1098 
1099 using namespace StandardExceptions;
1100 
1101 DEAL_II_NAMESPACE_CLOSE
1102 
1103 #endif
::ExceptionBase & ExcLowerRangeType(T arg1, T arg2)
void print_exc_data(std::ostream &out) const
Definition: exceptions.cc:149
virtual const char * what() const
Definition: exceptions.cc:120
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:552
void suppress_stacktrace_in_exceptions()
Definition: exceptions.cc:46
::ExceptionBase & ExcMessage(std::string arg1)
void set_additional_assert_output(const char *const p)
Definition: exceptions.cc:39
void abort(const ExceptionBase &exc, bool nothrow=false)
Definition: exceptions.cc:316
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:542
void set_fields(const char *file, const int line, const char *function, const char *cond, const char *exc_name)
Definition: exceptions.cc:98
void generate_message() const
Definition: exceptions.cc:270
virtual void print_info(std::ostream &out) const
Definition: exceptions.cc:164
#define DeclException0(Exception0)
Definition: exceptions.h:522
::ExceptionBase & ExcLowerRange(int arg1, int arg2)." )
::ExceptionBase & ExcNeedsFunctionparser()
::ExceptionBase & ExcNeedsNetCDF()
std::string what_str
Definition: exceptions.h:154
::ExceptionBase & ExcNeedsLAPACK()
unsigned int line
Definition: exceptions.h:108
void print_stack_trace(std::ostream &out) const
Definition: exceptions.cc:171
const char * exc
Definition: exceptions.h:123
::ExceptionBase & ExcNumberNotFinite(std::complex< double > arg1)
const char * cond
Definition: exceptions.h:118
const char * file
Definition: exceptions.h:103
::ExceptionBase & ExcIndexRangeType(T arg1, T arg2, T arg3)." << (arg2
::ExceptionBase & ExcNotMultiple(int arg1, int arg2)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition: exceptions.h:562
virtual ~ExceptionBase()
Definition: exceptions.cc:90
const char * get_exc_name() const
Definition: exceptions.cc:142
char ** stacktrace
Definition: exceptions.h:129
void disable_abort_on_exception()
Definition: exceptions.cc:53
int n_stacktrace_frames
Definition: exceptions.h:135
void issue_error(ExceptionHandling handling, const char *file, int line, const char *function, const char *cond, const char *exc_name, exc e)
Definition: exceptions.h:252
DeclExceptionMsg(ExcDivideByZero,"A piece of code is attempting a division by zero. This is ""likely going to lead to results that make no sense.")