mirror of
https://github.com/boostorg/smart_ptr.git
synced 2025-11-03 01:01:54 +01:00
1a7cd887e4
library. Changing includes to include the new individual smart pointer headers. Replacing old smart pointer library with an include of the new smart pointer headers. Simplify ifdefs that involve the member templates macros now that BOOST_MSVC6_MEMBER_TEMPLATES is also guaranteed to bet set for platforms that have full member templates. [SVN r12647]
212 lines
9.9 KiB
HTML
212 lines
9.9 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
||
<html>
|
||
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<title>Smart Pointers</title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF" text="#000000">
|
||
|
||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">Smart
|
||
Pointers</h1>
|
||
|
||
<p>Smart pointers are objects which store pointers to dynamically allocated
|
||
(heap) objects. They behave much like built-in C++ pointers except that
|
||
they automatically delete the object pointed to at the appropriate
|
||
time. Smart pointers are particularly useful in the face of exceptions as
|
||
they ensure proper destruction of dynamically allocated objects. They can also
|
||
be used to keep track of dynamically allocated objects shared by multiple
|
||
owners.</p>
|
||
|
||
<p>Conceptually, smart pointers are seen as owning the object pointed to, and
|
||
thus responsible for deletion of the object when it is no longer needed.</p>
|
||
|
||
<p>The smart pointer library provides five smart pointer class templates:</p>
|
||
|
||
<div align="left">
|
||
<table border="1" cellpadding="4" cellspacing="4">
|
||
<tr>
|
||
<td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
|
||
<td><a href="../boost/scoped_ptr.hpp"><boost/scoped_ptr.hpp></a></td>
|
||
<td>Simple sole ownership of single objects. Noncopyable.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
|
||
<td><a href="../boost/scoped_array.hpp"><boost/scoped_array.hpp></a></td>
|
||
<td>Simple sole ownership of arrays. Noncopyable.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
|
||
<td><a href="../boost/shared_ptr.hpp"><boost/shared_ptr.hpp></a></td>
|
||
<td>Object ownership shared among multiple pointers</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="shared_array.htm"><b>shared_array</b></a></td>
|
||
<td><a href="../boost/shared_array.hpp"><boost/shared_array.hpp></a></td>
|
||
<td>Array ownership shared among multiple pointers.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
|
||
<td><a href="../boost/weak_ptr.hpp"><boost/weak_ptr.hpp></a></td>
|
||
<td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
|
||
<p>These templates are designed to complement the <b>std::auto_ptr</b> template.</p>
|
||
|
||
<p>They are examples of the "resource acquisition is initialization"
|
||
idiom described in Bjarne Stroustrup's "The C++ Programming Language",
|
||
3rd edition, Section 14.4, Resource Management.</p>
|
||
|
||
<p>A test program, <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
|
||
provided to verify correct operation.</p>
|
||
|
||
<p>A page on <a href="compatibility.htm">compatibility</a> with older versions of
|
||
the Boost smart pointer library describes some of the changes since earlier versions
|
||
of the smart pointer implementation.</p>
|
||
|
||
<p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of
|
||
interest to those curious about performance issues.</p>
|
||
|
||
<h2><a name="Common requirements">Common Requirements</a></h2>
|
||
|
||
<p>These smart pointer class templates have a template parameter, <b>T</b>, which
|
||
specifies the type of the object pointed to by the smart pointer. The
|
||
behavior of the smart pointer templates is undefined if the destructor or <b>operator delete</b>
|
||
for objects of type <b>T</b> throw exceptions.</p>
|
||
|
||
<p><b>T</b> may be an incomplete type at the point of smart pointer
|
||
declaration. Unless otherwise specified, it is required that <b>T</b>
|
||
be a complete type at points of smart pointer instantiation. Implementations are
|
||
required to diagnose (treat as an error) all violations of this requirement,
|
||
including deletion of an incomplete type.
|
||
See the description of the <a href="../utility/utility.htm#checked_delete"><b>checked_delete</b></a>
|
||
function template.</p>
|
||
|
||
<h3>Rationale</h3>
|
||
|
||
<p>The requirements on <b>T</b> are carefully crafted to maximize safety
|
||
yet allow handle-body (also called pimpl) and similar idioms. In these idioms a
|
||
smart pointer may appear in translation units where <b>T</b> is an
|
||
incomplete type. This separates interface from implementation and hides
|
||
implementation from translation units which merely use the interface.
|
||
Examples described in the documentation for specific smart pointers illustrate
|
||
use of smart pointers in these idioms.</p>
|
||
|
||
<p>Note that <b>scoped_ptr</b> requires that <b>T</b> be a complete type
|
||
at destruction time, but <b>shared_ptr</b> does not.</p>
|
||
|
||
<h2>Exception Safety</h2>
|
||
|
||
<p>Several functions in these smart pointer classes are specified as having
|
||
"no effect" or "no effect except such-and-such" if an
|
||
exception is thrown. This means that when an exception is thrown by
|
||
an object of one of these classes, the entire program state remains the same as
|
||
it was prior to the function call which resulted in the exception being
|
||
thrown. This amounts to a guarantee that there are no detectable side
|
||
effects. Other functions never throw exceptions. The only exception
|
||
ever thrown by functions which do throw (assuming <b>T</b> meets the
|
||
<a href="#Common requirements">common requirements</a>) is <b>std::bad_alloc</b>,
|
||
and that is thrown only by functions which are explicitly documented as possibly
|
||
throwing <b>std::bad_alloc</b>.</p>
|
||
|
||
<h2>Exception-specifications</h2>
|
||
|
||
<p>Exception-specifications are not used; see
|
||
<a href="../../more/lib_guide.htm#Exception-specification">exception-specification
|
||
rationale</a>.</p>
|
||
|
||
<p>All the smart pointer templates contain member functions which can never throw exceptions,
|
||
because they neither throw exceptions themselves nor call other functions which
|
||
may throw exceptions. These members are indicated by a comment:
|
||
<code>// never throws</code>. </p>
|
||
|
||
<p>Functions which destroy objects of the pointed to type are prohibited from
|
||
throwing exceptions by the <a href="#Common requirements">common requirements</a>.</p>
|
||
|
||
<h2>History and Acknowledgements</h2>
|
||
|
||
<p>January 2002. Peter Dimov reworked all four classes, adding features, fixing bugs,
|
||
and splitting them into four separate headers, and added <b>weak_ptr</b>. See the
|
||
<a href="compatibility.htm">compatibility</a> page for a summary of the changes.</p>
|
||
|
||
<p>May 2001. Vladimir Prus suggested requiring a complete type on
|
||
destruction. Refinement evolved in discussions including Dave Abrahams,
|
||
Greg Colvin, Beman Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus,
|
||
Shankar Sai, and others.</p>
|
||
|
||
<p>November 1999. Darin Adler provided operator ==, operator !=, and std::swap
|
||
and std::less specializations for shared types.</p>
|
||
|
||
<p>September 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap</p>
|
||
|
||
<p>May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams
|
||
made a number of suggestions resulting in numerous improvements. See the
|
||
revision history in <a href="../../boost/smart_ptr.hpp"><b>smart_ptr.hpp</b></a>
|
||
for the specific changes made as a result of their constructive criticism.</p>
|
||
|
||
<p>October 1998. In 1994 Greg Colvin proposed to the C++ Standards Committee
|
||
classes named <b>auto_ptr</b> and <b>counted_ptr</b> which
|
||
were very similar to what we now call <b>scoped_ptr</b> and <b>shared_ptr</b>.
|
||
The committee document was 94-168/N0555, Exception Safe Smart Pointers. In
|
||
one of the very few cases where the Library Working Group's recommendations were
|
||
not followed by the full committee, <b>counted_ptr</b> was rejected
|
||
and surprising transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
|
||
|
||
<p>Beman Dawes proposed reviving the original semantics under the names <b>safe_ptr</b>
|
||
and <b>counted_ptr</b> at an October, 1998, meeting of Per Andersson,
|
||
Matt Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar
|
||
K<EFBFBD>hl, Nathan Myers, Chichiang Wan and Judy Ward. During the discussion,
|
||
the four class names were finalized, it was decided that there was no need to
|
||
exactly follow the <b>std::auto_ptr</b> interface, and various
|
||
function signatures and semantics were finalized.</p>
|
||
|
||
<p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
|
||
and discussed on the <a href="http://www.boost.org">boost.org</a> mailing
|
||
list. The implementation questions revolved around the reference count
|
||
which must be kept, either attached to the pointed to object, or detached
|
||
elsewhere. Each of those variants have themselves two major variants:
|
||
|
||
<ul>
|
||
<li>Direct detached: the shared_ptr contains a pointer to the object, and a
|
||
pointer to the count.</li>
|
||
<li>Indirect detached: the shared_ptr contains a pointer to a helper object,
|
||
which in turn contains a pointer to the object and the count.</li>
|
||
<li>Embedded attached: the count is a member of the object pointed to.</li>
|
||
<li>Placement attached: the count is attached via operator new manipulations.</li>
|
||
</ul>
|
||
|
||
<p>Each implementation technique has advantages and disadvantages. We went
|
||
so far as to run various timings of the direct and indirect approaches, and
|
||
found that at least on Intel Pentium chips there was very little measurable
|
||
difference. Kevlin Henney provided a paper he wrote on "Counted Body
|
||
Techniques." Dietmar K<>hl suggested an elegant partial template
|
||
specialization technique to allow users to choose which implementation they
|
||
preferred, and that was also experimented with.</p>
|
||
|
||
<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will
|
||
discourage users", and in the end we choose to supply only the direct
|
||
implementation.</p>
|
||
|
||
<p>See the Revision History section of the header for further contributors.</p>
|
||
|
||
<hr>
|
||
|
||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan
|
||
-->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="15110"
|
||
--></p>
|
||
|
||
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
|
||
Permission to copy, use,
|
||
modify, sell and distribute this document is granted provided this copyright
|
||
notice appears in all copies. This document is provided "as is"
|
||
without express or implied warranty, and with no claim as to its suitability for
|
||
any purpose.</p>
|
||
|
||
</body>
|
||
|
||
</html>
|