]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Update the exception module.
authorDavid Wells <wellsd2@rpi.edu>
Sun, 8 Apr 2018 22:15:51 +0000 (18:15 -0400)
committerDavid Wells <wellsd2@rpi.edu>
Mon, 9 Apr 2018 12:27:39 +0000 (08:27 -0400)
This module referenced a few since-removed functions.

doc/doxygen/headers/exceptions.h

index d8d9cb98729f528f733b5a2873ca2b1613de0bdb..eb356ba30cba24d01d630005da1193f1b3c9d291 100644 (file)
@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------
 //
-// Copyright (C) 2003 - 2013 by the deal.II authors
+// Copyright (C) 2003 - 2018 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
  * 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
  *   mode, not in release (or optimized, production) mode. In deal.II, static
  *   assertions are typically used to check that parameters to functions satisfy
  *     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
  *  @code
  *    #ifdef DEBUG
  *        if (!(cond))
- *              issue error of class ExcDomain(n,dim)
+ *          {
+ *            // issue error of class ExcDomain(n,dim)
+ *          }
  *    #else
  *        // do nothing
  *    #endif
  *  following sequence:
  *  @code
  *    if (!(cond))
- *      deal_II_exceptions::internals::issue_error_assert_1
+ *      deal_II_exceptions::internals::issue_error_noreturn
  *             (__FILE__,
  *              __LINE__,
  *              __PRETTY_FUNCTION__,
  *              #cond,
  *              #exc,
- *              &exc);
+ *              exc);
  *  @endcode
- *  
+ *
  *  (Note that function names and exact calling sequences may change
  *  over time, but the general principle remains the same.) I.e., if
  *  the given condition is violated, then the file and line in which
  *  the exception occurred as well as the condition itself and the call
  *  sequence of the exception object is passed to the
- *  deal_II_exceptions::internals::issue_error_assert_1()
+ *  deal_II_exceptions::internals::issue_error_noreturn()
  *  function. 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 this function.
  *
- *  <tt>__PRETTY__FUNCTION__</tt> is a macro defined by some compilers and
+ *  <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>issue_error_assert</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. Several of the
- *  @ref Tutorial programs show a typical output.
- *
- *  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>.
+ *  In <tt>issue_error_noreturn</tt>, the given data is transferred into the
+ *  <tt>exc</tt> object by calling the set_fields() function; Afterwards the
+ *  program is either aborted (and information about the exception is printed
+ *  to deallog) or the exception is thrown. The <tt>Assert</tt> macro does the
+ *  first path (print and abort); <tt>AssertThrow</tt> does the second
+ *  (throw). This behavior is consistent with the descriptions of static and
+ *  dynamic assertions earlier in this document. If it can be obtained from
+ *  the operating system, the output may also contain a stacktrace to show
+ *  where the error happened. Several of the @ref Tutorial programs show a
+ *  typical output.
+ *
+ *  If the preprocessor variable <tt>DEBUG</tt> is not set then 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,
  *  @endcode
  *  and catch it using the statement
  *  @code
- *    try {
- *      do_something ();
- *    }
- *    catch (std::exception &e) {
- *      std::cerr << "Exception occurred:" << std::endl
- *           << e.what ()
- *           << std::endl;
- *      do_something_to_reciver ();
- *    };
+ *    try
+ *      {
+ *        do_something ();
+ *      }
+ *    catch (std::exception &e)
+ *      {
+ *        std::cerr << "Exception occurred:" << std::endl
+ *                  << e.what ()
+ *                  << std::endl;
+ *        do_something_to_receiver ();
+ *      }
  *  @endcode
  *  <tt>std::exception</tt> is a standard <tt>C++</tt> class providing basic functionality for
  *  exceptions, such as the virtual function <tt>what()</tt> that returns some
  *  case there two types, corresponding to the <tt>X</tt> in
  *  <tt>DeclExceptionX</tt>) and finally the output
  *  sequence with which you can print additional information.
- *  
+ *
  *  The syntax of the output sequence is a bit weird but gets
  *  clearer once you see how this macro is defined (again schematically, actual
  *  function names and definitions may change over time and be different):
  *  @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;
+ *  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
  *  @code
  *    --------------------------------------------------------
  *    An error occurred in line <301> of file <exc-test.cc>.
- *    The violated condition was: 
+ *    The violated condition was:
  *      i<m
  *    The name and call sequence of the exception was:
  *      MyExc2(i,m)
- *    Additional Information: 
+ *    Additional Information:
  *      i=5, m=3
  *    --------------------------------------------------------
  *  @endcode
- *  
+ *
  *  Obviously for the <tt>DeclException0(name)</tt> macro, no types and
  *  also no output sequence is allowed.
  *

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.