libstdc++-v3/doc/xml/manual/diagnostics.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <chapter id="std.diagnostics" xreflabel="Diagnostics">
   7 <?dbhtml filename="diagnostics.html"?>
   8
   9 <chapterinfo>
  10   <keywordset>
  11     <keyword>
  12       ISO C++
  13     </keyword>
  14     <keyword>
  15       library
  16     </keyword>
  17   </keywordset>
  18 </chapterinfo>
  19
  20 <title>
  21   Diagnostics
  22   <indexterm><primary>Diagnostics</primary></indexterm>
  23 </title>
  24
  25 <sect1 id="std.diagnostics.exceptions" xreflabel="Exceptions">
  26   <?dbhtml filename="exceptions.html"?>
  27   <title>Exceptions</title>
  28
  29   <sect2 id="std.diagnostics.exceptions.api">
  30     <title>API Reference</title>
  31     <para>
  32       All exception objects are defined in one of the standard header
  33       files: <filename>exception</filename>,
  34       <filename>stdexcept</filename>, <filename>new</filename>, and
  35       <filename>typeinfo</filename>.
  36     </para>
  37
  38     <para>
  39       The base exception object is <classname>exception</classname>,
  40       located in <filename>exception</filename>. This object has no
  41       <classname>string</classname> member.
  42     </para>
  43
  44     <para>
  45       Derived from this are several classes that may have a
  46       <classname>string</classname> member: a full hierarchy can be
  47       found in the source documentation.
  48     </para>
  49
  50     <para>
  51       Full API details.
  52     </para>
  53
  54     <!-- Doxygen XML: api/group__exceptions.xml -->
  55
  56   </sect2>
  57   <sect2 id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions">
  58     <title>Adding Data to <classname>exception</classname></title>
  59     <para>
  60       The standard exception classes carry with them a single string as
  61       data (usually describing what went wrong or where the 'throw' took
  62     place).  It's good to remember that you can add your own data to
  63     these exceptions when extending the hierarchy:
  64    </para>
  65    <programlisting>
  66    struct My_Exception : public std::runtime_error
  67    {
  68      public:
  69        My_Exception (const string&amp; whatarg)
  70            : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
  71        int  errno_at_time_of_throw() const { return e; }
  72        DBID id_of_thing_that_threw() const { return id; }
  73      protected:
  74        int    e;
  75        DBID   id;     // some user-defined type
  76    };
  77    </programlisting>
  78
  79   </sect2>
  80 </sect1>
  81
  82 <sect1 id="std.diagnostics.concept_checking" xreflabel="Concept Checking">
  83   <title>Concept Checking</title>
  84   <para>
  85     In 1999, SGI added <quote>concept checkers</quote> to their
  86     implementation of the STL: code which checked the template
  87     parameters of instantiated pieces of the STL, in order to insure
  88     that the parameters being used met the requirements of the
  89     standard.  For example, the Standard requires that types passed as
  90     template parameters to <classname>vector</classname> be
  91     &quot;Assignable&quot; (which means what you think it means).  The
  92     checking was done during compilation, and none of the code was
  93     executed at runtime.
  94    </para>
  95    <para>
  96      Unfortunately, the size of the compiler files grew significantly
  97      as a result.  The checking code itself was cumbersome.  And bugs
  98      were found in it on more than one occasion.
  99    </para>
 100    <para>
 101      The primary author of the checking code, Jeremy Siek, had already
 102      started work on a replacement implementation.  The new code has been
 103      formally reviewed and accepted into
 104    <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the
 105    Boost libraries</ulink>, and we are pleased to incorporate it into the
 106    GNU C++ library.
 107  </para>
 108  <para>
 109    The new version imposes a much smaller space overhead on the generated
 110    object file.  The checks are also cleaner and easier to read and
 111    understand.
 112  </para>
 113
 114  <para>
 115    They are off by default for all versions of GCC.
 116    They can be enabled at configure time with
 117    <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
 118    You can enable them on a per-translation-unit basis with
 119      <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>.
 120  </para>
 121
 122  <para>
 123    Please note that the upcoming C++ standard has first-class
 124    support for template parameter constraints based on concepts in the core
 125    language. This will obviate the need for the library-simulated concept
 126    checking described above.
 127  </para>
 128
 129 </sect1>
 130
 131 </chapter>