[thirdparty/gcc.git] / libstdc++-v3 / docs / html / 19_diagnostics / howto.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
   <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19.">
   <meta name="GENERATOR" content="vi and eight fingers">
   <title>libstdc++-v3 HOWTO:  Chapter 19</title>
<link rel="StyleSheet" href="../lib3styles.css">
</head>
<body>

<h1 class="centered"><a name="top">Chapter 19:  Diagnostics</a></h1>

<p>Chapter 19 deals with program diagnostics, such as exceptions
   and assertions.  You know, all the things we wish weren't even
   necessary at all.
</p>


<!-- ####################################################### -->
<hr>
<h1>Contents</h1>
<ul>
   <li><a href="#1">Adding data to exceptions</a>
   <li><a href="#2">Exception class hierarchy diagram</a>
   <li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a>
   <li><a href="#4">Verbose <code>terminate</code></a>
</ul>

<hr>

<!-- ####################################################### -->

<h2><a name="1">Adding data to exceptions</a></h2>
   <p>The standard exception classes carry with them a single string as
      data (usually describing what went wrong or where the 'throw' took
      place).  It's good to remember that you can add your own data to
      these exceptions when extending the hierarchy:
   </p>
   <pre>
   struct My_Exception : public std::runtime_error
   {
     public:
       My_Exception (const string&amp; whatarg)
           : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
       int  errno_at_time_of_throw() const { return e; }
       DBID id_of_thing_that_threw() const { return id; }
     protected:
       int    e;
       DBID   id;     // some user-defined type
   };
   </pre>
   <p>Return <a href="#top">to top of page</a> or
      <a href="../faq/index.html">to the FAQ</a>.
   </p>

<hr>
<h2><a name="2">Exception class hierarchy diagram</a></h2>
   <p>At one point we were going to make up a PDF of the exceptions
      hierarchy, akin to the one done for the I/O class hierarchy.
      Time was our enemy.  Since then we've moved to Doxygen, which has
      the useful property of not sucking.  Specifically, when the source
      code is changed, the diagrams are automatically brought up to date.
      For the old way, we had to update the diagrams separately.
   </p>
   <p>There are several links to the Doxygen-generated pages from
      <a href="../documentation.html">here</a>.
   </p>
   <p>Return <a href="#top">to top of page</a> or
      <a href="../faq/index.html">to the FAQ</a>.
   </p>

<hr>
<h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2>
   <p>Better taste!  Less fat!  Literally!</p>
   <p>In 1999, SGI added <em>concept checkers</em> to their implementation
      of the STL:  code which checked the template parameters of
      instantiated pieces of the STL, in order to insure that the parameters
      being used met the requirements of the standard.  For example,
      the Standard requires that types passed as template parameters to
      <code>vector</code> be &quot;Assignable&quot; (which means what you think
      it means).  The checking was done during compilation, and none of
      the code was executed at runtime.
   </p>
   <p>Unfortunately, the size of the compiler files grew significantly
      as a result.  The checking code itself was cumbersome.  And bugs
      were found in it on more than one occasion.
   </p>
   <p>The primary author of the checking code, Jeremy Siek, had already
      started work on a replcement implementation.  The new code has been
      formally reviewed and accepted into
      <a href="http://www.boost.org/libs/concept_check/concept_check.htm">the
      Boost libraries</a>, and we are pleased to incorporate it into the
      GNU C++ library.
   </p>
   <p>The new version imposes a much smaller space overhead on the generated
      object file.  The checks are also cleaner and easier to read and
      understand.
   </p>
   <p>For GCC 3.0 and 3.1 they are off by default.  They can be enabled at
      configure time with
      <a href="../configopts.html"><code>--enable-concept-checks</code></a>.
   </p>
   <p>Return <a href="#top">to top of page</a> or
      <a href="../faq/index.html">to the FAQ</a>.
   </p>

