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