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

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <HTML>
   3 <HEAD>
   4    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   5    <META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (Phil Edwards)">
   6    <META NAME="KEYWORDS" CONTENT="HOWTO, libstdc++, GCC, g++, libg++, STL">
   7    <META NAME="DESCRIPTION" CONTENT="HOWTO for the libstdc++ chapter 18.">
   8    <META NAME="GENERATOR" CONTENT="vi and eight fingers">
   9    <TITLE>libstdc++-v3 HOWTO:  Chapter 18</TITLE>
  10 <LINK REL=StyleSheet HREF="../lib3styles.css">
  11 <!-- $Id: howto.html,v 1.7 2000/12/03 23:47:47 jsm28 Exp $ -->
  12 </HEAD>
  13 <BODY>
  14
  15 <H1 CLASS="centered"><A NAME="top">Chapter 18:  Library Support</A></H1>
  16
  17 <P>Chapter 18 deals with the functions called and objects created
  18    automatically during the course of a program's existence.
  19 </P>
  20 <P>While we can't reproduce the contents of the Standard here (you need to
  21    get your own copy from your nation's member body; see our homepage for
  22    help), we can mention a couple of changes in what kind of support a C++
  23    program gets from the Standard Library.
  24 </P>
  25
  26
  27 <!-- ####################################################### -->
  28 <HR>
  29 <H1>Contents</H1>
  30 <UL>
  31    <LI><A HREF="#1">Types</A>
  32    <LI><A HREF="#2">Implementation properties</A>
  33    <LI><A HREF="#3">Start and Termination</A>
  34    <LI><A HREF="#4">Dynamic memory management</A>
  35 </UL>
  36
  37 <HR>
  38
  39 <!-- ####################################################### -->
  40
  41 <H2><A NAME="1">Types</A></H2>
  42    <P>All the types that you're used to in C are here in one form or
  43       another.  The only change that might affect people is the type of
  44       NULL:  while it is required to be a macro, the definition of that
  45       macro is <EM>not</EM> allowed to be <TT>(void*)0</TT>, which is
  46       often used in C.
  47    </P>
  48    <P>In g++, NULL is #define'd to be <TT>__null</TT>, a magic keyword
  49       extension of g++.
  50    </P>
  51    <P>The biggest problem of #defining NULL to be something like
  52       &quot;0L&quot; is that the compiler will view that as a long integer
  53       before it views it as a pointer, so overloading won't do what you
  54       expect.  (This is why g++ has a magic extension, so that NULL is
  55       always a pointer.)
  56    </P>
  57    <P>In his book
  58       <A HREF="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&ptype=0"><EM>Effective C++</EM></A>,
  59       Scott Meyers points out that the best way to solve this problem is to
  60       not overload on pointer-vs-integer types to begin with.  He also
  61       offers a way to make your own magic NULL that will match pointers
  62       before it matches integers:
  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>(Cribbed from the published version of
  81       <A HREF="http://www.awlonline.com/cseng/meyerscddemo/">the
  82       Effective C++ CD</A>, reproduced here with permission.)
  83    </P>
  84    <P>If you aren't using g++ (why?), but you do have a compiler which
  85       supports member function templates, then you can use this definition
  86       of NULL (be sure to #undef any existing versions).  It only helps if
  87       you actually use NULL in function calls, though; if you make a call of
  88       <TT>foo(0);</TT> instead of <TT>foo(NULL);</TT>, then you're back
  89       where you started.
  90    </P>
  91    <P><B>Added Note:</B>  When we contacted Dr. Meyers to ask permission to
  92       print this stuff, it prompted him to run this code through current
  93       compilers to see what the state of the art is with respect to member
  94       template functions.  He posted
  95       <A HREF="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&CONTEXT=964036823.871301239">an
  96       article to Usenet</A> after discovering that the code above is not
  97       valid!  Even though it has no data members, it still needs a
  98       user-defined constructor (which means that the class needs a type name
  99       after all).  The ctor can have an empty body; it just needs to be
 100       there.  (Stupid requirement?  We think so too, and this will probably
 101       be changed in the language itself.)
 102    </P>
 103    <P>Return <A HREF="#top">to top of page</A> or
 104       <A HREF="../faq/index.html">to the FAQ</A>.
 105    </P>
 106
 107 <HR>
 108 <H2><A NAME="2">Implementation properties</A></H2>
 109    <P>
 110    <H3><CODE>&lt;limits&gt;</CODE></H3>
 111    This header mainly defines traits classes to give access to various
 112    implementation defined-aspects of the fundamental types.  The
 113    traits classes -- fourteen in total -- are all specilizations of the
 114    template class <CODE>numeric_limits</CODE> defined as follows:
 115    <PRE>
 116    template&lt;typename T&gt; struct class {
 117       static const bool is_specialized;
 118       static T max() throw();
 119       static T min() throw();
 120
 121       static const int digits;
 122       static const int digits10;
 123       static const bool is_signed;
 124       static const bool is_integer;
 125       static const bool is_exact;
 126       static const int radix;
 127       static T epsilon() throw();
 128       static T round_error() throw();
 129
 130       static const int min_exponent;
 131       static const int min_exponent10;
 132       static const int max_exponent;
 133       static const int max_exponent10;
 134
 135       static const bool has_infinity;
 136       static const bool has_quiet_NaN;
 137       static const bool has_signaling_NaN;
 138       static const float_denorm_style has_denorm;
 139       static const bool has_denorm_loss;
 140       static T infinity() throw();
 141       static T quiet_NaN() throw();
 142       static T denorm_min() throw();
 143
 144       static const bool is_iec559;
 145       static const bool is_bounded;
 146       static const bool is_modulo;
 147
 148       static const bool traps;
 149       static const bool tinyness_before;
 150       static const float_round_style round_style;
 151    };</PRE>
 152    </P>
 153    <P>Return <A HREF="#top">to top of page</A> or
 154       <A HREF="../faq/index.html">to the FAQ</A>.
 155    </P>
 156
 157 <HR>
 158 <H2><A NAME="3">Start and Termination</A></H2>
 159    <P>Not many changes here to <TT>&lt;cstdlib&gt;</TT> (the old stdlib.h).
 160       You should note that the <TT>abort()</TT> function does not call
 161       the destructors of automatic nor static objects, so if you're depending
 162       on those to do cleanup, it isn't going to happen.  (The functions
 163       registered with <TT>atexit()</TT> don't get called either, so you
 164       can forget about that possibility, too.)
 165    </P>
 166    <P>The good old <TT>exit()</TT> function can be a bit funky, too, until
 167       you look closer.  Basically, three points to remember are:
 168       <OL>
 169         <LI>Static objects are destroyed in reverse order of their creation.
 170         <LI>Functions registered with <TT>atexit()</TT> are called in
 171             reverse order of registration, once per registration call.
 172             (This isn't actually new.)
 173         <LI>The previous two actions are &quot;interleaved,&quot; that is,
 174             given this code:
 175             <PRE>
 176               extern "C or C++" void  f1 (void);
 177               extern "C or C++" void  f2 (void);
 178
 179               static Thing obj1;
 180               atexit(f1);
 181               static Thing obj2;
 182               atexit(f2);
 183             </PRE>then at a call of <TT>exit()</TT>, f2 will be called, then
 184             obj2 will be destroyed, then f1 will be called, and finally obj1
 185             will be destroyed.  If f1 or f2 allow an exception to propogate
 186             out of them, Bad Things happen.
 187       </OL>
 188    </P>
 189    <P>Return <A HREF="#top">to top of page</A> or
 190       <A HREF="../faq/index.html">to the FAQ</A>.
 191    </P>
 192
 193 <HR>
 194 <H2><A NAME="4">Dynamic memory management</A></H2>
 195    <P>There are six flavors each of <TT>new</TT> and <TT>delete</TT>, so
 196       make certain that you're using the right ones!  Here are quickie
 197       descriptions of <TT>new</TT>:
 198       <UL>
 199         <LI>single object form, throwing a <TT>bad_alloc</TT> on errors;
 200             this is what most people are used to using
 201         <LI>single object &quot;nothrow&quot; form, returning NULL on errors
 202         <LI>array new, throwing <TT>bad_alloc</TT> on errors
 203         <LI>array nothrow new, returning NULL on errors
 204         <LI>placement new, which does nothing (like it's supposed to)
 205         <LI>placement array new, which also does nothing
 206       </UL>
 207       They are distinguished by the parameters that you pass to them, like
 208       any other overloaded function.  The six flavors of <TT>delete</TT>
 209       are distinguished the same way, but none of them are allowed to throw
 210       an exception under any circumstances anyhow.  (They match up for
 211       completeness' sake.)
 212    </P>
 213    <P>Remember that it is perfectly okay to call <TT>delete</TT> on a
 214       NULL pointer!  Nothing happens, by definition.  That is not the
 215       same thing as deleting a pointer twice.
 216    </P>
 217    <P>By default, if one of the &quot;throwing <TT>new</TT>s&quot; can't
 218       allocate the memory requested, it tosses an instance of a
 219       <TT>bad_alloc</TT> exception (or, technically, some class derived
 220       from it).  You can change this by writing your own function (called
 221       a new-handler) and then registering it with <TT>set_new_handler()</TT>:
 222       <PRE>
 223    typedef void (*PFV)(void);
 224
 225    static char*  safety;
 226    static PFV    old_handler;
 227
 228    void my_new_handler ()
 229    {
 230        delete[] safety;
 231        popup_window ("Dude, you are running low on heap memory.  You
 232                       should, like, close some windows, or something.
 233                       The next time you run out, we're gonna burn!");
 234        set_new_handler (old_handler);
 235        return;
 236    }
 237
 238    int main ()
 239    {
 240        safety = new char[500000];
 241        old_handler = set_new_handler (&my_new_handler);
 242        ...
 243    }
 244       </PRE>
 245    </P>
 246    <P><TT>bad_alloc</TT> is derived from the base <TT>exception</TT>
 247       class defined in Chapter 19.
 248    </P>
 249    <P>Return <A HREF="#top">to top of page</A> or
 250       <A HREF="../faq/index.html">to the FAQ</A>.
 251    </P>
 252
 253
 254
 255
 256
 257 <!-- ####################################################### -->
 258
 259 <HR>
 260 <P CLASS="fineprint"><EM>
 261 Comments and suggestions are welcome, and may be sent to
 262 <A HREF="mailto:pme@sources.redhat.com">Phil Edwards</A> or
 263 <A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>.
 264 <BR> $Id: howto.html,v 1.7 2000/12/03 23:47:47 jsm28 Exp $
 265 </EM></P>
 266
 267
 268 </BODY>
 269 </HTML>