/**
- * This class should be used as a base class for all exception
- * classes. Do not use its methods and variables directly since the
- * interface and mechanism may be subject to change. Rather create
- * new exception classes using the <tt>DeclException</tt> macro
- * family.
- *
- *
- * <h3>General overview of the exception handling mechanism in deal.II</h3>
- *
- * The error handling mechanism in <tt>deal.II</tt> is generally used in two ways.
- * The first uses error checking in debug mode only and is useful for programs
- * which are not fully tested. When the program shows no error anymore, one may
- * switch off error handling and get better performance by this, since checks
- * for errors are done quite frequently in the library (a typical speed up is
- * a factor of four!). This mode of exception generation is most useful for
- * internal consistency checks such as range checking or checking of the
- * validity of function arguments. Errors of this kind usually are programming
- * errors and the program should abort with as detailed a message as possible,
- * including location and reason for the generation of the exception.
- *
- * The second mode is for error checks which should always be on, such as for
- * I/O errors, failing memory requests and the like. It does not make much
- * sense to turn this mode off, since this kind of errors may happen in tested
- * and untested programs likewise. Exceptions of this kind do not terminate the
- * program, rather they throw exceptions in the <tt>C++</tt> manner, allowing the
- * program to catch them and eventually do something about it. As it may be
- * useful to have some information printed out if an exception could not be
- * handled properly, additional information is passed along as for the first
- * mode. The latter makes it necessary to provide a family of macros which
- * enter this additional information into the exception class; this could
- * in principle be done by the programmer himself each time by hand, but since
- * the information can be obtained automatically, a macro is provided for
- * this.
- *
- * Both modes use exception classes, which need to have special features
- * in additional to the <tt>C++</tt> standard's <tt>exception</tt> class. Such a class
- * is declared by the following lines of code:
- * @code
- * DeclException2 (ExcDomain, int, int,
- * << "Index= " << arg1 << "Upper Bound= " << arg2);
- * @endcode
- * This declares an exception class named <tt>ExcDomain</tt>, which
- * has two variables as additional information (named
- * <tt>arg1</tt> and <tt>arg2</tt> by default) and which outputs the
- * given sequence (which is appended to an <tt>std::ostream</tt>
- * variable's name, thus the weird syntax). There are
- * other <tt>DeclExceptionN</tt> macros for exception classes
- * with more or no parameters. It is proposed to let start
- * the name of all exceptions by <tt>Exc...</tt> and to declare them locally to
- * the class it is to be used in. Declaring exceptions globally is possible
- * but pollutes the global namespace, is less readable and thus unnecessary.
- *
- * Since exception classes are declared the same way for both modes of error
- * checking, it is possible to use an exception declared through the
- * <tt>DeclExceptionN(...)</tt> macro family in both modes; there is no need to
- * declare different classes for each of these.
- *
- *
- * <h3>Use of the debug mode exceptions</h3>
- *
- * To use the exception mechanism for debug mode error checking, write lines
- * like the following in your source code:
- * @code
- * Assert (n<dim, ExcDomain(n,dim));
- * @endcode
- * which by macro expansion does the following:
- * @code
- * #ifdef DEBUG
- * if (!(cond))
- * issue error of class ExcDomain(n,dim)
- * #else
- * do nothing
- * #endif
- * @endcode
- * i.e. it issues an error only if the preprocessor variable
- * <tt>DEBUG</tt> is set and if the given condition (in this case
- * <tt>n < dim</tt> is violated).
- *
- * If the exception was declared using the <tt>DeclException0 (...)</tt>
- * macro, i.e. without any additional parameters, its name has
- * nonetheless to be given with parentheses:
- * <tt>Assert (i>m, ExcSomewhat());</tt>
- *
- * <h4>How it works internally</h4>
- *
- * If the <tt>DEBUG</tt> preprocessor directive is set, the call <tt>Assert
- * (cond, exc);</tt> is basically converted by the preprocessor into the
- * sequence (note that function names and exact calling sequences may
- * change over time, but the general principle remains the same)
- * @code
- * if (!(cond))
- * deal_II_exceptions::internals::issue_error_assert_1
- * (__FILE__,
- * __LINE__,
- * __PRETTY_FUNCTION__,
- * #cond,
- * #exc,
- * &exc);
- * @endcode
- * i.e. if the given condition is violated, then the file and
- * line in which the exception occured as well as
- * the condition itself and the call sequence of the
- * exception object is transferred. Additionally an object
- * of the form given by <tt>exc</tt> is created (this is normally an
- * unnamed object like in <tt>ExcDomain (n, dim)</tt> of class
- * <tt>ExcDomain</tt>) and transferred to the deal_II_exceptions::internals::issue_error_assert_1()
- * function.
- *
- * <tt>__PRETTY__FUNCTION__</tt> is a macro defined by some compilers and
- * gives the name of the function. If another compiler is used, we
- * try to set this function to something reasonable, if the compiler
- * provides us with that, and <tt>"(not available)"</tt> otherwise.
- *
- * In <tt>__IssueError</tt> the given data is transferred into the
- * <tt>exc</tt> object by calling the set_fields() function; after that, the
- * general error info is printed onto <tt>std::cerr</tt> using the
- * PrintError() function of <tt>exc</tt> and finally the exception specific
- * data is printed using the user defined function PrintError() (which is
- * normally created using the <tt>DeclException (...)</tt> macro family. If
- * it can be obtained from the operating system, the output may also contain
- * a stacktrace to show where the error happened.
- *
- * After printing all this information,
- * deal_II_exceptions::internals::abort() is called (with one
- * exception, see the end of this section). This terminates the
- * program, which is the right thing to do for this kind of error
- * checking since it is used to detect programming errors rather than
- * run-time errors; a program can, by definition, not recover from
- * programming errors.
- *
- * If the preprocessor variable <tt>DEBUG</tt> is not set, then nothing
- * happens, i.e. the <tt>Assert</tt> macro is expanded to <tt>{}</tt>.
- *
- * Sometimes, there is no useful condition for an exception other
- * than that the program flow should not have reached a certain point,
- * e.g. a <tt>default</tt> section of a <tt>switch</tt> statement. In this case,
- * raise the exception by the following construct:
- * @verbatim
- * Assert (false, ExcInternalError());
- * @endverbatim
- *
- * As mentioned above, the program is terminated once a call to
- * <tt>Assert</tt> fails. However, there is one case where we do not want
- * to do this, namely when a C++ exception is active. The usual case
- * where this happens is that someone throws an exception through the
- * <tt>AssertThrow</tt> mechanism (see below) which, while the stack is
- * unwound, leads to the destruction of other objects in stack frames
- * above. If other objects refer to the objects being thus destroyed,
- * some destructors raise an exception through <tt>Assert</tt>. If we
- * would abort the program then, we would only ever see the message
- * that an object is being destroyed which is still referenced from
- * somewhere, but we would never see the original exception that
- * triggered this. (You can see it in the debugger by putting a break
- * point on the function <tt>__throw</tt>, but you cannot see it from the
- * program itself.) In that case, we use a C++ standard library
- * function to detect the presence of another active exception and do
- * not terminate the program to allow that the thrown exception
- * propagates to some place where its message can be displayed.
- *
- * Since it is common that one failed assertion leads to a whole
- * chain of others, we only ever print the very first message. If the
- * program is then aborted, that is no problem. If it is not (since a
- * C++ exception is active), only the first is displayed and a
- * message about suppressed follow-up messages is shown.
- *
- *
- * <h3>Use of run-time exceptions</h3>
- *
- * For this mode, the standard <tt>C++</tt> <tt>throw</tt> and <tt>catch</tt> concept exists. We
- * want to keep to this, but want to extend it a bit. In general, the
- * structure is the same, i.e. you normally raise and exception by
- * @code
- * if (!(cond))
- * throw ExcSomething();
- * @endcode
- * and catch it using the statement
- * @code
- * try {
- * do_something ();
- * }
- * catch (exception &e) {
- * std::cerr << "Exception occured:" << std::endl
- * << e.what ()
- * << std::endl;
- * do_something_to_reciver ();
- * };
- * @endcode
- * <tt>exception</tt> is a standard <tt>C++</tt> class providing basic functionality for
- * exceptions, such as the virtual function <tt>what()</tt> which returns some
- * information on the exception itself. This information is useful if an
- * exception can't be handled properly, in which case as precise a description
- * as possible should be printed.
- *
- * The problem here is that to get significant and useful information out
- * of <tt>what()</tt>, it is necessary to overload this function in out exception
- * class and call the <tt>throw</tt> operator with additional arguments to the
- * exception class. The first thing, overloading the <tt>what</tt> function is
- * done using the <tt>DeclExceptionN</tt> macros, but putting the right information,
- * which is the same as explained above for the <tt>Assert</tt> expansion, requires
- * some work if one would want to write it down each time:
- * @code
- * if (!(cond))
- * {
- * ExcSomething e(additional information);
- * e.set_fields (__FILE__, __LINE__, __PRETTY_FUNCTION__,
- * "condition as a string",
- * "name of condition as a string");
- * throw e;
- * };
- * @endcode
- *
- * For this purpose, the macro <tt>AssertThrow</tt> was invented. It does
- * mainly the same job as does the <tt>Assert</tt> macro, but it does not
- * kill the program, it rather throws an exception as shown above. The mode
- * of usage is
- * @code
- * AssertThrow (cond, ExcSomething(additional information));
- * @endcode
- *
- * The condition to be checked is incorporated into the macro in order to
- * allow passing the violated condition as a string. The expansion of the
- * <tt>AssertThrow</tt> macro is not affected by the <tt>DEBUG</tt>
- * preprocessor variable.
- *
- *
- * <h3>Description of the DeclExceptionN macro family</h3>
- *
- * Declare an exception class without any additional parameters.
- * There is a whole family of <tt>DeclException?</tt> macros
- * where <tt>?</tt> is to be replaced by the number of additional
- * parameters (0 to 5 presently).
- *
- * The syntax is as follows:
- * @code
- * DeclException2 (ExcDomain,
- * int,
- * int,
- * << " i=" << arg1 << ", m=" << arg2);
- * @endcode
- * The first is the name of the exception class to be created.
- * The next arguments are the types of the parameters (in this
- * case there are two type names needed) and finally the output
- * sequence with which you can print additional information.
- *
- * The syntax of the output sequence is a bit weird but gets
- * clear once you see how this macro is defined:
- * @code
- * class name : public ExceptionBase {
- * public:
- * name (const type1 a1, const type2 a2) :
- * arg1 (a1), arg2(a2) {};
- * virtual void print_info (std::ostream &out) const {
- * out outsequence << std::endl;
- * };
- * private:
- * type1 arg1;
- * type2 arg2;
- * };
- * @endcode
- *
- * If declared as specified, you can later use this exception class
- * in the following manner:
- * @code
- * int i=5;
- * int m=3;
- * Assert (i<m, MyExc2(i,m));
- * @endcode
- * and the output if the condition fails will be
- * @verbatim
- * --------------------------------------------------------
- * An error occurred in line <301> of file <exc-test.cc>.
- * The violated condition was:
- * i<m
- * The name and call sequence of the exception was:
- * MyExc2(i,m)
- * Additional Information:
- * i=5, m=3
- * --------------------------------------------------------
- * @endverbatim
- *
- * Obviously for the <tt>DeclException0(name)</tt> macro, no types and
- * also no output sequence is allowed.
+ * This class is the base class for all exception classes. Do not use
+ * its methods and variables directly since the interface and
+ * mechanism may be subject to change. Rather create new exception
+ * classes using the <tt>DeclException</tt> macro family.
*
+ * See the @ref Exceptions module for more details on this class and
+ * what can be done with classes derived from it.
*
* @ingroup Exceptions
- * @author Wolfgang Bangerth, November 1997, extensions 1998
+ * @author Wolfgang Bangerth, 1997, extensions 1998
*/
class ExceptionBase : public std::exception
{
* @defgroup Exceptions Exceptions and assertions
*
* This module contains classes that are used in the exception mechanism of
- * deal.II. Exceptions are used in two different ways:
+ * deal.II.
*
+ * <h2>Brief overview</h2>
+ *
+ * Exceptions are used in two different ways:
* <ul>
*
* <li> Static assertions: These are checks that are only enabled in debug
*
* Rather, one has to check them every time during execution of a
* program. Within deal.II, this is done using the AssertThrow macro
- * introduced in step-9, step-13, and following tutorial programs. The macro
- * checks a condition, and if violated throws an exception of one of the
- * types declared in this module, using the C++ <code>throw</code>
- * mechanism. Since these are run-time exceptions, this gives the program
- * the chance to catch the exception and, for example, write the output to a
+ * introduced in @ref step_9 "step-9", @ref step_13 "step-13", and
+ * following tutorial programs. The macro checks a condition, and if
+ * violated throws an exception of one of the types declared in this
+ * module, using the C++ <code>throw</code> mechanism. Since these
+ * are run-time exceptions, this gives the program the chance to
+ * catch the exception and, for example, write the output to a
* writable file instead.
* </ul>
+ *
+ *
+ * <h2>Detailed description</h2>
+ *
+ * The error handling mechanism in <tt>deal.II</tt> is generally used in two ways.
+ * The first uses error checking in debug mode only and is useful for programs
+ * which are not fully tested. When the program shows no error anymore, one may
+ * switch off error handling and get better performance by this, since checks
+ * for errors are done quite frequently in the library (a typical speed up is
+ * a factor of four!). This mode of exception generation is most useful for
+ * internal consistency checks such as range checking or checking of the
+ * validity of function arguments. Errors of this kind usually are programming
+ * errors and the program should abort with as detailed a message as possible,
+ * including location and reason for the generation of the exception.
+ *
+ * The second mode is for error checks which should always be on, such as for
+ * I/O errors, failing memory requests and the like. It does not make much
+ * sense to turn this mode off, since this kind of errors may happen in tested
+ * and untested programs likewise. Exceptions of this kind do not terminate the
+ * program, rather they throw exceptions in the <tt>C++</tt> manner, allowing the
+ * program to catch them and eventually do something about it. As it may be
+ * useful to have some information printed out if an exception could not be
+ * handled properly, additional information is passed along as for the first
+ * mode. The latter makes it necessary to provide a family of macros which
+ * enter this additional information into the exception class; this could
+ * in principle be done by the programmer himself each time by hand, but since
+ * the information can be obtained automatically, a macro is provided for
+ * this.
+ *
+ * Both modes use exception classes, which need to have special features
+ * in additional to the <tt>C++</tt> standard's <tt>exception</tt> class. Such a class
+ * is declared by the following lines of code:
+ * @code
+ * DeclException2 (ExcDomain, int, int,
+ * << "Index= " << arg1 << "Upper Bound= " << arg2);
+ * @endcode
+ * This declares an exception class named <tt>ExcDomain</tt>, which
+ * has two variables as additional information (named
+ * <tt>arg1</tt> and <tt>arg2</tt> by default) and which outputs the
+ * given sequence (which is appended to an <tt>std::ostream</tt>
+ * variable's name, thus the weird syntax). There are
+ * other <tt>DeclExceptionN</tt> macros for exception classes
+ * with more or no parameters. It is proposed to let start
+ * the name of all exceptions by <tt>Exc...</tt> and to declare them locally to
+ * the class it is to be used in. Declaring exceptions globally is possible
+ * but pollutes the global namespace, is less readable and thus unnecessary.
+ *
+ * Since exception classes are declared the same way for both modes of error
+ * checking, it is possible to use an exception declared through the
+ * <tt>DeclExceptionN(...)</tt> macro family in both modes; there is no need to
+ * declare different classes for each of these.
+ *
+ *
+ * <h3>Use of the debug mode exceptions</h3>
+ *
+ * To use the exception mechanism for debug mode error checking, write lines
+ * like the following in your source code:
+ * @code
+ * Assert (n<dim, ExcDomain(n,dim));
+ * @endcode
+ * which by macro expansion does the following:
+ * @code
+ * #ifdef DEBUG
+ * if (!(cond))
+ * issue error of class ExcDomain(n,dim)
+ * #else
+ * do nothing
+ * #endif
+ * @endcode
+ * i.e. it issues an error only if the preprocessor variable
+ * <tt>DEBUG</tt> is set and if the given condition (in this case
+ * <tt>n < dim</tt> is violated).
+ *
+ * If the exception was declared using the <tt>DeclException0 (...)</tt>
+ * macro, i.e. without any additional parameters, its name has
+ * nonetheless to be given with parentheses:
+ * <tt>Assert (i>m, ExcSomewhat());</tt>
+ *
+ * <h4>How it works internally</h4>
+ *
+ * If the <tt>DEBUG</tt> preprocessor directive is set, the call <tt>Assert
+ * (cond, exc);</tt> is basically converted by the preprocessor into the
+ * sequence (note that function names and exact calling sequences may
+ * change over time, but the general principle remains the same)
+ * @code
+ * if (!(cond))
+ * deal_II_exceptions::internals::issue_error_assert_1
+ * (__FILE__,
+ * __LINE__,
+ * __PRETTY_FUNCTION__,
+ * #cond,
+ * #exc,
+ * &exc);
+ * @endcode
+ * i.e. if the given condition is violated, then the file and
+ * line in which the exception occured as well as
+ * the condition itself and the call sequence of the
+ * exception object is transferred. Additionally an object
+ * of the form given by <tt>exc</tt> is created (this is normally an
+ * unnamed object like in <tt>ExcDomain (n, dim)</tt> of class
+ * <tt>ExcDomain</tt>) and transferred to the deal_II_exceptions::internals::issue_error_assert_1()
+ * function.
+ *
+ * <tt>__PRETTY__FUNCTION__</tt> is a macro defined by some compilers and
+ * gives the name of the function. If another compiler is used, we
+ * try to set this function to something reasonable, if the compiler
+ * provides us with that, and <tt>"(not available)"</tt> otherwise.
+ *
+ * In <tt>__IssueError</tt> the given data is transferred into the
+ * <tt>exc</tt> object by calling the set_fields() function; after that, the
+ * general error info is printed onto <tt>std::cerr</tt> using the
+ * PrintError() function of <tt>exc</tt> and finally the exception specific
+ * data is printed using the user defined function PrintError() (which is
+ * normally created using the <tt>DeclException (...)</tt> macro family. If
+ * it can be obtained from the operating system, the output may also contain
+ * a stacktrace to show where the error happened.
+ *
+ * After printing all this information,
+ * deal_II_exceptions::internals::abort() is called (with one
+ * exception, see the end of this section). This terminates the
+ * program, which is the right thing to do for this kind of error
+ * checking since it is used to detect programming errors rather than
+ * run-time errors; a program can, by definition, not recover from
+ * programming errors.
+ *
+ * If the preprocessor variable <tt>DEBUG</tt> is not set, then nothing
+ * happens, i.e. the <tt>Assert</tt> macro is expanded to <tt>{}</tt>.
+ *
+ * Sometimes, there is no useful condition for an exception other
+ * than that the program flow should not have reached a certain point,
+ * e.g. a <tt>default</tt> section of a <tt>switch</tt> statement. In this case,
+ * raise the exception by the following construct:
+ * @verbatim
+ * Assert (false, ExcInternalError());
+ * @endverbatim
+ *
+ * As mentioned above, the program is terminated once a call to
+ * <tt>Assert</tt> fails. However, there is one case where we do not want
+ * to do this, namely when a C++ exception is active. The usual case
+ * where this happens is that someone throws an exception through the
+ * <tt>AssertThrow</tt> mechanism (see below) which, while the stack is
+ * unwound, leads to the destruction of other objects in stack frames
+ * above. If other objects refer to the objects being thus destroyed,
+ * some destructors raise an exception through <tt>Assert</tt>. If we
+ * would abort the program then, we would only ever see the message
+ * that an object is being destroyed which is still referenced from
+ * somewhere, but we would never see the original exception that
+ * triggered this. (You can see it in the debugger by putting a break
+ * point on the function <tt>__throw</tt>, but you cannot see it from the
+ * program itself.) In that case, we use a C++ standard library
+ * function to detect the presence of another active exception and do
+ * not terminate the program to allow that the thrown exception
+ * propagates to some place where its message can be displayed.
+ *
+ * Since it is common that one failed assertion leads to a whole
+ * chain of others, we only ever print the very first message. If the
+ * program is then aborted, that is no problem. If it is not (since a
+ * C++ exception is active), only the first is displayed and a
+ * message about suppressed follow-up messages is shown.
+ *
+ *
+ * <h3>Use of run-time exceptions</h3>
+ *
+ * For this mode, the standard <tt>C++</tt> <tt>throw</tt> and <tt>catch</tt> concept exists. We
+ * want to keep to this, but want to extend it a bit. In general, the
+ * structure is the same, i.e. you normally raise and exception by
+ * @code
+ * if (!(cond))
+ * throw ExcSomething();
+ * @endcode
+ * and catch it using the statement
+ * @code
+ * try {
+ * do_something ();
+ * }
+ * catch (exception &e) {
+ * std::cerr << "Exception occured:" << std::endl
+ * << e.what ()
+ * << std::endl;
+ * do_something_to_reciver ();
+ * };
+ * @endcode
+ * <tt>exception</tt> is a standard <tt>C++</tt> class providing basic functionality for
+ * exceptions, such as the virtual function <tt>what()</tt> which returns some
+ * information on the exception itself. This information is useful if an
+ * exception can't be handled properly, in which case as precise a description
+ * as possible should be printed.
+ *
+ * The problem here is that to get significant and useful information out
+ * of <tt>what()</tt>, it is necessary to overload this function in out exception
+ * class and call the <tt>throw</tt> operator with additional arguments to the
+ * exception class. The first thing, overloading the <tt>what</tt> function is
+ * done using the <tt>DeclExceptionN</tt> macros, but putting the right information,
+ * which is the same as explained above for the <tt>Assert</tt> expansion, requires
+ * some work if one would want to write it down each time:
+ * @code
+ * if (!(cond))
+ * {
+ * ExcSomething e(additional information);
+ * e.set_fields (__FILE__, __LINE__, __PRETTY_FUNCTION__,
+ * "condition as a string",
+ * "name of condition as a string");
+ * throw e;
+ * };
+ * @endcode
+ *
+ * For this purpose, the macro <tt>AssertThrow</tt> was invented. It does
+ * mainly the same job as does the <tt>Assert</tt> macro, but it does not
+ * kill the program, it rather throws an exception as shown above. The mode
+ * of usage is
+ * @code
+ * AssertThrow (cond, ExcSomething(additional information));
+ * @endcode
+ *
+ * The condition to be checked is incorporated into the macro in order to
+ * allow passing the violated condition as a string. The expansion of the
+ * <tt>AssertThrow</tt> macro is not affected by the <tt>DEBUG</tt>
+ * preprocessor variable.
+ *
+ *
+ * <h3>Description of the DeclExceptionN macro family</h3>
+ *
+ * Declare an exception class without any additional parameters.
+ * There is a whole family of <tt>DeclException?</tt> macros
+ * where <tt>?</tt> is to be replaced by the number of additional
+ * parameters (0 to 5 presently).
+ *
+ * The syntax is as follows:
+ * @code
+ * DeclException2 (ExcDomain,
+ * int,
+ * int,
+ * << " i=" << arg1 << ", m=" << arg2);
+ * @endcode
+ * The first is the name of the exception class to be created.
+ * The next arguments are the types of the parameters (in this
+ * case there are two type names needed) and finally the output
+ * sequence with which you can print additional information.
+ *
+ * The syntax of the output sequence is a bit weird but gets
+ * clear once you see how this macro is defined:
+ * @code
+ * class name : public ExceptionBase {
+ * public:
+ * name (const type1 a1, const type2 a2) :
+ * arg1 (a1), arg2(a2) {};
+ * virtual void print_info (std::ostream &out) const {
+ * out outsequence << std::endl;
+ * };
+ * private:
+ * type1 arg1;
+ * type2 arg2;
+ * };
+ * @endcode
*
+ * If declared as specified, you can later use this exception class
+ * in the following manner:
+ * @code
+ * int i=5;
+ * int m=3;
+ * Assert (i<m, MyExc2(i,m));
+ * @endcode
+ * and the output if the condition fails will be
+ * @verbatim
+ * --------------------------------------------------------
+ * An error occurred in line <301> of file <exc-test.cc>.
+ * The violated condition was:
+ * i<m
+ * The name and call sequence of the exception was:
+ * MyExc2(i,m)
+ * Additional Information:
+ * i=5, m=3
+ * --------------------------------------------------------
+ * @endverbatim
+ *
+ * Obviously for the <tt>DeclException0(name)</tt> macro, no types and
+ * also no output sequence is allowed.
+ *
* @author Wolfgang Bangerth, 1998-2006
*/