libs/smart_ptr/doc/smart_ptr/introduction.adoc

   1 ////
   2 Copyright 1999 Greg Colvin and Beman Dawes
   3 Copyright 2002 Darin Adler
   4 Copyright 2017 Peter Dimov
   5
   6 Distributed under the Boost Software License, Version 1.0.
   7
   8 See accompanying file LICENSE_1_0.txt or copy at
   9 http://www.boost.org/LICENSE_1_0.txt
  10 ////
  11
  12 [#introduction]
  13 # Introduction
  14 :toc:
  15 :toc-title:
  16 :idprefix: intro_
  17
  18 Smart pointers are objects which store pointers to dynamically allocated (heap) objects.
  19 They behave much like built-in {cpp} pointers except that they automatically delete the object
  20 pointed to at the appropriate time. Smart pointers are particularly useful in the face of
  21 exceptions as they ensure proper destruction of dynamically allocated objects. They can also be
  22 used to keep track of dynamically allocated objects shared by multiple owners.
  23
  24 Conceptually, smart pointers are seen as owning the object pointed to, and thus responsible for
  25 deletion of the object when it is no longer needed. As such, they are examples of the "resource
  26 acquisition is initialization" idiom described in Bjarne Stroustrup's "The C++ Programming Language",
  27 3rd edition, Section 14.4, Resource Management.
  28
  29 This 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
  40 In addition, the library contains the following supporting utility functions and classes:
  41
  42 * `<<make_shared,make_shared>>`, a factory function for creating objects that returns 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 * `<<pointer_to_other,pointer_to_other>>`, a helper trait for converting one smart pointer type to another;
  47 * `<<pointer_cast,static_pointer_cast>>` and companions, generic smart pointer casts;
  48 * `<<intrusive_ref_counter,intrusive_ref_counter>>`, a helper base class containing a reference count.
  49 * `<<atomic_shared_ptr,atomic_shared_ptr>>`, a helper class implementing the interface of `std::atomic` for a value of type `shared_ptr`.
  50
  51 As a general rule, the destructor or `operator delete` for an object managed by pointers in the library
  52 are not allowed to throw exceptions.