shared_ptr class template

The shared_ptr class template stores a pointer to a dynamically allocated
object, typically with a C++ new-expression. The object pointed to is
guaranteed to be deleted when the last shared_ptr pointing to it is
destroyed or reset. See the example.

Every shared_ptr meets the CopyConstructible and Assignable
requirements of the C++ Standard Library, and so can be used in standard
library containers. Comparison operators are supplied so that shared_ptr
works with the standard library's associative containers.

Normally, a shared_ptr cannot correctly hold a pointer to a dynamically
allocated array. See shared_array for
that usage.

Because the implementation uses reference counting, cycles of shared_ptr instances
will not be reclaimed. For example, if main() holds a shared_ptr to
A, which directly or indirectly holds a shared_ptr back to A,
A's use count will be 2. Destruction of the original shared_ptr will
leave A dangling with a use count of 1. Use weak_ptr
to "break cycles."

The class template is parameterized on T, the type of the object pointed
to. shared_ptr and most of its member functions place no
requirements on T; it is allowed to be an incomplete type, or
void. Member functions that do place additional requirements (constructors,
reset) are explicitly documented below.

shared_ptr<T> can be implicitly converted to shared_ptr<U>
whenever T* can be implicitly converted to U*.
In particular, shared_ptr<T> is implicitly convertible
to shared_ptr<T const>, to shared_ptr<U>
where U is an accessible base of T, and to
shared_ptr<void>.

shared_ptr is now part of TR1, the first C++
Library Technical Report. The latest draft of TR1 is available
at the following location:

A simple guideline that nearly eliminates the possibility of memory leaks is:
always use a named smart pointer variable to hold the result of new.
Every occurence of the new keyword in the code should have the
form:

shared_ptr<T> p(new Y);

It is, of course, acceptable to use another smart pointer in place of shared_ptr
above; having T and Y be the same type, or
passing arguments to Y's constructor is also OK.

If you observe this guideline, it naturally follows that you will have no
explicit deletes; try/catch constructs will
be rare.

Avoid using unnamed shared_ptr temporaries to save typing; to
see why this is dangerous, consider this example:

The function ok follows the guideline to the letter, whereas
bad constructs the temporary shared_ptr in place,
admitting the possibility of a memory leak. Since function arguments are
evaluated in unspecified order, it is possible for new int(2) to
be evaluated first, g() second, and we may never get to the
shared_ptr constructor if g throws an exception.
See Herb Sutter's treatment (also
here) of the issue for more information.

The exception safety problem described above may also be eliminated by using
the make_shared
or allocate_shared
factory functions defined in boost/make_shared.hpp. These factory functions also provide
an efficiency benefit by consolidating allocations.

[The nothrow guarantee is important, since reset() is specified
in terms of the default constructor; this implies that the constructor must not
allocate memory.]

template<class Y> explicit shared_ptr(Y * p);

Requirements:p must be convertible to T *. Y
must be a complete type. The expression delete p must be
well-formed, must not invoke undefined behavior, and must not throw exceptions.

Effects: Constructs a shared_ptr that owns the pointer p.

Postconditions:use_count() == 1 && get() == p.

Throws:std::bad_alloc, or an implementation-defined
exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, delete p is
called.

Notes:p must be a pointer to an object that was
allocated via a C++ new expression or be 0. The postcondition that
use count is 1 holds even if p is 0; invoking delete
on a pointer that has a value of 0 is harmless.

