libstdc++-v3/docs/html/19_diagnostics/howto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   6    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
   7    <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19.">
   8    <meta name="GENERATOR" content="vi and eight fingers">
   9    <title>libstdc++-v3 HOWTO:  Chapter 19</title>
  10 <link rel="StyleSheet" href="../lib3styles.css">
  11 </head>
  12 <body>
  13
  14 <h1 class="centered"><a name="top">Chapter 19:  Diagnostics</a></h1>
  15
  16 <p>Chapter 19 deals with program diagnostics, such as exceptions
  17    and assertions.  You know, all the things we wish weren't even
  18    necessary at all.
  19 </p>
  20
  21
  22 <!-- ####################################################### -->
  23 <hr>
  24 <h1>Contents</h1>
  25 <ul>
  26    <li><a href="#1">Adding data to exceptions</a>
  27    <li><a href="#2">Exception class hierarchy diagram</a>
  28    <li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a>
  29    <li><a href="#4">Verbose <code>terminate</code></a>
  30 </ul>
  31
  32 <hr>
  33
  34 <!-- ####################################################### -->
  35
  36 <h2><a name="1">Adding data to exceptions</a></h2>
  37    <p>The standard exception classes carry with them a single string as
  38       data (usually describing what went wrong or where the 'throw' took
  39       place).  It's good to remember that you can add your own data to
  40       these exceptions when extending the hierarchy:
  41    </p>
  42    <pre>
  43    struct My_Exception : public std::runtime_error
  44    {
  45      public:
  46        My_Exception (const string&amp; whatarg)
  47            : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
  48        int  errno_at_time_of_throw() const { return e; }
  49        DBID id_of_thing_that_threw() const { return id; }
  50      protected:
  51        int    e;
  52        DBID   id;     // some user-defined type
  53    };
  54    </pre>
  55    <p>Return <a href="#top">to top of page</a> or
  56       <a href="../faq/index.html">to the FAQ</a>.
  57    </p>
  58
  59 <hr>
  60 <h2><a name="2">Exception class hierarchy diagram</a></h2>
  61    <p>At one point we were going to make up a PDF of the exceptions
  62       hierarchy, akin to the one done for the I/O class hierarchy.
  63       Time was our enemy.  Since then we've moved to Doxygen, which has
  64       the useful property of not sucking.  Specifically, when the source
  65       code is changed, the diagrams are automatically brought up to date.
  66       For the old way, we had to update the diagrams separately.
  67    </p>
  68    <p>There are several links to the Doxygen-generated pages from
  69       <a href="../documentation.html">here</a>.
  70    </p>
  71    <p>Return <a href="#top">to top of page</a> or
  72       <a href="../faq/index.html">to the FAQ</a>.
  73    </p>
  74
  75 <hr>
  76 <h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2>
  77    <p>Better taste!  Less fat!  Literally!</p>
  78    <p>In 1999, SGI added <em>concept checkers</em> to their implementation
  79       of the STL:  code which checked the template parameters of
  80       instantiated pieces of the STL, in order to insure that the parameters
  81       being used met the requirements of the standard.  For example,
  82       the Standard requires that types passed as template parameters to
  83       <code>vector</code> be &quot;Assignable&quot; (which means what you think
  84       it means).  The checking was done during compilation, and none of
  85       the code was executed at runtime.
  86    </p>
  87    <p>Unfortunately, the size of the compiler files grew significantly
  88       as a result.  The checking code itself was cumbersome.  And bugs
  89       were found in it on more than one occasion.
  90    </p>
  91    <p>The primary author of the checking code, Jeremy Siek, had already
  92       started work on a replcement implementation.  The new code has been
  93       formally reviewed and accepted into
  94       <a href="http://www.boost.org/libs/concept_check/concept_check.htm">the
  95       Boost libraries</a>, and we are pleased to incorporate it into the
  96       GNU C++ library.
  97    </p>
  98    <p>The new version imposes a much smaller space overhead on the generated
  99       object file.  The checks are also cleaner and easier to read and
 100       understand.
 101    </p>
 102    <p>For GCC 3.0 and 3.1 they are off by default.  They can be enabled at
 103       configure time with
 104       <a href="../configopts.html"><code>--enable-concept-checks</code></a>.
 105       For 3.1 you can instead #define _GLIBCPP_CONCEPT_CHECKS to enable them
 106       on a per-translation-unit basis.
 107    </p>
 108    <p>Return <a href="#top">to top of page</a> or
 109       <a href="../faq/index.html">to the FAQ</a>.
 110    </p>
 111
 112 <hr>
 113 <h2><a name="4">Verbose <code>terminate</code></a></h2>
 114    <p>If you are having difficulty with uncaught exceptions and want a
 115       little bit of help debugging the causes of the core dumps, you can
 116       make use of a GNU extension in GCC 3.1 and later:
 117       <pre>
 118    #include &lt;exception&gt;
 119
 120    int main()
 121    {
 122        std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
 123        ...
 124        throw <em>anything</em>;
 125    }</pre>
 126    </p>
 127    <p>The <code> __verbose_terminate_handler </code> function obtains the name
 128       of the current exception, attempts to demangle it, and prints it to
 129       stderr.  If the exception is derived from <code> std::exception </code>
 130       then the output from <code>what()</code> will be included.
 131    </p>
 132    <p>Any replacement termination function is required to kill the program
 133       without returning; this one calls abort.
 134    </p>
 135    <p>For example:
 136       <pre>
 137    #include &lt;exception&gt;
 138    #include &lt;stdexcept&gt;
 139
 140    struct BLARGH : std::runtime_error
 141    {
 142        BLARGH (const string&amp; whatarg)
 143            : std::runtime_error(whatarg) { }
 144    };
 145
 146    int main (int argc)
 147    {
 148        std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
 149        if (argc &gt; 5)
 150            throw BLARGH(&quot;argc is greater than 5!&quot;);
 151        else
 152            throw argc;
 153    }</pre>
 154    </p>
 155    <p>In GCC 3.1 and later, this gives
 156       <pre>
 157    % ./a.out
 158    terminate called after throwing a `int'
 159    Aborted
 160    % ./a.out f f f f f f f f f f f
 161    terminate called after throwing a `BLARGH'
 162    what(): argc is greater than 5!
 163    Aborted
 164    %</pre>
 165       The 'Aborted' line comes from the call to abort(), of course.
 166    </p>
 167    <p>Return <a href="#top">to top of page</a> or
 168       <a href="../faq/index.html">to the FAQ</a>.
 169    </p>
 170
 171
 172 <!-- ####################################################### -->
 173
 174 <hr>
 175 <p class="fineprint"><em>
 176 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 177 Comments and suggestions are welcome, and may be sent to
 178 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 179 </em></p>
 180
 181
 182 </body>
 183 </html>