diff options
Diffstat (limited to 'libstdc++-v3/docs/html/19_diagnostics/howto.html')
| -rw-r--r-- | libstdc++-v3/docs/html/19_diagnostics/howto.html | 231 |
1 files changed, 152 insertions, 79 deletions
diff --git a/libstdc++-v3/docs/html/19_diagnostics/howto.html b/libstdc++-v3/docs/html/19_diagnostics/howto.html index 7bfbcdf9bb4..e85d57d3d34 100644 --- a/libstdc++-v3/docs/html/19_diagnostics/howto.html +++ b/libstdc++-v3/docs/html/19_diagnostics/howto.html @@ -1,107 +1,180 @@ <!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@sources.redhat.com (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"> -<!-- $Id: howto.html,v 1.5 2000/12/03 23:47:47 jsm28 Exp $ --> -</HEAD> -<BODY> - -<H1 CLASS="centered"><A NAME="top">Chapter 19: Diagnostics</A></H1> - -<P>Chapter 19 deals with program diagnostics, such as exceptions +<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> +</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</A> -</UL> +<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> +<hr> <!-- ####################################################### --> -<H2><A NAME="1">Adding data to exceptions</A></H2> - <P>The standard exception classes carry with them a single string as +<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 heirarchy: - </P> - <PRE> - using std::runtime_error; - struct My_Exception : public runtime_error + these exceptions when extending the hierarchy: + </p> + <pre> + struct My_Exception : public std::runtime_error { public: - My_Exception (const string& whatarg) - : runtime_error(whatarg), e(errno), id(GetDataBaseID()) { } + My_Exception (const string& 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>The <A HREF="exceptions_hiearchy.pdf">diagram</A> is in PDF, or - at least it will be once it gets finished. - </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</A></H2> - <P>As part of their 3.3 release, SGI added some nifty macros which - perform assertions on type properties. For example, the Standard - requires that types passed as template parameters to <TT>vector</TT> - be "Assignable" (which means what you think it means). - </P> - <P>The concept checkers allow the source code for <TT>vector</TT> to - declare - <PRE> - __STL_CLASS_REQUIRES(_Tp, _Assignable); - </PRE>inside the template. <TT>_Tp</TT> is the element type of the - vector, and <TT>_Assignable</TT> is the concept to be checked (it is - defined in some back-end header files). When you instantiate - <TT>vector<MyType></TT>, compile-time checking can be done on - whether MyType meets the requirements for vectors. - </P> -<P>This is an extension to the library. This documentation needs updating.</P> - <P>Return <A HREF="#top">to top of page</A> or - <A HREF="../faq/index.html">to the FAQ</A>. - </P> - - + </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 "Assignable" (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>Right now they are off by default. More will be added once + GCC 3.0 is released and we have time to revisit this topic. + </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 <exception> + + 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 <exception> + #include <stdexcept> + + struct BLARGH : std::runtime_error + { + BLARGH (const string& whatarg) + : std::runtime_error(whatarg) { } + }; + int main (int argc) + { + std::set_terminate (__gnu_cxx::verbose_terminate_handler); + if (argc > 5) + throw BLARGH("argc is greater than 5!"); + 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> +<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:pme@sources.redhat.com">Phil Edwards</A> or -<A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>. -<BR> $Id: howto.html,v 1.5 2000/12/03 23:47:47 jsm28 Exp $ -</EM></P> +<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. +</em></p> -</BODY> -</HTML> +</body> +</html> |