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