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

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