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

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