l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.4/doc/xml/manual/auto_ptr.xml

   1 <sect1 id="manual.util.memory.auto_ptr" xreflabel="auto_ptr">
   2 <?dbhtml filename="auto_ptr.html"?>
   3
   4 <sect1info>
   5   <keywordset>
   6     <keyword>
   7       ISO C++
   8     </keyword>
   9     <keyword>
  10       auto_ptr
  11     </keyword>
  12   </keywordset>
  13 </sect1info>
  14
  15 <title>auto_ptr</title>
  16
  17 <sect2 id="auto_ptr.limitations" xreflabel="auto_ptr.limitations">
  18 <title>Limitations</title>
  19
  20    <para>Explaining all of the fun and delicious things that can
  21    happen with misuse of the <classname>auto_ptr</classname> class
  22    template (called <acronym>AP</acronym> here) would take some
  23    time. Suffice it to say that the use of <acronym>AP</acronym>
  24    safely in the presence of copying has some subtleties.
  25    </para>
  26    <para>
  27      The AP class is a really
  28       nifty idea for a smart pointer, but it is one of the dumbest of
  29       all the smart pointers -- and that's fine.
  30    </para>
  31    <para>
  32      AP is not meant to be a supersmart solution to all resource
  33       leaks everywhere.  Neither is it meant to be an effective form
  34       of garbage collection (although it can help, a little bit).
  35       And it can <emphasis>not</emphasis>be used for arrays!
  36    </para>
  37    <para>
  38      <acronym>AP</acronym> is meant to prevent nasty leaks in the
  39      presence of exceptions.  That's <emphasis>all</emphasis>.  This
  40      code is AP-friendly:
  41    </para>
  42    <programlisting>
  43     // Not a recommend naming scheme, but good for web-based FAQs.
  44     typedef std::auto_ptr&lt;MyClass&gt;  APMC;
  45
  46     extern function_taking_MyClass_pointer (MyClass*);
  47     extern some_throwable_function ();
  48
  49     void func (int data)
  50     {
  51         APMC  ap (new MyClass(data));
  52
  53         some_throwable_function();   // this will throw an exception
  54
  55         function_taking_MyClass_pointer (ap.get());
  56     }
  57    </programlisting>
  58    <para>When an exception gets thrown, the instance of MyClass that's
  59       been created on the heap will be <function>delete</function>'d as the stack is
  60       unwound past <function>func()</function>.
  61    </para>
  62    <para>Changing that code as follows is not <acronym>AP</acronym>-friendly:
  63    </para>
  64    <programlisting>
  65         APMC  ap (new MyClass[22]);
  66    </programlisting>
  67    <para>You will get the same problems as you would without the use
  68       of <acronym>AP</acronym>:
  69    </para>
  70    <programlisting>
  71         char*  array = new char[10];       // array new...
  72         ...
  73         delete array;                      // ...but single-object delete
  74    </programlisting>
  75    <para>
  76      AP cannot tell whether the pointer you've passed at creation points
  77       to one or many things.  If it points to many things, you are about
  78       to die.  AP is trivial to write, however, so you could write your
  79       own <code>auto_array_ptr</code> for that situation (in fact, this has
  80       been done many times; check the mailing lists, Usenet, Boost, etc).
  81    </para>
  82 </sect2>
  83
  84 <sect2 id="auto_ptr.using" xreflabel="auto_ptr.using">
  85 <title>Use in Containers</title>
  86
  87   <para>
  88   </para>
  89   <para>All of the <ulink url="../23_containers/howto.html">containers</ulink>
  90       described in the standard library require their contained types
  91       to have, among other things, a copy constructor like this:
  92   </para>
  93    <programlisting>
  94     struct My_Type
  95     {
  96         My_Type (My_Type const&amp;);
  97     };
  98    </programlisting>
  99    <para>
 100      Note the const keyword; the object being copied shouldn't change.
 101      The template class <code>auto_ptr</code> (called AP here) does not
 102      meet this requirement.  Creating a new AP by copying an existing
 103      one transfers ownership of the pointed-to object, which means that
 104      the AP being copied must change, which in turn means that the
 105      copy ctors of AP do not take const objects.
 106    </para>
 107    <para>
 108      The resulting rule is simple: <emphasis>Never ever use a
 109      container of auto_ptr objects</emphasis>. The standard says that
 110      <quote>undefined</quote> behavior is the result, but it is
 111      guaranteed to be messy.
 112    </para>
 113    <para>
 114      To prevent you from doing this to yourself, the
 115       <ulink url="../19_diagnostics/howto.html#3">concept checks</ulink> built
 116       in to this implementation will issue an error if you try to
 117       compile code like this:
 118    </para>
 119    <programlisting>
 120     #include &lt;vector&gt;
 121     #include &lt;memory&gt;
 122
 123     void f()
 124     {
 125         std::vector&lt; std::auto_ptr&lt;int&gt; &gt;   vec_ap_int;
 126     }
 127    </programlisting>
 128    <para>
 129 Should you try this with the checks enabled, you will see an error.
 130    </para>
 131 </sect2>
 132
 133 </sect1>