<hr>
<h2><a name="4">Verbose <code>terminate</code></a></h2>
   <p>If you are having difficulty with uncaught exceptions and want a
      little bit of help debugging the causes of the core dumps, you can
      make use of a GNU extension in GCC 3.1 and later:
      <pre>
   #include &lt;exception&gt;

   int main()
   {
       std::set_terminate (__gnu_cxx::verbose_terminate_handler);
       ...
       throw <em>anything</em>;
   }</pre>
   </p>
   <p>The <code> verbose_terminate_handler </code> function obtains the name
      of the current exception, attempts to demangle it, and prints it to
      stderr.  If the exception is derived from <code> std::exception </code>
      then the output from <code>what()</code> will be included.
   </p>
   <p>Any replacement termination function is required to kill the program
      without returning; this one calls abort.
   </p>
   <p>For example:
      <pre>
   #include &lt;exception&gt;
   #include &lt;stdexcept&gt;

   struct BLARGH : std::runtime_error
   {
       BLARGH (const string&amp; whatarg)
           : std::runtime_error(whatarg) { }
   };

   int main (int argc)
   {
       std::set_terminate (__gnu_cxx::verbose_terminate_handler);
       if (argc &gt; 5)
           throw BLARGH(&quot;argc is greater than 5!&quot;);
       else
           throw argc;
   }</pre>
   </p>
   <p>In GCC 3.1 and later, this gives
      <pre>
   % ./a.out
   terminate called after throwing a `int'
   Aborted
   % ./a.out f f f f f f f f f f f
   terminate called after throwing a `BLARGH'
   what(): argc is greater than 5!
   Aborted
   %</pre>
      The 'Aborted' line comes from the call to abort(), of course.
   </p>
   <p>Return <a href="#top">to top of page</a> or
      <a href="../faq/index.html">to the FAQ</a>.
   </p>


<!-- ####################################################### -->

<hr>
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>


</body>
</html>
Commit	Line	Data
b2dad0e3	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
5d5e5e4e PE	2	<html>
5d5e5e4e PE	3	<head>
0435269a PE	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">
5d5e5e4e	9	<title>libstdc++-v3 HOWTO: Chapter 19</title>
94e091c8	10	<link rel="StyleSheet" href="../lib3styles.css">
5d5e5e4e PE	11	</head>
5d5e5e4e PE	12	<body>
b2dad0e3	13
0435269a	14	<h1 class="centered"><a name="top">Chapter 19: Diagnostics</a></h1>
b2dad0e3	15
5d5e5e4e	16	<p>Chapter 19 deals with program diagnostics, such as exceptions
dd1ee41e PE	17	and assertions. You know, all the things we wish weren't even
dd1ee41e PE	18	necessary at all.
5d5e5e4e	19	</p>
b2dad0e3 BK	20
	21
	22	<!-- ####################################################### -->
5d5e5e4e PE	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>
1b4a6975	29	<li><a href="#4">Verbose <code>terminate</code></a>
5d5e5e4e	30	</ul>
b2dad0e3	31
5d5e5e4e	32	<hr>
b2dad0e3 BK	33
	34	<!-- ####################################################### -->
	35
5d5e5e4e PE	36	<h2><a name="1">Adding data to exceptions</a></h2>
5d5e5e4e PE	37	<p>The standard exception classes carry with them a single string as
b2dad0e3 BK	38	data (usually describing what went wrong or where the 'throw' took
b2dad0e3 BK	39	place). It's good to remember that you can add your own data to
c5504edb	40	these exceptions when extending the hierarchy:
5d5e5e4e	41	</p>
0435269a PE	42	<pre>
0435269a PE	43	struct My_Exception : public std::runtime_error
b2dad0e3 BK	44	{
b2dad0e3 BK	45	public:
537286a2	46	My_Exception (const string& whatarg)
0435269a	47	: std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
b2dad0e3 BK	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	};
0435269a	54	</pre>
5d5e5e4e PE	55	<p>Return <a href="#top">to top of page</a> or
	56	<a href="../faq/index.html">to the FAQ</a>.
	57	</p>
