libstdc++-v3/docs/html/18_support/howto.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
  10    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
  11    <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18." />
  12    <meta name="GENERATOR" content="vi and eight fingers" />
  13    <title>libstdc++-v3 HOWTO:  Chapter 18: Library Support</title>
  14 <link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
  15 <link rel="Start" href="../documentation.html" type="text/html"
  16   title="GNU C++ Standard Library" />
  17 <link rel="Prev" href="../17_intro/howto.html" type="text/html"
  18   title="Library Introduction" />
  19 <link rel="Next" href="../19_diagnostics/howto.html" type="text/html"
  20   title="Diagnostics" />
  21 <link rel="Copyright" href="../17_intro/license.html" type="text/html" />
  22 <link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
  23 </head>
  24 <body>
  25
  26 <h1 class="centered"><a name="top">Chapter 18:  Library Support</a></h1>
  27
  28 <p>Chapter 18 deals with the functions called and objects created
  29    automatically during the course of a program's existence.
  30 </p>
  31 <p>While we can't reproduce the contents of the Standard here (you need to
  32    get your own copy from your nation's member body; see our homepage for
  33    help), we can mention a couple of changes in what kind of support a C++
  34    program gets from the Standard Library.
  35 </p>
  36
  37
  38 <!-- ####################################################### -->
  39 <hr />
  40 <h1>Contents</h1>
  41 <ul>
  42    <li><a href="#1">Types</a></li>
  43    <li><a href="#2">Implementation properties</a></li>
  44    <li><a href="#3">Start and Termination</a></li>
  45    <li><a href="#4">Dynamic memory management</a></li>
  46    <li><a href="#5">RTTI, the ABI, and demangling</a></li>
  47 </ul>
  48
  49 <hr />
  50
  51 <!-- ####################################################### -->
  52
  53 <h2><a name="1">Types</a></h2>
  54    <p>All the types that you're used to in C are here in one form or
  55       another.  The only change that might affect people is the type of
  56       NULL:  while it is required to be a macro, the definition of that
  57       macro is <em>not</em> allowed to be <code>(void*)0</code>, which is
  58       often used in C.
  59    </p>
  60    <p>In g++, NULL is #define'd to be <code>__null</code>, a magic keyword
  61       extension of g++.
  62    </p>
  63    <p>The biggest problem of #defining NULL to be something like
  64       &quot;0L&quot; is that the compiler will view that as a long integer
  65       before it views it as a pointer, so overloading won't do what you
  66       expect.  (This is why g++ has a magic extension, so that NULL is
  67       always a pointer.)
  68    </p>
  69    <p>In his book
  70       <a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&amp;ptype=0"><em>Effective C++</em></a>,
  71       Scott Meyers points out that the best way to solve this problem is to
  72       not overload on pointer-vs-integer types to begin with.  He also
  73       offers a way to make your own magic NULL that will match pointers
  74       before it matches integers:
  75    </p>
  76    <pre>
  77    const                             // this is a const object...
  78    class {
  79    public:
  80      template&lt;class T&gt;               // convertible to any type
  81        operator T*() const           // of null non-member
  82        { return 0; }                 // pointer...
  83
  84      template&lt;class C, class T&gt;      // or any type of null
  85        operator T C::*() const       // member pointer...
  86        { return 0; }
  87
  88    private:
  89      void operator&amp;() const;         // whose address can't be
  90                                      // taken (see Item 27)...
  91
  92    } NULL;                           // and whose name is NULL
  93    </pre>
  94    <p>(Cribbed from the published version of
  95       <a href="http://www.awlonline.com/cseng/meyerscddemo/">the
  96       Effective C++ CD</a>, reproduced here with permission.)
  97    </p>
  98    <p>If you aren't using g++ (why?), but you do have a compiler which
  99       supports member function templates, then you can use this definition
 100       of NULL (be sure to #undef any existing versions).  It only helps if
 101       you actually use NULL in function calls, though; if you make a call of
 102       <code>foo(0);</code> instead of <code>foo(NULL);</code>, then you're back
 103       where you started.
 104    </p>
 105    <p><strong>Added Note:</strong>  When we contacted Dr. Meyers to ask
 106       permission to
 107       print this stuff, it prompted him to run this code through current
 108       compilers to see what the state of the art is with respect to member
 109       template functions.  He posted
 110       <a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&amp;CONTEXT=964036823.871301239">an
 111       article to Usenet</a> after discovering that the code above is not
 112       valid!  Even though it has no data members, it still needs a
 113       user-defined constructor (which means that the class needs a type name
 114       after all).  The ctor can have an empty body; it just needs to be
 115       there.  (Stupid requirement?  We think so too, and this will probably
 116       be changed in the language itself.)
 117    </p>
 118    <p>Return <a href="#top">to top of page</a> or
 119       <a href="../faq/index.html">to the FAQ</a>.
 120    </p>
 121
 122 <hr />
 123 <h2><a name="2">Implementation properties</a></h2>
 124    <h3><code>&lt;limits&gt;</code></h3>
 125    <p>This header mainly defines traits classes to give access to various
 126    implementation defined-aspects of the fundamental types.  The
 127    traits classes -- fourteen in total -- are all specilizations of the
 128    template class <code>numeric_limits</code>, documented
 129    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html">here</a>
 130    and defined as follows:
 131    </p>
 132    <pre>
 133    template&lt;typename T&gt; struct class {
 134       static const bool is_specialized;
 135       static T max() throw();
 136       static T min() throw();
 137
 138       static const int digits;
 139       static const int digits10;
 140       static const bool is_signed;
 141       static const bool is_integer;
 142       static const bool is_exact;
 143       static const int radix;
 144       static T epsilon() throw();
 145       static T round_error() throw();
 146
 147       static const int min_exponent;
 148       static const int min_exponent10;
 149       static const int max_exponent;
 150       static const int max_exponent10;
 151
 152       static const bool has_infinity;
 153       static const bool has_quiet_NaN;
 154       static const bool has_signaling_NaN;
 155       static const float_denorm_style has_denorm;
 156       static const bool has_denorm_loss;
 157       static T infinity() throw();
 158       static T quiet_NaN() throw();
 159       static T denorm_min() throw();
 160
 161       static const bool is_iec559;
 162       static const bool is_bounded;
 163       static const bool is_modulo;
 164
 165       static const bool traps;
 166       static const bool tinyness_before;
 167       static const float_round_style round_style;
 168    };</pre>
 169    <p>Return <a href="#top">to top of page</a> or
 170       <a href="../faq/index.html">to the FAQ</a>.
 171    </p>
 172
 173 <hr />
 174 <h2><a name="3">Start and Termination</a></h2>
 175    <p>Not many changes here to <code>&lt;cstdlib&gt;</code> (the old stdlib.h).
 176       You should note that the <code>abort()</code> function does not call
 177       the destructors of automatic nor static objects, so if you're depending
 178       on those to do cleanup, it isn't going to happen.  (The functions
 179       registered with <code>atexit()</code> don't get called either, so you
 180       can forget about that possibility, too.)
 181    </p>
 182    <p>The good old <code>exit()</code> function can be a bit funky, too, until
 183       you look closer.  Basically, three points to remember are:
 184    </p>
 185       <ol>
 186         <li>Static objects are destroyed in reverse order of their creation.
 187         </li>
 188         <li>Functions registered with <code>atexit()</code> are called in
 189             reverse order of registration, once per registration call.
 190             (This isn't actually new.)
 191         </li>
 192         <li>The previous two actions are &quot;interleaved,&quot; that is,
 193             given this pseudocode:
 194             <pre>
 195               extern "C or C++" void  f1 (void);
 196               extern "C or C++" void  f2 (void);
 197
 198               static Thing obj1;
 199               atexit(f1);
 200               static Thing obj2;
 201               atexit(f2);
 202             </pre>
 203             then at a call of <code>exit()</code>, f2 will be called, then
 204             obj2 will be destroyed, then f1 will be called, and finally obj1
 205             will be destroyed.  If f1 or f2 allow an exception to propagate
 206             out of them, Bad Things happen.
 207         </li>
 208       </ol>
 209    <p>Note also that <code>atexit()</code> is only required to store 32
 210       functions, and the compiler/library might already be using some of
 211       those slots.  If you think you may run out, we recommend using
 212       the xatexit/xexit combination from libiberty, which has no such limit.
 213    </p>
 214    <p>Return <a href="#top">to top of page</a> or
 215       <a href="../faq/index.html">to the FAQ</a>.
 216    </p>
 217
 218 <hr />
 219 <h2><a name="4">Dynamic memory management</a></h2>
 220    <p>There are six flavors each of <code>new</code> and <code>delete</code>, so
 221       make certain that you're using the right ones!  Here are quickie
 222       descriptions of <code>new</code>:
 223         </p>
 224    <ul>
 225       <li>single object form, throwing a <code>bad_alloc</code> on errors;
 226           this is what most people are used to using</li>
 227       <li>single object &quot;nothrow&quot; form, returning NULL on errors</li>
 228       <li>array new, throwing <code>bad_alloc</code> on errors</li>
 229       <li>array nothrow new, returning NULL on errors</li>
 230       <li>placement new, which does nothing (like it's supposed to)</li>
 231       <li>placement array new, which also does nothing</li>
 232    </ul>
 233    <p>They are distinguished by the parameters that you pass to them, like
 234       any other overloaded function.  The six flavors of <code>delete</code>
 235       are distinguished the same way, but none of them are allowed to throw
 236       an exception under any circumstances anyhow.  (They match up for
 237       completeness' sake.)
 238    </p>
 239    <p>Remember that it is perfectly okay to call <code>delete</code> on a
 240       NULL pointer!  Nothing happens, by definition.  That is not the
 241       same thing as deleting a pointer twice.
 242    </p>
 243    <p>By default, if one of the &quot;throwing <code>new</code>s&quot; can't
 244       allocate the memory requested, it tosses an instance of a
 245       <code>bad_alloc</code> exception (or, technically, some class derived
 246       from it).  You can change this by writing your own function (called a
 247       new-handler) and then registering it with <code>set_new_handler()</code>:
 248         </p>
 249    <pre>
 250    typedef void (*PFV)(void);
 251
 252    static char*  safety;
 253    static PFV    old_handler;
 254
 255    void my_new_handler ()
 256    {
 257        delete[] safety;
 258        popup_window ("Dude, you are running low on heap memory.  You
 259                       should, like, close some windows, or something.
 260                       The next time you run out, we're gonna burn!");
 261        set_new_handler (old_handler);
 262        return;
 263    }
 264
 265    int main ()
 266    {
 267        safety = new char[500000];
 268        old_handler = set_new_handler (&amp;my_new_handler);
 269        ...
 270    }
 271    </pre>
 272    <p><code>bad_alloc</code> is derived from the base <code>exception</code>
 273       class defined in Chapter 19.
 274    </p>
 275    <p>Return <a href="#top">to top of page</a> or
 276       <a href="../faq/index.html">to the FAQ</a>.
 277    </p>
 278
 279 <hr />
 280 <h2><a name="5">RTTI, the ABI, and demangling</a></h2>
 281    <p>If you have read the <a href="../documentation.html#4">source
 282       documentation</a> for <code> namespace abi </code> then you are aware
 283       of the cross-vendor C++ ABI which we use.  One of the exposed
 284       functions is the one which we use for demangling in programs like
 285       <code>c++filt</code>, and you can use it yourself as well.
 286    </p>
 287    <p>(The function itself might use different demanglers, but that's the
 288       whole point of abstract interfaces.  If we change the implementation,
 289       you won't notice.)
 290    </p>
 291    <p>Probably the only times you'll be interested in demangling at runtime
 292       are when you're seeing <code>typeid</code> strings in RTTI, or when
 293       you're handling the runtime-support exception classes.  For example:
 294    </p>
 295    <pre>
 296 #include &lt;exception&gt;
 297 #include &lt;iostream&gt;
 298 #include &lt;cxxabi.h&gt;
 299
 300 struct empty { };
 301
 302 template &lt;typename T, int N&gt;
 303   struct bar { };
 304
 305
 306 int main()
 307 {
 308   int     status;
 309   char   *realname;
 310
 311   // exception classes not in &lt;stdexcept&gt;, thrown by the implementation
 312   // instead of the user
 313   std::bad_exception  e;
 314   realname = abi::__cxa_demangle(e.what(), 0, 0, &amp;status);
 315   std::cout &lt;&lt; e.what() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
 316   free(realname);
 317
 318
 319   // typeid
 320   bar&lt;empty,17&gt;          u;
 321   const std::type_info  &amp;ti = typeid(u);
 322
 323   realname = abi::__cxa_demangle(ti.name(), 0, 0, &amp;status);
 324   std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
 325   free(realname);
 326
 327   return 0;
 328 }</pre>
 329    <p>With GCC 3.1 and later, this prints
 330    </p>
 331    <pre>
 332       St13bad_exception       =&gt; std::bad_exception   : 0
 333       3barI5emptyLi17EE       =&gt; bar&lt;empty, 17&gt;       : 0 </pre>
 334    <p>The demangler interface is described in the source documentation
 335       linked to above.  It is actually written in C, so you don't need to
 336       be writing C++ in order to demangle C++.  (That also means we have to
 337       use crummy memory management facilities, so don't forget to free()
 338       the returned char array.)
 339    </p>
 340    <p>Return <a href="#top">to top of page</a> or
 341       <a href="../faq/index.html">to the FAQ</a>.
 342    </p>
 343
 344
 345 <!-- ####################################################### -->
 346
 347 <hr />
 348 <p class="fineprint"><em>
 349 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 350 Comments and suggestions are welcome, and may be sent to
 351 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 352 </em></p>
 353
 354
 355 </body>
 356 </html>