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

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