b2dad0e3	58
5d5e5e4e PE	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
0da1b7b5 PE	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.
5d5e5e4e PE	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>
b2dad0e3	74
5d5e5e4e PE	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
30a20a1e PE	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
5d5e5e4e	83	<code>vector</code> be "Assignable" (which means what you think
30a20a1e PE	84	it means). The checking was done during compilation, and none of
30a20a1e PE	85	the code was executed at runtime.
5d5e5e4e PE	86	</p>
5d5e5e4e PE	87	<p>Unfortunately, the size of the compiler files grew significantly
30a20a1e PE	88	as a result. The checking code itself was cumbersome. And bugs
30a20a1e PE	89	were found in it on more than one occasion.
5d5e5e4e PE	90	</p>
5d5e5e4e PE	91	<p>The primary author of the checking code, Jeremy Siek, had already
30a20a1e PE	92	started work on a replcement implementation. The new code has been
30a20a1e PE	93	formally reviewed and accepted into
5d5e5e4e PE	94	<a href="http://www.boost.org/libs/concept_check/concept_check.htm">the
5d5e5e4e PE	95	Boost libraries</a>, and we are pleased to incorporate it into the
30a20a1e	96	GNU C++ library.
5d5e5e4e PE	97	</p>
5d5e5e4e PE	98	<p>The new version imposes a much smaller space overhead on the generated
30a20a1e PE	99	object file. The checks are also cleaner and easier to read and
30a20a1e PE	100	understand.
5d5e5e4e	101	</p>
ffe94f83 PE	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>.
5d5e5e4e	105	</p>
1b4a6975 PE	106	<p>Return <a href="#top">to top of page</a> or
	107	<a href="../faq/index.html">to the FAQ</a>.
	108	</p>
	109
	110	<hr>
	111	<h2><a name="4">Verbose <code>terminate</code></a></h2>
	112	<p>If you are having difficulty with uncaught exceptions and want a
	113	little bit of help debugging the causes of the core dumps, you can
	114	make use of a GNU extension in GCC 3.1 and later:
	115	<pre>
	116	#include <exception>
	117
	118	int main()
	119	{
	120	std::set_terminate (__gnu_cxx::verbose_terminate_handler);
	121	...
	122	throw <em>anything</em>;
	123	}</pre>
	124	</p>
	125	<p>The <code> verbose_terminate_handler </code> function obtains the name
	126	of the current exception, attempts to demangle it, and prints it to
	127	stderr. If the exception is derived from <code> std::exception </code>
	128	then the output from <code>what()</code> will be included.
	129	</p>
	130	<p>Any replacement termination function is required to kill the program
	131	without returning; this one calls abort.
	132	</p>
	133	<p>For example:
	134	<pre>
	135	#include <exception>
	136	#include <stdexcept>
	137
	138	struct BLARGH : std::runtime_error
	139	{
	140	BLARGH (const string& whatarg)
	141	: std::runtime_error(whatarg) { }
	142	};
30a20a1e	143
1b4a6975 PE	144	int main (int argc)
	145	{
	146	std::set_terminate (__gnu_cxx::verbose_terminate_handler);
	147	if (argc > 5)
	148	throw BLARGH("argc is greater than 5!");
	149	else
	150	throw argc;
	151	}</pre>
	152	</p>
	153	<p>In GCC 3.1 and later, this gives
	154	<pre>
	155	% ./a.out
	156	terminate called after throwing a `int'
	157	Aborted
	158	% ./a.out f f f f f f f f f f f
	159	terminate called after throwing a `BLARGH'
	160	what(): argc is greater than 5!
	161	Aborted
	162	%</pre>
	163	The 'Aborted' line comes from the call to abort(), of course.
	164	</p>
5d5e5e4e PE	165	<p>Return <a href="#top">to top of page</a> or
	166	<a href="../faq/index.html">to the FAQ</a>.
	167	</p>
dd1ee41e PE	168
dd1ee41e PE	169
b2dad0e3 BK	170	<!-- ####################################################### -->
b2dad0e3 BK	171
5d5e5e4e	172	<hr>
0435269a	173	<p class="fineprint"><em>
c9fe10db	174	See <a href="../17_intro/license.html">license.html</a> for copying conditions.
b2dad0e3	175	Comments and suggestions are welcome, and may be sent to
0435269a	176	<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
5d5e5e4e	177	</em></p>
b2dad0e3 BK	178
b2dad0e3 BK	179
5d5e5e4e PE	180	</body>
5d5e5e4e PE	181	</html>