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"?>
5 <info><title>auto_ptr</title>
18 <section xml:id="auto_ptr.limitations"><info><title>Limitations</title></info>
21 <para>Explaining all of the fun and delicious things that can
22 happen with misuse of the <classname>auto_ptr</classname> class
23 template (called <acronym>AP</acronym> here) would take some
24 time. Suffice it to say that the use of <acronym>AP</acronym>
25 safely in the presence of copying has some subtleties.
28 The AP class is a really
29 nifty idea for a smart pointer, but it is one of the dumbest of
30 all the smart pointers -- and that's fine.
33 AP is not meant to be a supersmart solution to all resource
34 leaks everywhere. Neither is it meant to be an effective form
35 of garbage collection (although it can help, a little bit).
36 And it can <emphasis>not</emphasis>be used for arrays!
39 <acronym>AP</acronym> is meant to prevent nasty leaks in the
40 presence of exceptions. That's <emphasis>all</emphasis>. This
44 // Not a recommend naming scheme, but good for web-based FAQs.
45 typedef std::auto_ptr<MyClass> APMC;
47 extern function_taking_MyClass_pointer (MyClass*);
48 extern some_throwable_function ();
52 APMC ap (new MyClass(data));
54 some_throwable_function(); // this will throw an exception
56 function_taking_MyClass_pointer (ap.get());
59 <para>When an exception gets thrown, the instance of MyClass that's
60 been created on the heap will be <function>delete</function>'d as the stack is
61 unwound past <function>func()</function>.
63 <para>Changing that code as follows is not <acronym>AP</acronym>-friendly:
66 APMC ap (new MyClass[22]);
68 <para>You will get the same problems as you would without the use
69 of <acronym>AP</acronym>:
72 char* array = new char[10]; // array new...
74 delete array; // ...but single-object delete
77 AP cannot tell whether the pointer you've passed at creation points
78 to one or many things. If it points to many things, you are about
79 to die. AP is trivial to write, however, so you could write your
80 own <code>auto_array_ptr</code> for that situation (in fact, this has
81 been done many times; check the mailing lists, Usenet, Boost, etc).
85 <section xml:id="auto_ptr.using"><info><title>Use in Containers</title></info>
90 <para>All of the <link linkend="std.containers">containers</link>
91 described in the standard library require their contained types
92 to have, among other things, a copy constructor like this:
97 My_Type (My_Type const&);
101 Note the const keyword; the object being copied shouldn't change.
102 The template class <code>auto_ptr</code> (called AP here) does not
103 meet this requirement. Creating a new AP by copying an existing
104 one transfers ownership of the pointed-to object, which means that
105 the AP being copied must change, which in turn means that the
106 copy ctors of AP do not take const objects.
109 The resulting rule is simple: <emphasis>Never ever use a
110 container of auto_ptr objects</emphasis>. The standard says that
111 <quote>undefined</quote> behavior is the result, but it is
112 guaranteed to be messy.
115 To prevent you from doing this to yourself, the
116 <link linkend="manual.ext.compile_checks">concept checks</link> built
117 in to this implementation will issue an error if you try to
118 compile code like this:
121 #include <vector>
122 #include <memory>
126 std::vector< std::auto_ptr<int> > vec_ap_int;
130 Should you try this with the checks enabled, you will see an error.