Smart Pointers

Introduction
Common Requirements
Exception Safety
Exception-specifications

Introduction

Smart pointers are objects that 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.

The smart pointer library provides five smart pointer class templates:

These templates are designed to complement the std::auto_ptr template.

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.

A page on smart pointer programming techniques lists some advanced applications of shared_ptr and weak_ptr.

Common Requirements

The smart pointer class templates have a template parameter, T, that 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 the point 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: 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 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.

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

Exception Safety

Several functions in the 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 is thrown only by functions which are explicitly documented as possibly throwing std::bad_alloc.

Exception-specifications

Exception-specifications are not used; see exception-specification rationale.

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.