auto_ptr.xml revision 1.1 
1<section id="std.util.memory.auto_ptr" xreflabel="auto_ptr">
2<?dbhtml filename="auto_ptr.html"?>
3
4<sectioninfo>
5  <keywordset>
6    <keyword>
7      ISO C++
8    </keyword>
9    <keyword>
10      auto_ptr
11    </keyword>
12  </keywordset>
13</sectioninfo>
14
15<title>auto_ptr</title>
16
17<section id="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</section>
83
84<section id="auto_ptr.using">
85<title>Use in Containers</title>
86
87  <para>
88  </para>
89  <para>All of the <link linkend="std.containers">containers</link>
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      <link linkend="manual.ext.compile_checks">concept checks</link> 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>
129Should you try this with the checks enabled, you will see an error.
130   </para>
131</section>
132
133</section>
134