[This constructor has been changed to a template in order to remember the actual
pointer type passed. The destructor will call delete with the
same pointer, complete with its original type, even when T does
not have a virtual destructor, or is void.

The optional intrusive counting support has been dropped as it exposes too much
implementation details and doesn't interact well with weak_ptr.
The current implementation uses a different mechanism,
enable_shared_from_this, to solve the "shared_ptr from
this" problem.]

Requirements:p must be convertible to T *. D
must be CopyConstructible. The copy constructor and destructor
of D must not throw. The expression d(p) must be
well-formed, must not invoke undefined behavior, and must not throw exceptions.
A must be an Allocator, as described in section 20.1.5 (Allocator
requirements) of the C++ Standard.

Effects: Constructs a shared_ptr that owns the pointer
p and the deleter d. The second constructor allocates
memory using a copy of a.

Postconditions:use_count() == 1 && get() == p.

Throws:std::bad_alloc, or an implementation-defined
exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, d(p) is called.

Notes: When the the time comes to delete the object pointed to by p,
the stored copy of d is invoked with the stored copy of p
as an argument.

[Custom deallocators allow a factory function returning a shared_ptr
to insulate the user from its memory allocation strategy. Since the deallocator
is not part of the type, changing the allocation strategy does not break source
or binary compatibility, and does not require a client recompilation. For
example, a "no-op" deallocator is useful when returning a shared_ptr
to a statically allocated object, and other variations allow a shared_ptr
to be used as a wrapper for another smart pointer, easing interoperability.

The support for custom deallocators does not impose significant overhead. Other
shared_ptr features still require a deallocator to be kept.

The requirement that the copy constructor of D does not throw comes from
the pass by value. If the copy constructor throws, the pointer is leaked.
Removing the requirement requires a pass by (const) reference.

The main problem with pass by reference lies in its interaction with rvalues. A
const reference may still cause a copy, and will require a const operator(). A
non-const reference won't bind to an rvalue at all. A good solution to this
problem is the rvalue reference proposed in
N1377/N1385.]

Effects: Constructs a shared_ptr that shares ownership with
r and stores a copy of the pointer stored in r.

Postconditions:use_count() == r.use_count().

Throws:bad_weak_ptr when r.use_count() == 0.

Exception safety: If an exception is thrown, the constructor has no
effect.

template<class Y> shared_ptr(std::auto_ptr<Y> & r);

Effects: Constructs a shared_ptr, as if by storing a copy of r.release().

Postconditions:use_count() == 1.

Throws:std::bad_alloc, or an implementation-defined
exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, the constructor has no
effect.

[This constructor takes a the source auto_ptr by reference and
not by value, and cannot accept auto_ptr temporaries. This is
by design, as the constructor offers the strong guarantee; an rvalue reference
would solve this problem, too.]

Notes: The use count updates caused by the temporary object construction
and destruction are not considered observable side effects, and the
implementation is free to meet the effects (and the implied guarantees) via
different means, without creating a temporary. In particular, in the example:

Returns: an unspecified value that, when used in boolean contexts, is
equivalent to get() != 0.

Throws: nothing.

Notes: This conversion operator allows shared_ptr objects to be
used in boolean contexts, like if (p && p->valid()) {}.
The actual target type is typically a pointer to a member function, avoiding
many of the implicit conversion pitfalls.

operator< is a strict weak ordering as described in section 25.3 [lib.alg.sorting]
of the C++ standard;

under the equivalence relation defined by operator<, !(a
< b) && !(b < a), two shared_ptr instances
are equivalent if and only if they share ownership or are both empty.

Throws: nothing.

Notes: Allows shared_ptr objects to be used as keys in
associative containers.

[Operator< has been preferred over a std::less
specialization for consistency and legality reasons, as std::less
is required to return the results of operator<, and many
standard algorithms use operator< instead of std::less
for comparisons when a predicate is not supplied. Composite objects, like std::pair,
also implement their operator< in terms of their contained
subobjects' operator<.

See shared_ptr_example.cpp for a
complete example program. The program builds a std::vector and std::set
of shared_ptr objects.

Note that after the containers have been populated, some of the shared_ptr
objects will have a use count of 1 rather than a use count of 2, since the set
is a std::set rather than a std::multiset, and thus does not
contain duplicate entries. Furthermore, the use count may be even higher at
various times while push_back and insert container operations are
performed. More complicated yet, the container operations may throw exceptions
under a variety of circumstances. Getting the memory management and exception
handling in this example right without a smart pointer would be a nightmare.

One common usage of shared_ptr is to implement a handle/body (also called
pimpl) idiom which avoids exposing the body (implementation) in the header
file.

The shared_ptr_example2_test.cpp
sample program includes a header file, shared_ptr_example2.hpp,
which uses a shared_ptr<> to an incomplete type to hide the
implementation. The instantiation of member functions which require a complete
type occurs in the shared_ptr_example2.cpp
implementation file. Note that there is no need for an explicit destructor.
Unlike ~scoped_ptr, ~shared_ptr does not require that T be a complete
type.

shared_ptr objects offer the same level of thread safety as
built-in types. A shared_ptr instance can be "read" (accessed
using only const operations) simultaneously by multiple threads. Different shared_ptr
instances can be "written to" (accessed using mutable operations such as operator=
or reset) simultaneosly by multiple threads (even
when these instances are copies, and share the same reference count
underneath.)

Starting with Boost release 1.33.0, shared_ptr uses a lock-free
implementation on the following platforms:

GNU GCC on x86 or x86-64;

GNU GCC on IA64;

Metrowerks CodeWarrior on PowerPC;

GNU GCC on PowerPC;

Windows.

If your program is single-threaded and does not link to any libraries that might
have used shared_ptr in its default configuration, you can
#define the macro BOOST_SP_DISABLE_THREADS on a
project-wide basis to switch to ordinary non-atomic reference count updates.

(Defining BOOST_SP_DISABLE_THREADS in some, but not all,
translation units is technically a violation of the One Definition Rule and
undefined behavior. Nevertheless, the implementation attempts to do its best to
accommodate the request to use non-atomic updates in those translation units.
No guarantees, though.)

You can define the macro BOOST_SP_USE_PTHREADS to turn off the
lock-free platform-specific implementation and fall back to the generic pthread_mutex_t-based
code.

Q. There are several variations of shared pointers, with different
tradeoffs; why does the smart pointer library supply only a single
implementation? It would be useful to be able to experiment with each type so
as to find the most suitable for the job at hand?

A. An important goal of shared_ptr is to provide a
standard shared-ownership pointer. Having a single pointer type is important
for stable library interfaces, since different shared pointers typically cannot
interoperate, i.e. a reference counted pointer (used by library A) cannot share
ownership with a linked pointer (used by library B.)

A. Parameterization discourages users. The shared_ptr template is
carefully crafted to meet common needs without extensive parameterization. Some
day a highly configurable smart pointer may be invented that is also very easy
to use and very hard to misuse. Until then, shared_ptr is the smart
pointer of choice for a wide range of applications. (Those interested in policy
based smart pointers should read
Modern C++ Design by Andrei Alexandrescu.)

Q. I am not convinced. Default parameters can be used where appropriate
to hide the complexity. Again, why not policies?

A. Template parameters affect the type. See the answer to the first
question above.

Q. Why doesn't shared_ptr use a linked list implementation?

A. A linked list implementation does not offer enough advantages to
offset the added cost of an extra pointer. See timings
page. In addition, it is expensive to make a linked list implementation thread
safe.

Q. Why doesn't shared_ptr (or any of the other Boost smart
pointers) supply an automatic conversion to T*?

A. Automatic conversion is believed to be too error prone.

Q. Why does shared_ptr supply use_count()?

A. As an aid to writing test cases and debugging displays. One of the
progenitors had use_count(), and it was useful in tracking down bugs in a
complex project that turned out to have cyclic-dependencies.

Q. Why doesn't shared_ptr specify complexity requirements?

A. Because complexity requirements limit implementors and complicate the
specification without apparent benefit to shared_ptr users. For example,
error-checking implementations might become non-conforming if they had to meet
stringent complexity requirements.

Q. Why doesn't shared_ptr provide a release() function?

A.shared_ptr cannot give away ownership unless it's unique()
because the other copy will still destroy the object.

Furthermore, the pointer returned by release() would be difficult
to deallocate reliably, as the source shared_ptr could have been created
with a custom deleter.

Q. Why is operator->() const, but its return value is a
non-const pointer to the element type?

A. Shallow copy pointers, including raw pointers, typically don't
propagate constness. It makes little sense for them to do so, as you can always
obtain a non-const pointer from a const one and then proceed to modify the
object through it.shared_ptr is "as close to raw pointers as possible
but no closer".