1//// 2Copyright 1999 Greg Colvin and Beman Dawes 3Copyright 2002 Darin Adler 4Copyright 2017 Peter Dimov 5 6Distributed under the Boost Software License, Version 1.0. 7 8See accompanying file LICENSE_1_0.txt or copy at 9http://www.boost.org/LICENSE_1_0.txt 10//// 11 12[#introduction] 13# Introduction 14:toc: 15:toc-title: 16:idprefix: intro_ 17 18Smart pointers are objects which store pointers to dynamically allocated (heap) objects. 19They behave much like built-in {cpp} pointers except that they automatically delete the object 20pointed to at the appropriate time. Smart pointers are particularly useful in the face of 21exceptions as they ensure proper destruction of dynamically allocated objects. They can also be 22used to keep track of dynamically allocated objects shared by multiple owners. 23 24Conceptually, smart pointers are seen as owning the object pointed to, and thus responsible for 25deletion of the object when it is no longer needed. As such, they are examples of the "resource 26acquisition is initialization" idiom described in Bjarne Stroustrup's "The C++ Programming Language", 273rd edition, Section 14.4, Resource Management. 28 29This library provides six smart pointer class templates: 30 31* `<<scoped_ptr,scoped_ptr>>`, used to contain ownership of a dynamically allocated object to the current scope; 32* `<<scoped_array,scoped_array>>`, which provides scoped ownership for a dynamically allocated array; 33* `<<shared_ptr,shared_ptr>>`, a versatile tool for managing shared ownership of an object or array; 34* `<<weak_ptr,weak_ptr>>`, a non-owning observer to a `shared_ptr`-managed object that can be promoted temporarily to `shared_ptr`; 35* `<<intrusive_ptr,intrusive_ptr>>`, a pointer to objects with an embedded reference count; 36* `<<local_shared_ptr,local_shared_ptr>>`, providing shared ownership within a single thread. 37 38`shared_ptr` and `weak_ptr` are part of the {cpp} standard since its 2011 iteration. 39 40In addition, the library contains the following supporting utility functions and classes: 41 42* `<<make_shared,make_shared>>` and `allocate_shared`, factory functions for creating objects that return a `shared_ptr`; 43* `<<make_unique,make_unique>>`, a factory function returning `std::unique_ptr`; 44* `<<allocate_unique,allocate_unique>>`, a factory function for creating objects using an allocator that returns a `std::unique_ptr`; 45* `<<enable_shared_from_this,enable_shared_from_this>>`, a helper base class that enables the acquisition of a `shared_ptr` pointing to `this`; 46* `<<enable_shared_from,enable_shared_from>>`, a newer and better replacement for `enable_shared_from_this`; 47* `<<pointer_to_other,pointer_to_other>>`, a helper trait for converting one smart pointer type to another; 48* `<<pointer_cast,static_pointer_cast>>` and companions, generic smart pointer casts; 49* `<<intrusive_ref_counter,intrusive_ref_counter>>`, a helper base class containing a reference count. 50* `<<atomic_shared_ptr,atomic_shared_ptr>>`, a helper class implementing the interface of `std::atomic` for a value of type `shared_ptr`. 51 52As a general rule, the destructor or `operator delete` for an object managed by pointers in the library 53are not allowed to throw exceptions. 54