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

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