Smart Pointers

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.

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.

These smart pointer class templates have a template parameter, T, 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 operator delete
for objects of type T throw exceptions.

T may be an incomplete type at the point of smart pointer declaration.
Unless otherwise specified, it is required that T 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 checked_delete function template.

Note that shared_ptr does not have this restriction, as most of
its member functions do not require T to be a complete type.

Rationale

The requirements on T 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 T 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.

Note that scoped_ptr requires that T be a complete type at
destruction time, but shared_ptr does not.

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 T meets
the common requirements) is std::bad_alloc,
and that is thrown only by functions which are explicitly documented as
possibly throwing std::bad_alloc.

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:
// never throws.

Functions which destroy objects of the pointed to type are prohibited from
throwing exceptions by the common requirements.

January 2002. Peter Dimov reworked all four classes, adding features, fixing
bugs, and splitting them into four separate headers, and added weak_ptr.
See the compatibility page for a summary of the
changes.

May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams made a
number of suggestions resulting in numerous improvements.

October 1998. Beman Dawes proposed reviving the original semantics under the
names safe_ptr and counted_ptr, meeting of Per Andersson, Matt
Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar Kühl,
Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new
class names were finalized, it was decided that there was no need to exactly
follow the std::auto_ptr interface, and various function signatures and
semantics were finalized.

Over the next three months, several implementations were considered for shared_ptr,
and discussed on the boost.org 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:

Direct detached: the shared_ptr contains a pointer to the object, and a pointer
to the count.

Indirect detached: the shared_ptr contains a pointer to a helper object, which
in turn contains a pointer to the object and the count.

Embedded attached: the count is a member of the object pointed to.

Placement attached: the count is attached via operator new manipulations.

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.

But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage
users", and in the end we choose to supply only the direct implementation.

Summer, 1994. Greg Colvin proposed to the C++ Standards Committee classes named auto_ptr
and counted_ptr which were very similar to what we now call scoped_ptr
and shared_ptr. [Col-94] In one of the very few
cases where the Library Working Group's recommendations were not followed by
the full committee, counted_ptr was rejected and surprising
transfer-of-ownership semantics were added to auto_ptr.