1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>Smart Pointers</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7 <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
8 <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
9 width="277" align="middle" border="0">Smart Pointers</h1>
10 <p><a href="#Introduction">Introduction</a><br>
11 <a href="#common_requirements">Common Requirements</a><br>
12 <a href="#Exception_Safety">Exception Safety</a><br>
13 <a href="#Exception-specifications">Exception-specifications</a><br>
14 <a href="#History">History and Acknowledgements</a><br>
15 <a href="#References">References</a></p>
16 <h2><a name="Introduction">Introduction</a></h2>
17 <p>Smart pointers are objects which store pointers to dynamically allocated (heap)
18 objects. They behave much like built-in C++ pointers except that they
19 automatically delete the object pointed to at the appropriate time. Smart
20 pointers are particularly useful in the face of exceptions as they ensure
21 proper destruction of dynamically allocated objects. They can also be used to
22 keep track of dynamically allocated objects shared by multiple owners.</p>
23 <p>Conceptually, smart pointers are seen as owning the object pointed to, and thus
24 responsible for deletion of the object when it is no longer needed.</p>
25 <p>The smart pointer library provides six smart pointer class templates:</p>
27 <table border="1" cellpadding="4" cellspacing="0">
29 <td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
30 <td><a href="../../boost/scoped_ptr.hpp"><boost/scoped_ptr.hpp></a></td>
31 <td>Simple sole ownership of single objects. Noncopyable.</td>
34 <td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
35 <td><a href="../../boost/scoped_array.hpp"><boost/scoped_array.hpp></a></td>
36 <td>Simple sole ownership of arrays. Noncopyable.</td>
39 <td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
40 <td><a href="../../boost/shared_ptr.hpp"><boost/shared_ptr.hpp></a></td>
41 <td>Object ownership shared among multiple pointers.</td>
44 <td><a href="shared_array.htm"><b>shared_array</b></a></td>
45 <td><a href="../../boost/shared_array.hpp"><boost/shared_array.hpp></a></td>
46 <td>Array ownership shared among multiple pointers.</td>
49 <td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
50 <td><a href="../../boost/weak_ptr.hpp"><boost/weak_ptr.hpp></a></td>
51 <td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
54 <td><a href="intrusive_ptr.html"><b>intrusive_ptr</b></a></td>
55 <td><a href="../../boost/intrusive_ptr.hpp"><boost/intrusive_ptr.hpp></a></td>
56 <td>Shared ownership of objects with an embedded reference count.</td>
60 <p>These templates are designed to complement the <b>std::auto_ptr</b> template.</p>
61 <p>They are examples of the "resource acquisition is initialization" idiom
62 described in Bjarne Stroustrup's "The C++ Programming Language", 3rd edition,
63 Section 14.4, Resource Management.</p>
64 <p>Additionally, the smart pointer library provides efficient factory functions
65 for creating smart pointer objects:</p>
67 <table border="1" cellpadding="4" cellspacing="0">
69 <td><a href="make_shared.html"><b>make_shared, allocate_shared</b></a> for objects</td>
70 <td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
71 <td>Efficient creation of <code>shared_ptr</code> objects.</td>
74 <td><a href="make_shared_array.html"><b>make_shared, allocate_shared</b></a> for arrays</td>
75 <td><a href="../../boost/make_shared.hpp"><boost/make_shared.hpp></a></td>
76 <td>Efficient creation of <code>shared_ptr</code> arrays.</td>
79 <td><a href="make_unique.html"><b>make_unique</b></a></td>
80 <td><a href="../../boost/make_unique.hpp"><boost/make_unique.hpp></a></td>
81 <td>Creation of <code>unique_ptr</code> objects and arrays.</td>
85 <p>A test program, <a href="test/smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
86 provided to verify correct operation.</p>
87 <p>A page on <a href="compatibility.htm">compatibility</a> with older versions of
88 the Boost smart pointer library describes some of the changes since earlier
89 versions of the smart pointer implementation.</p>
90 <p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of interest
91 to those curious about performance issues.</p>
92 <P>A page on <A href="sp_techniques.html">smart pointer programming techniques</A> lists
93 some advanced applications of <code>shared_ptr</code> and <code>weak_ptr</code>.</P>
94 <h2><a name="common_requirements">Common Requirements</a></h2>
95 <p>These smart pointer class templates have a template parameter, <b>T</b>, which
96 specifies the type of the object pointed to by the smart pointer. The behavior
97 of the smart pointer templates is undefined if the destructor or <b>operator delete</b>
98 for objects of type <b>T</b> throw exceptions.</p>
99 <p><b>T</b> may be an incomplete type at the point of smart pointer declaration.
100 Unless otherwise specified, it is required that <b>T</b> be a complete type at
101 points of smart pointer instantiation. Implementations are required to diagnose
102 (treat as an error) all violations of this requirement, including deletion of
103 an incomplete type. See the description of the <a href="../utility/utility.htm#checked_delete">
104 <b>checked_delete</b></a> function template.</p>
105 <P>Note that <STRONG>shared_ptr</STRONG> does not have this restriction, as most of
106 its member functions do not require <STRONG>T</STRONG> to be a complete type.</P>
108 <p>The requirements on <b>T</b> are carefully crafted to maximize safety yet allow
109 handle-body (also called pimpl) and similar idioms. In these idioms a smart
110 pointer may appear in translation units where <b>T</b> is an incomplete type.
111 This separates interface from implementation and hides implementation from
112 translation units which merely use the interface. Examples described in the
113 documentation for specific smart pointers illustrate use of smart pointers in
115 <p>Note that <b>scoped_ptr</b> requires that <b>T</b> be a complete type at
116 destruction time, but <b>shared_ptr</b> does not.</p>
117 <h2><a name="Exception_Safety">Exception Safety</a></h2>
118 <p>Several functions in these smart pointer classes are specified as having "no
119 effect" or "no effect except such-and-such" if an exception is thrown. This
120 means that when an exception is thrown by an object of one of these classes,
121 the entire program state remains the same as it was prior to the function call
122 which resulted in the exception being thrown. This amounts to a guarantee that
123 there are no detectable side effects. Other functions never throw exceptions.
124 The only exception ever thrown by functions which do throw (assuming <b>T</b> meets
125 the <a href="#common_requirements">common requirements</a>) is <b>std::bad_alloc</b>,
126 and that is thrown only by functions which are explicitly documented as
127 possibly throwing <b>std::bad_alloc</b>.</p>
128 <h2><a name="Exception-specifications">Exception-specifications</a></h2>
129 <p>Exception-specifications are not used; see <a href="http://www.boost.org/more/lib_guide.htm#Exception-specification">
130 exception-specification rationale</a>.</p>
131 <p>All the smart pointer templates contain member functions which can never throw
132 exceptions, because they neither throw exceptions themselves nor call other
133 functions which may throw exceptions. These members are indicated by a comment: <code>
134 // never throws</code>.
136 <p>Functions which destroy objects of the pointed to type are prohibited from
137 throwing exceptions by the <a href="#common_requirements">common requirements</a>.</p>
138 <h2><a name="History">History</a> and Acknowledgements</h2>
139 <p>February 2017. Glen Fernandes rewrote <b>allocate_shared</b>
140 and <b>make_shared</b> for arrays for a more optimal and more
141 maintainable implementation.</p>
142 <p>February 2014. Glen Fernandes updated overloads of <b>make_shared</b> and
143 <b>allocate_shared</b> to conform to the specification in C++ standard paper
144 <a href="#D&F-14">[D&F-14]</a>, and implemented <b>make_unique</b> for
145 arrays and objects. Peter Dimov and Glen Fernandes updated the scalar and
146 array implementations, respectively, to resolve C++ standard library defect
148 <p>November 2012. Glen Fernandes provided implementations of <b>make_shared</b>
149 and <b>allocate_shared</b> for arrays. They achieve a single allocation for an
150 array that can be initialized with constructor arguments or initializer lists
151 as well as overloads for default initialization and no value initialization.
152 See the <a href="make_shared_array.html">make_shared and allocate_shared for
153 arrays</a> page for more information.</p>
154 <p>January 2002. Peter Dimov reworked all four classes, adding features, fixing
155 bugs, and splitting them into four separate headers, and added <b>weak_ptr</b>.
156 See the <a href="compatibility.htm">compatibility</a> page for a summary of the
158 <p>May 2001. Vladimir Prus suggested requiring a complete type on destruction.
159 Refinement evolved in discussions including Dave Abrahams, Greg Colvin, Beman
160 Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and
162 <p>November 1999. Darin Adler provided <b>operator ==</b>, <b>operator !=</b>, and <b>std::swap</b>
163 and <b>std::less</b> specializations for shared types.</p>
164 <p>September 1999. Luis Coelho provided <b>shared_ptr::swap</b> and <b>shared_array::swap</b></p>
165 <p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a
166 number of suggestions resulting in numerous improvements.</p>
167 <p>October 1998. Beman Dawes proposed reviving the original semantics under the
168 names <b>safe_ptr</b> and <b>counted_ptr</b>, meeting of Per Andersson, Matt
169 Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar Kühl,
170 Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new
171 class names were finalized, it was decided that there was no need to exactly
172 follow the <b>std::auto_ptr</b> interface, and various function signatures and
173 semantics were finalized.</p>
174 <p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
175 and discussed on the <a href="http://www.boost.org">boost.org</a> mailing list.
176 The implementation questions revolved around the reference count which must be
177 kept, either attached to the pointed to object, or detached elsewhere. Each of
178 those variants have themselves two major variants:
181 Direct detached: the shared_ptr contains a pointer to the object, and a pointer
184 Indirect detached: the shared_ptr contains a pointer to a helper object, which
185 in turn contains a pointer to the object and the count.
187 Embedded attached: the count is a member of the object pointed to.
189 Placement attached: the count is attached via operator new manipulations.</li>
191 <p>Each implementation technique has advantages and disadvantages. We went so far
192 as to run various timings of the direct and indirect approaches, and found that
193 at least on Intel Pentium chips there was very little measurable difference.
194 Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar
195 Kühl suggested an elegant partial template specialization technique to allow
196 users to choose which implementation they preferred, and that was also
197 experimented with.</p>
198 <p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage
199 users", and in the end we choose to supply only the direct implementation.</p>
200 <p>Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named <b>auto_ptr</b>
201 and <b>counted_ptr</b> which were very similar to what we now call <b>scoped_ptr</b>
202 and <b>shared_ptr</b>. <a href="#Col-94">[Col-94]</a> In one of the very few
203 cases where the Library Working Group's recommendations were not followed by
204 the full committee, <b>counted_ptr</b> was rejected and surprising
205 transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
206 <h2><a name="References">References</a></h2>
207 <p>[<a name="D&F-14">D&F-14</a>] Peter Dimov & Glen Fernandes, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">
208 Extending make_shared to Support Arrays, Revision 1</a>, C++ committee document N3870,
210 <p>[<a name="Col-94">Col-94</a>] Gregory Colvin, <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1994/N0555.pdf">
211 Exception Safe Smart Pointers</a>, C++ committee document 94-168/N0555,
213 <p>[<a name="E&D-94">E&D-94</a>] John R. Ellis & David L. Detlefs, <a href="http://www.usenix.org/publications/library/proceedings/c++94/full_papers/ellis.a">
214 Safe, Efficient Garbage Collection for C++</a>, Usenix Proceedings,
215 February, 1994. This paper includes an extensive discussion of weak pointers
216 and an extensive bibliography.</p>
219 <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
220 Distributed under the Boost Software License, Version 1.0. See accompanying
221 file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at
222 <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
projects / platform / upstream / boost.git / blob