Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Smart Pointers

Introduction

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.

scoped_ptr	<boost/scoped_ptr.hpp>	Simple sole ownership of single objects. Noncopyable.
scoped_array	<boost/scoped_array.hpp>	Simple sole ownership of arrays. Noncopyable.
shared_ptr	<boost/shared_ptr.hpp>	Object ownership shared among multiple pointers.
shared_array	<boost/shared_array.hpp>	Array ownership shared among multiple pointers.
weak_ptr	<boost/weak_ptr.hpp>	Non-owning observers of an object owned by shared_ptr.
intrusive_ptr	<boost/intrusive_ptr.hpp>	Shared ownership of objects with an embedded reference count.

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.

Additionally, the smart pointer library provides efficient factory functions for creating smart pointer objects:

make_shared, allocate_shared for objects	<boost/make_shared.hpp>	Efficient creation of `shared_ptr` objects.
make_shared, allocate_shared for arrays	<boost/make_shared.hpp>	Efficient creation of `shared_ptr` arrays.
make_unique	<boost/make_unique.hpp>	Creation of `unique_ptr` objects and arrays.

A page on compatibility with older versions of the Boost smart pointer library describes some of the changes since earlier versions of the smart pointer implementation.

A page on smart pointer timings will be of interest to those curious about performance issues.

Common Requirements

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.

Exception Safety

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.

Exception-specifications

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.

History and Acknowledgements

February 2014. Glen Fernandes updated overloads of make_shared and allocate_shared to conform to the specification in C++ standard paper [D&F-14], and implemented make_unique for arrays and objects. Peter Dimov and Glen Fernandes updated the scalar and array implementations, respectively, to resolve C++ standard library defect 2070.

November 2012. Glen Fernandes provided implementations of make_shared and allocate_shared for arrays. They achieve a single allocation for an array that can be initialized with constructor arguments or initializer lists as well as overloads for default initialization and no value initialization. See the make_shared and allocate_shared for arrays page for more information.

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 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.

November 1999. Darin Adler provided operator ==, operator !=, and std::swap and std::less specializations for shared types.

September 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap

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:

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.

References

[E&D-94] John R. Ellis & David L. Detlefs, Safe, Efficient Garbage Collection for C++, Usenix Proceedings, February, 1994. This paper includes an extensive discussion of weak pointers and an extensive bibliography.

Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. Distributed under the Boost Software License, Version 1.0. See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt.