Requires:: `Y` must be a complete type. The expression `delete[] p`, when `T` is an array type, or `delete p`, when `T` is not an array type,
must be well-formed, well-defined, and not throw exceptions. When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]`
must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`.
Effects:: When `T` is not an array type, constructs a `shared_ptr` that owns the pointer `p`. Otherwise, constructs a `shared_ptr` that owns `p` and
a deleter of an unspecified type that calls `delete[] p`.
Postconditions:: `use_count() == 1 && get() == p`. If `T` is not an array type and `p` is unambiguously convertible to `enable_shared_from_this<V>*`
for some `V`, `p\->shared_from_this()` returns a copy of `*this`.
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 calls `delete[] p`, when `T` is an array type, or `delete p`, when `T` is not an array type.
NOTE: `p` must be a pointer to an object that was allocated via a {cpp} `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.
NOTE: This constructor is 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`.
### constructors taking a deleter
```
template<class Y, class D> shared_ptr(Y * p, D d);
```
```
template<class Y, class D, class A> shared_ptr(Y * p, D d, A a);
```
```
template<class D> shared_ptr(std::nullptr_t p, D d);
```
```
template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a);
```
[none]
* {blank}
+
Requires:: `D` must be `CopyConstructible`. The copy constructor and destructor of `D` must not throw. The expression `d(p)` must be well-formed, well-defined,
and not throw exceptions. `A` must be an `Allocator`, as described in section Allocator Requirements [allocator.requirements] of the {cpp} Standard.
When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]` must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`.
Effects:: Constructs a `shared_ptr` that owns the pointer `p` and the deleter `d`. The constructors taking an allocator a allocate memory using a copy of `a`.
Postconditions:: `use_count() == 1 && get() == p`. If `T` is not an array type and `p` is unambiguously convertible to `enable_shared_from_this<V>*` for some `V`,
`p\->shared_from_this()` returns a copy of `*this`.
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.
NOTE: 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.
NOTE: 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.
NOTE: The requirement that the copy constructor of `D` does not throw comes from the pass by value. If the copy constructor throws, the pointer would leak.
D * get_deleter(shared_ptr<T> const & p) noexcept;
```
[none]
* {blank}
+
Returns:: If `*this` owns a deleter `d` of type (cv-unqualified) `D`, returns `&d`; otherwise returns 0.
## Example
See link:../../example/shared_ptr_example.cpp[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.
## Handle/Body Idiom
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 link:../../example/shared_ptr_example2_test.cpp[shared_ptr_example2_test.cpp] sample program includes a header file,
link:../../example/shared_ptr_example2.hpp[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 link:../../example/shared_ptr_example2.cpp[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.
## Thread Safety
`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`)
simultaneously by multiple threads (even when these instances are copies, and share the same reference count underneath.)
Any other simultaneous accesses result in undefined behavior.
Examples:
```
shared_ptr<int> p(new int(42));
```
.Reading a `shared_ptr` from two threads
```
// thread A
shared_ptr<int> p2(p); // reads p
// thread B
shared_ptr<int> p3(p); // OK, multiple reads are safe
```
.Writing different `shared_ptr` instances from two threads
```
// thread A
p.reset(new int(1912)); // writes p
// thread B
p2.reset(); // OK, writes p2
```
.Reading and writing a `shared_ptr` from two threads
Starting with Boost release 1.33.0, `shared_ptr` uses a lock-free implementation on most common platforms.
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.
## Frequently Asked Questions
[qanda]
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?::
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.)
Why doesn't shared_ptr have template parameters supplying traits or policies to allow extensive user customization?::
Parameterization discourages users. The `shared_ptr` template is carefully crafted to meet common needs without extensive parameterization.
I am not convinced. Default parameters can be used where appropriate to hide the complexity. Again, why not policies?::
Template parameters affect the type. See the answer to the first question above.
Why doesn't `shared_ptr` use a linked list implementation?::
A linked list implementation does not offer enough advantages to offset the added cost of an extra pointer. In addition, it is expensive to
make a linked list implementation thread safe.
Why doesn't `shared_ptr` (or any of the other Boost smart pointers) supply an automatic conversion to T*?::
Automatic conversion is believed to be too error prone.
Why does `shared_ptr` supply `use_count()`?::
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.
// Who owns p now? b will still call delete on it in its destructor.
```
+
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, or may have pointed to an object of a different type.
Why is `operator\->()` const, but its return value is a non-const pointer to the element type?::
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".
