1//// 2Copyright 1999 Greg Colvin and Beman Dawes 3Copyright 2002 Darin Adler 4Copyright 2002-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[#shared_ptr] 13# shared_ptr: Shared Ownership 14:toc: 15:toc-title: 16:idprefix: shared_ptr_ 17 18## Description 19 20The `shared_ptr` class template stores a pointer to a dynamically allocated object, typically with a {cpp} `new`-expression. 21The object pointed to is guaranteed to be deleted when the last `shared_ptr` pointing to it is destroyed or reset. 22 23.Using shared_ptr 24``` 25shared_ptr<X> p1( new X ); 26shared_ptr<void> p2( new int(5) ); 27``` 28 29`shared_ptr` deletes the exact pointer that has been passed at construction time, complete with its original type, regardless 30of the template parameter. In the second example above, when `p2` is destroyed or reset, it will call `delete` on the original 31`int*` that has been passed to the constructor, even though `p2` itself is of type `shared_ptr<void>` and stores a pointer of 32type `void*`. 33 34Every `shared_ptr` meets the `CopyConstructible`, `MoveConstructible`, `CopyAssignable` and `MoveAssignable` requirements of the 35{cpp} Standard Library, and can be used in standard library containers. Comparison operators are supplied so that `shared_ptr` 36works with the standard library's associative containers. 37 38Because the implementation uses reference counting, cycles of `shared_ptr` instances will not be reclaimed. For example, if `main()` 39holds a `shared_ptr` to `A`, which directly or indirectly holds a `shared_ptr` back to `A`, `A`'s use count will be 2. Destruction 40of the original `shared_ptr` will leave `A` dangling with a use count of 1. Use `<<weak_ptr,weak_ptr>>` to "break cycles." 41 42The class template is parameterized on `T`, the type of the object pointed to. `shared_ptr` and most of its member functions place 43no requirements on `T`; it is allowed to be an incomplete type, or `void`. Member functions that do place additional requirements 44(constructors, `reset`) are explicitly documented below. 45 46`shared_ptr<T>` can be implicitly converted to `shared_ptr<U>` whenever `T*` can be implicitly converted to `U*`. In particular, 47`shared_ptr<T>` is implicitly convertible to `shared_ptr<T const>`, to `shared_ptr<U>` where `U` is an accessible base of `T`, 48and to `shared_ptr<void>`. 49 50`shared_ptr` is now part of the C++11 Standard, as `std::shared_ptr`. 51 52Starting with Boost release 1.53, `shared_ptr` can be used to hold a pointer to a dynamically allocated array. This is accomplished 53by using an array type (`T[]` or `T[N]`) as the template parameter. There is almost no difference between using an unsized array, 54`T[]`, and a sized array, `T[N]`; the latter just enables `operator[]` to perform a range check on the index. 55 56.Using shared_ptr with arrays 57``` 58shared_ptr<double[1024]> p1( new double[1024] ); 59shared_ptr<double[]> p2( new double[n] ); 60``` 61 62## Best Practices 63 64A simple guideline that nearly eliminates the possibility of memory leaks is: always use a named smart pointer variable to hold the result 65of `new`. Every occurence of the `new` keyword in the code should have the form: 66 67 shared_ptr<T> p(new Y); 68 69It is, of course, acceptable to use another smart pointer in place of `shared_ptr` above; having `T` and `Y` be the same type, or passing 70arguments to the constructor of `Y` is also OK. 71 72If you observe this guideline, it naturally follows that you will have no explicit `delete` statements; `try`/`catch` constructs will be rare. 73 74Avoid using unnamed `shared_ptr` temporaries to save typing; to see why this is dangerous, consider this example: 75 76.Exception-safe and -unsafe use of shared_ptr 77``` 78void f(shared_ptr<int>, int); 79int g(); 80 81void ok() 82{ 83 shared_ptr<int> p( new int(2) ); 84 f( p, g() ); 85} 86 87void bad() 88{ 89 f( shared_ptr<int>( new int(2) ), g() ); 90} 91``` 92 93The function `ok` follows the guideline to the letter, whereas `bad` constructs the temporary `shared_ptr` in place, admitting the possibility of 94a memory leak. Since function arguments are evaluated in unspecified order, it is possible for `new int(2)` to be evaluated first, `g()` second, 95and we may never get to the `shared_ptr` constructor if `g` throws an exception. See http://www.gotw.ca/gotw/056.htm[Herb Sutter's treatment] of 96the issue for more information. 97 98The exception safety problem described above may also be eliminated by using the `<<make_shared,make_shared>>` or `allocate_shared` factory 99functions defined in `<boost/smart_ptr/make_shared.hpp>`. These factory functions also provide an efficiency benefit by consolidating allocations. 100 101## Synopsis 102 103`shared_ptr` is defined in `<boost/smart_ptr/shared_ptr.hpp>`. 104 105``` 106namespace boost { 107 108 class bad_weak_ptr: public std::exception; 109 110 template<class T> class weak_ptr; 111 112 template<class T> class shared_ptr { 113 public: 114 115 typedef /*see below*/ element_type; 116 117 constexpr shared_ptr() noexcept; 118 constexpr shared_ptr(std::nullptr_t) noexcept; 119 120 template<class Y> explicit shared_ptr(Y * p); 121 template<class Y, class D> shared_ptr(Y * p, D d); 122 template<class Y, class D, class A> shared_ptr(Y * p, D d, A a); 123 template<class D> shared_ptr(std::nullptr_t p, D d); 124 template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a); 125 126 ~shared_ptr() noexcept; 127 128 shared_ptr(shared_ptr const & r) noexcept; 129 template<class Y> shared_ptr(shared_ptr<Y> const & r) noexcept; 130 131 shared_ptr(shared_ptr && r) noexcept; 132 template<class Y> shared_ptr(shared_ptr<Y> && r) noexcept; 133 134 template<class Y> shared_ptr(shared_ptr<Y> const & r, element_type * p) noexcept; 135 template<class Y> shared_ptr(shared_ptr<Y> && r, element_type * p) noexcept; 136 137 template<class Y> explicit shared_ptr(weak_ptr<Y> const & r); 138 139 template<class Y> explicit shared_ptr(std::auto_ptr<Y> & r); 140 template<class Y> shared_ptr(std::auto_ptr<Y> && r); 141 142 template<class Y, class D> shared_ptr(std::unique_ptr<Y, D> && r); 143 144 shared_ptr & operator=(shared_ptr const & r) noexcept; 145 template<class Y> shared_ptr & operator=(shared_ptr<Y> const & r) noexcept; 146 147 shared_ptr & operator=(shared_ptr const && r) noexcept; 148 template<class Y> shared_ptr & operator=(shared_ptr<Y> const && r) noexcept; 149 150 template<class Y> shared_ptr & operator=(std::auto_ptr<Y> & r); 151 template<class Y> shared_ptr & operator=(std::auto_ptr<Y> && r); 152 153 template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r); 154 155 shared_ptr & operator=(std::nullptr_t) noexcept; 156 157 void reset() noexcept; 158 159 template<class Y> void reset(Y * p); 160 template<class Y, class D> void reset(Y * p, D d); 161 template<class Y, class D, class A> void reset(Y * p, D d, A a); 162 163 template<class Y> void reset(shared_ptr<Y> const & r, element_type * p) noexcept; 164 template<class Y> void reset(shared_ptr<Y> && r, element_type * p) noexcept; 165 166 T & operator*() const noexcept; // only valid when T is not an array type 167 T * operator->() const noexcept; // only valid when T is not an array type 168 169 // only valid when T is an array type 170 element_type & operator[](std::ptrdiff_t i) const noexcept; 171 172 element_type * get() const noexcept; 173 174 bool unique() const noexcept; 175 long use_count() const noexcept; 176 177 explicit operator bool() const noexcept; 178 179 void swap(shared_ptr & b) noexcept; 180 181 template<class Y> bool owner_before(shared_ptr<Y> const & r) const noexcept; 182 template<class Y> bool owner_before(weak_ptr<Y> const & r) const noexcept; 183 184 template<class Y> bool owner_equals(shared_ptr<Y> const & r) const noexcept; 185 template<class Y> bool owner_equals(weak_ptr<Y> const & r) const noexcept; 186 187 std::size_t owner_hash_value() const noexcept; 188 }; 189 190 template<class T, class U> 191 bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 192 193 template<class T, class U> 194 bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 195 196 template<class T, class U> 197 bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 198 199 template<class T> bool operator==(shared_ptr<T> const & p, std::nullptr_t) noexcept; 200 template<class T> bool operator==(std::nullptr_t, shared_ptr<T> const & p) noexcept; 201 202 template<class T> bool operator!=(shared_ptr<T> const & p, std::nullptr_t) noexcept; 203 template<class T> bool operator!=(std::nullptr_t, shared_ptr<T> const & p) noexcept; 204 205 template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b) noexcept; 206 207 template<class T> 208 typename shared_ptr<T>::element_type * 209 get_pointer(shared_ptr<T> const & p) noexcept; 210 211 template<class T, class U> 212 shared_ptr<T> static_pointer_cast(shared_ptr<U> const & r) noexcept; 213 214 template<class T, class U> 215 shared_ptr<T> const_pointer_cast(shared_ptr<U> const & r) noexcept; 216 217 template<class T, class U> 218 shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const & r) noexcept; 219 220 template<class T, class U> 221 shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U> const & r) noexcept; 222 223 template<class E, class T, class Y> 224 std::basic_ostream<E, T> & 225 operator<< (std::basic_ostream<E, T> & os, shared_ptr<Y> const & p); 226 227 template<class D, class T> D * get_deleter(shared_ptr<T> const & p) noexcept; 228 229 template<class T> bool atomic_is_lock_free( shared_ptr<T> const * p ) noexcept; 230 231 template<class T> shared_ptr<T> atomic_load( shared_ptr<T> const * p ) noexcept; 232 template<class T> 233 shared_ptr<T> atomic_load_explicit( shared_ptr<T> const * p, int ) noexcept; 234 235 template<class T> 236 void atomic_store( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 237 template<class T> 238 void atomic_store_explicit( shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 239 240 template<class T> 241 shared_ptr<T> atomic_exchange( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 242 template<class T> 243 shared_ptr<T> atomic_exchange_explicit( 244 shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 245 246 template<class T> 247 bool atomic_compare_exchange( 248 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w ) noexcept; 249 template<class T> 250 bool atomic_compare_exchange_explicit( 251 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w, int, int ) noexcept; 252} 253``` 254 255## Members 256 257### element_type 258``` 259typedef ... element_type; 260``` 261`element_type` is `T` when `T` is not an array type, and `U` when `T` is `U[]` or `U[N]`. 262 263### default constructor 264``` 265constexpr shared_ptr() noexcept; 266``` 267``` 268constexpr shared_ptr(std::nullptr_t) noexcept; 269``` 270[none] 271* {blank} 272+ 273Effects:: Constructs an empty `shared_ptr`. 274Postconditions:: `use_count() == 0 && get() == 0`. 275 276### pointer constructor 277``` 278template<class Y> explicit shared_ptr(Y * p); 279``` 280[none] 281* {blank} 282+ 283Requires:: `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, 284 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(\*)[]` 285 must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`. 286 287Effects:: 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 288 a deleter of an unspecified type that calls `delete[] p`. 289 290Postconditions:: `use_count() == 1 && get() == p`. If `T` is not an array type and `p` is unambiguously convertible to `enable_shared_from_this<V>*` 291 for some `V`, `p\->shared_from_this()` returns a copy of `*this`. 292 293Throws:: `std::bad_alloc`, or an implementation-defined exception when a resource other than memory could not be obtained. 294 295Exception 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. 296 297NOTE: `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` 298is 0; invoking `delete` on a pointer that has a value of 0 is harmless. 299 300NOTE: This constructor is a template in order to remember the actual pointer type passed. The destructor will call delete with the same pointer, complete 301with its original type, even when `T` does not have a virtual destructor, or is `void`. 302 303### constructors taking a deleter 304``` 305template<class Y, class D> shared_ptr(Y * p, D d); 306``` 307``` 308template<class Y, class D, class A> shared_ptr(Y * p, D d, A a); 309``` 310``` 311template<class D> shared_ptr(std::nullptr_t p, D d); 312``` 313``` 314template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a); 315``` 316[none] 317* {blank} 318+ 319Requires:: `D` must be `CopyConstructible`. The copy constructor and destructor of `D` must not throw. The expression `d(p)` must be well-formed, well-defined, 320 and not throw exceptions. `A` must be an `Allocator`, as described in section Allocator Requirements [allocator.requirements] of the {cpp} Standard. 321 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*`. 322 323Effects:: 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`. 324 325Postconditions:: `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`, 326 `p\->shared_from_this()` returns a copy of `*this`. 327 328Throws:: `std::bad_alloc`, or an implementation-defined exception when a resource other than memory could not be obtained. 329 330Exception safety:: If an exception is thrown, `d(p)` is called. 331 332NOTE: 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. 333 334NOTE: Custom deallocators allow a factory function returning a `shared_ptr` to insulate the user from its memory allocation strategy. Since the deallocator 335is 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, 336a "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 337for another smart pointer, easing interoperability. 338 339NOTE: 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. 340 341### copy and converting constructors 342``` 343shared_ptr(shared_ptr const & r) noexcept; 344``` 345``` 346template<class Y> shared_ptr(shared_ptr<Y> const & r) noexcept; 347``` 348[none] 349* {blank} 350+ 351Requires:: `Y*` should be convertible to `T*`. 352 353Effects:: If `r` is empty, constructs an empty `shared_ptr`; otherwise, constructs a `shared_ptr` that shares ownership with `r`. 354 355Postconditions:: `get() == r.get() && use_count() == r.use_count()`. 356 357### move constructors 358``` 359shared_ptr(shared_ptr && r) noexcept; 360``` 361``` 362template<class Y> shared_ptr(shared_ptr<Y> && r) noexcept; 363``` 364[none] 365* {blank} 366+ 367Requires:: `Y*` should be convertible to `T*`. 368 369Effects:: Move-constructs a `shared_ptr` from `r`. 370 371Postconditions:: `*this` contains the old value of `r`. `r` is empty and `r.get() == 0`. 372 373### aliasing constructor 374``` 375template<class Y> shared_ptr(shared_ptr<Y> const & r, element_type * p) noexcept; 376``` 377[none] 378* {blank} 379+ 380Effects:: Copy-constructs a `shared_ptr` from `r`, while storing `p` instead. 381 382Postconditions:: `get() == p && use_count() == r.use_count()`. 383 384### aliasing move constructor 385``` 386template<class Y> shared_ptr(shared_ptr<Y> && r, element_type * p) noexcept; 387``` 388[none] 389* {blank} 390+ 391Effects:: Move-constructs a `shared_ptr` from `r`, while storing `p` instead. 392 393Postconditions:: `get() == p` and `use_count()` equals the old count of `r`. `r` is empty and `r.get() == 0`. 394 395### weak_ptr constructor 396``` 397template<class Y> explicit shared_ptr(weak_ptr<Y> const & r); 398``` 399[none] 400* {blank} 401+ 402Requires:: `Y*` should be convertible to `T*`. 403 404Effects:: Constructs a `shared_ptr` that shares ownership with `r` and stores a copy of the pointer stored in `r`. 405 406Postconditions:: `use_count() == r.use_count()`. 407 408Throws:: `bad_weak_ptr` when `r.use_count() == 0`. 409 410Exception safety:: If an exception is thrown, the constructor has no effect. 411 412### auto_ptr constructors 413``` 414template<class Y> shared_ptr(std::auto_ptr<Y> & r); 415``` 416``` 417template<class Y> shared_ptr(std::auto_ptr<Y> && r); 418``` 419[none] 420* {blank} 421+ 422Requires:: `Y*` should be convertible to `T*`. 423 424Effects:: Constructs a `shared_ptr`, as if by storing a copy of `r.release()`. 425 426Postconditions:: `use_count() == 1`. 427 428Throws:: `std::bad_alloc`, or an implementation-defined exception when a resource other than memory could not be obtained. 429 430Exception safety:: If an exception is thrown, the constructor has no effect. 431 432### unique_ptr constructor 433``` 434template<class Y, class D> shared_ptr(std::unique_ptr<Y, D> && r); 435``` 436[none] 437* {blank} 438+ 439Requires:: `Y*` should be convertible to `T*`. 440 441Effects:: 442- When `r.get() == 0`, equivalent to `shared_ptr()`; 443- When `D` is not a reference type, equivalent to `shared_ptr(r.release(), r.get_deleter())`; 444- Otherwise, equivalent to `shared_ptr(r.release(), del)`, where `del` is a deleter that stores the reference `rd` returned 445 from `r.get_deleter()` and `del(p)` calls `rd(p)`. 446 447Throws:: `std::bad_alloc`, or an implementation-defined exception when a resource other than memory could not be obtained. 448 449Exception safety:: If an exception is thrown, the constructor has no effect. 450 451### destructor 452``` 453~shared_ptr() noexcept; 454``` 455[none] 456* {blank} 457+ 458Effects:: 459- If `*this` is empty, or shares ownership with another `shared_ptr` instance (`use_count() > 1`), there are no side effects. 460- Otherwise, if `*this` owns a pointer `p` and a deleter `d`, `d(p)` is called. 461- Otherwise, `*this` owns a pointer `p`, and `delete p` is called. 462 463### assignment 464``` 465shared_ptr & operator=(shared_ptr const & r) noexcept; 466``` 467``` 468template<class Y> shared_ptr & operator=(shared_ptr<Y> const & r) noexcept; 469``` 470``` 471template<class Y> shared_ptr & operator=(std::auto_ptr<Y> & r); 472``` 473[none] 474* {blank} 475+ 476Effects:: Equivalent to `shared_ptr(r).swap(*this)`. 477Returns:: `*this`. 478 479NOTE: The use count updates caused by the temporary object construction and destruction are not considered observable side effects, 480and the implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary. 481 482[NOTE] 483==== 484In particular, in the example: 485``` 486shared_ptr<int> p(new int); 487shared_ptr<void> q(p); 488p = p; 489q = p; 490``` 491both assignments may be no-ops. 492==== 493 494``` 495shared_ptr & operator=(shared_ptr && r) noexcept; 496``` 497``` 498template<class Y> shared_ptr & operator=(shared_ptr<Y> && r) noexcept; 499``` 500``` 501template<class Y> shared_ptr & operator=(std::auto_ptr<Y> && r); 502``` 503``` 504template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r); 505``` 506[none] 507* {blank} 508+ 509Effects:: Equivalent to `shared_ptr(std::move(r)).swap(*this)`. 510Returns:: `*this`. 511 512``` 513shared_ptr & operator=(std::nullptr_t) noexcept; 514``` 515[none] 516* {blank} 517+ 518Effects:: Equivalent to `shared_ptr().swap(*this)`. 519Returns:: `*this`. 520 521### reset 522``` 523void reset() noexcept; 524``` 525[none] 526* {blank} 527+ 528Effects:: Equivalent to `shared_ptr().swap(*this)`. 529 530``` 531template<class Y> void reset(Y * p); 532``` 533[none] 534* {blank} 535+ 536Effects:: Equivalent to `shared_ptr(p).swap(*this)`. 537 538``` 539template<class Y, class D> void reset(Y * p, D d); 540``` 541[none] 542* {blank} 543+ 544Effects:: Equivalent to `shared_ptr(p, d).swap(*this)`. 545 546``` 547template<class Y, class D, class A> void reset(Y * p, D d, A a); 548``` 549[none] 550* {blank} 551+ 552Effects:: Equivalent to `shared_ptr(p, d, a).swap(*this)`. 553 554``` 555template<class Y> void reset(shared_ptr<Y> const & r, element_type * p) noexcept; 556``` 557[none] 558* {blank} 559+ 560Effects:: Equivalent to `shared_ptr(r, p).swap(*this)`. 561 562``` 563template<class Y> void reset(shared_ptr<Y> && r, element_type * p) noexcept; 564``` 565[none] 566* {blank} 567+ 568Effects:: 569 Equivalent to `shared_ptr(std::move(r), p).swap(*this)`. 570 571### indirection 572``` 573T & operator*() const noexcept; 574``` 575[none] 576* {blank} 577+ 578Requires:: `T` should not be an array type. The stored pointer must not be 0. 579Returns:: `*get()`. 580 581``` 582T * operator->() const noexcept; 583``` 584[none] 585* {blank} 586+ 587Requires:: `T` should not be an array type. The stored pointer must not be 0. 588Returns:: `get()`. 589 590``` 591element_type & operator[](std::ptrdiff_t i) const noexcept; 592``` 593[none] 594* {blank} 595+ 596Requires:: `T` should be an array type. The stored pointer must not be 0. `i >= 0`. If `T` is `U[N]`, `i < N`. 597Returns:: `get()[i]`. 598 599### get 600 601``` 602element_type * get() const noexcept; 603``` 604[none] 605* {blank} 606+ 607Returns:: 608 The stored pointer. 609 610### unique 611``` 612bool unique() const noexcept; 613``` 614[none] 615* {blank} 616+ 617Returns:: 618 `use_count() == 1`. 619 620### use_count 621``` 622long use_count() const noexcept; 623``` 624[none] 625* {blank} 626+ 627Returns:: 628 The number of `shared_ptr` objects, `*this` included, that share ownership with `*this`, or 0 when `*this` is empty. 629 630### conversions 631``` 632explicit operator bool() const noexcept; 633``` 634[none] 635* {blank} 636+ 637Returns:: `get() != 0`. 638 639NOTE: This conversion operator allows `shared_ptr` objects to be used in boolean contexts, like `if(p && p\->valid()) {}`. 640 641NOTE: The conversion to `bool` is not merely syntactic sugar. It allows `shared_ptr` variables to be declared in conditions when using 642`dynamic_pointer_cast` or `weak_ptr::lock`. 643 644NOTE: On C++03 compilers, the return value is of an unspecified type. 645 646### swap 647``` 648void swap(shared_ptr & b) noexcept; 649``` 650[none] 651* {blank} 652+ 653Effects:: 654 Exchanges the contents of the two smart pointers. 655 656### owner_before 657``` 658template<class Y> bool owner_before(shared_ptr<Y> const & r) const noexcept; 659``` 660``` 661template<class Y> bool owner_before(weak_ptr<Y> const & r) const noexcept; 662``` 663[none] 664* {blank} 665+ 666Returns:: 667 See the description of `operator<`. 668 669### owner_equals 670``` 671template<class Y> bool owner_equals(shared_ptr<Y> const & r) const noexcept; 672``` 673``` 674template<class Y> bool owner_equals(weak_ptr<Y> const & r) const noexcept; 675``` 676[none] 677* {blank} 678+ 679Returns:: 680 `true` if and only if `*this` and `r` share ownership or are both empty. 681 682### owner_hash_value 683``` 684std::size_t owner_hash_value() const noexcept; 685``` 686[none] 687* {blank} 688+ 689Returns:: 690 An unspecified hash value such that two instances that share ownership 691 have the same hash value. 692 693## Free Functions 694 695### comparison 696``` 697template<class T, class U> 698 bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 699``` 700[none] 701* {blank} 702+ 703Returns:: `a.get() == b.get()`. 704 705``` 706template<class T, class U> 707 bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 708``` 709[none] 710* {blank} 711+ 712Returns:: `a.get() != b.get()`. 713 714``` 715template<class T> bool operator==(shared_ptr<T> const & p, std::nullptr_t) noexcept; 716``` 717``` 718template<class T> bool operator==(std::nullptr_t, shared_ptr<T> const & p) noexcept; 719``` 720[none] 721* {blank} 722+ 723Returns:: `p.get() == 0`. 724 725``` 726template<class T> bool operator!=(shared_ptr<T> const & p, std::nullptr_t) noexcept; 727``` 728``` 729template<class T> bool operator!=(std::nullptr_t, shared_ptr<T> const & p) noexcept; 730``` 731[none] 732* {blank} 733+ 734Returns:: `p.get() != 0`. 735 736``` 737template<class T, class U> 738 bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 739``` 740[none] 741* {blank} 742+ 743Returns:: An unspecified value such that 744 - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; 745 - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `shared_ptr` instances 746 are equivalent if and only if they share ownership or are both empty. 747 748NOTE: Allows `shared_ptr` objects to be used as keys in associative containers. 749 750NOTE: The rest of the comparison operators are omitted by design. 751 752### swap 753``` 754template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b) noexcept; 755``` 756[none] 757* {blank} 758+ 759Effects:: 760 Equivalent to `a.swap(b)`. 761 762### get_pointer 763``` 764template<class T> 765 typename shared_ptr<T>::element_type * 766 get_pointer(shared_ptr<T> const & p) noexcept; 767``` 768[none] 769* {blank} 770+ 771Returns:: `p.get()`. 772 773NOTE: Provided as an aid to generic programming. Used by `mem_fn`. 774 775### static_pointer_cast 776``` 777template<class T, class U> 778 shared_ptr<T> static_pointer_cast(shared_ptr<U> const & r) noexcept; 779``` 780[none] 781* {blank} 782+ 783Requires:: The expression `static_cast<T*>( (U*)0 )` must be well-formed. 784Returns:: `shared_ptr<T>( r, static_cast<typename shared_ptr<T>::element_type*>(r.get()) )`. 785 786CAUTION: The seemingly equivalent expression `shared_ptr<T>(static_cast<T*>(r.get()))` will eventually 787result in undefined behavior, attempting to delete the same object twice. 788 789### const_pointer_cast 790``` 791template<class T, class U> 792 shared_ptr<T> const_pointer_cast(shared_ptr<U> const & r) noexcept; 793``` 794[none] 795* {blank} 796+ 797Requires:: The expression `const_cast<T*>( (U*)0 )` must be well-formed. 798Returns:: `shared_ptr<T>( r, const_cast<typename shared_ptr<T>::element_type*>(r.get()) )`. 799 800### dynamic_pointer_cast 801``` 802template<class T, class U> 803 shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const & r) noexcept; 804``` 805[none] 806* {blank} 807+ 808Requires:: The expression `dynamic_cast<T*>( (U*)0 )` must be well-formed. 809Returns:: 810 - When `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` returns a nonzero value `p`, `shared_ptr<T>(r, p)`; 811 - Otherwise, `shared_ptr<T>()`. 812 813### reinterpret_pointer_cast 814``` 815template<class T, class U> 816 shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U> const & r) noexcept; 817``` 818[none] 819* {blank} 820+ 821Requires:: The expression `reinterpret_cast<T*>( (U*)0 )` must be well-formed. 822Returns:: `shared_ptr<T>( r, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()) )`. 823 824### operator<< 825``` 826template<class E, class T, class Y> 827 std::basic_ostream<E, T> & 828 operator<< (std::basic_ostream<E, T> & os, shared_ptr<Y> const & p); 829``` 830[none] 831* {blank} 832+ 833Effects:: `os << p.get();`. 834Returns:: `os`. 835 836### get_deleter 837``` 838template<class D, class T> 839 D * get_deleter(shared_ptr<T> const & p) noexcept; 840``` 841[none] 842* {blank} 843+ 844Returns:: 845 If `*this` owns a deleter `d` of type (cv-unqualified) `D`, returns `&d`; otherwise returns 0. 846 847### Atomic Access 848 849NOTE: The function in this section are atomic with respect to the first `shared_ptr` argument, 850 identified by `*p`. Concurrent access to the same `shared_ptr` instance is not a data race, if 851 done exclusively by the functions in this section. 852 853``` 854template<class T> bool atomic_is_lock_free( shared_ptr<T> const * p ) noexcept; 855``` 856[none] 857* {blank} 858+ 859Returns:: `false`. 860 861NOTE: This implementation is not lock-free. 862 863``` 864template<class T> shared_ptr<T> atomic_load( shared_ptr<T> const * p ) noexcept; 865``` 866``` 867template<class T> shared_ptr<T> atomic_load_explicit( shared_ptr<T> const * p, int ) noexcept; 868``` 869[none] 870* {blank} 871+ 872Returns:: `*p`. 873 874NOTE: The `int` argument is the `memory_order`, but this implementation does not use it, as it's lock-based 875 and therefore always sequentially consistent. 876 877``` 878template<class T> 879 void atomic_store( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 880``` 881``` 882template<class T> 883 void atomic_store_explicit( shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 884``` 885[none] 886* {blank} 887+ 888Effects:: `p\->swap(r)`. 889 890``` 891template<class T> 892 shared_ptr<T> atomic_exchange( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 893``` 894``` 895template<class T> 896 shared_ptr<T> atomic_exchange_explicit( 897 shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 898``` 899[none] 900* {blank} 901+ 902Effects:: `p\->swap(r)`. 903Returns:: The old value of `*p`. 904 905``` 906template<class T> 907 bool atomic_compare_exchange( 908 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w ) noexcept; 909``` 910``` 911template<class T> 912 bool atomic_compare_exchange_explicit( 913 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w, int, int ) noexcept; 914``` 915[none] 916* {blank} 917+ 918Effects:: If `*p` is equivalent to `*v`, assigns `w` to `*p`, otherwise assigns `*p` to `*v`. 919Returns:: `true` if `*p` was equivalent to `*v`, `false` otherwise. 920Remarks:: Two `shared_ptr` instances are equivalent if they store the same pointer value and _share ownership_. 921 922 923## Example 924 925See link:../../example/shared_ptr_example.cpp[shared_ptr_example.cpp] for a complete example program. The program builds a 926`std::vector` and `std::set` of `shared_ptr` objects. 927 928Note that after the containers have been populated, some of the `shared_ptr` objects will have a use count of 1 rather than 929a use count of 2, since the set is a `std::set` rather than a `std::multiset`, and thus does not contain duplicate entries. 930Furthermore, the use count may be even higher at various times while `push_back` and `insert` container operations are performed. 931More complicated yet, the container operations may throw exceptions under a variety of circumstances. Getting the memory management 932and exception handling in this example right without a smart pointer would be a nightmare. 933 934## Handle/Body Idiom 935 936One common usage of `shared_ptr` is to implement a handle/body (also called pimpl) idiom which avoids exposing the body (implementation) 937in the header file. 938 939The link:../../example/shared_ptr_example2_test.cpp[shared_ptr_example2_test.cpp] sample program includes a header file, 940link:../../example/shared_ptr_example2.hpp[shared_ptr_example2.hpp], which uses a `shared_ptr` to an incomplete type to hide the implementation. 941The instantiation of member functions which require a complete type occurs in the link:../../example/shared_ptr_example2.cpp[shared_ptr_example2.cpp] 942implementation 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. 943 944## Thread Safety 945 946`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) 947simultaneously by multiple threads. Different `shared_ptr` instances can be "written to" (accessed using mutable operations such as `operator=` or `reset`) 948simultaneously by multiple threads (even when these instances are copies, and share the same reference count underneath.) 949 950Any other simultaneous accesses result in undefined behavior. 951 952Examples: 953``` 954shared_ptr<int> p(new int(42)); 955``` 956 957.Reading a `shared_ptr` from two threads 958``` 959// thread A 960shared_ptr<int> p2(p); // reads p 961 962// thread B 963shared_ptr<int> p3(p); // OK, multiple reads are safe 964``` 965 966.Writing different `shared_ptr` instances from two threads 967``` 968// thread A 969p.reset(new int(1912)); // writes p 970 971// thread B 972p2.reset(); // OK, writes p2 973``` 974 975.Reading and writing a `shared_ptr` from two threads 976``` 977// thread A 978p = p3; // reads p3, writes p 979 980// thread B 981p3.reset(); // writes p3; undefined, simultaneous read/write 982``` 983 984.Reading and destroying a `shared_ptr` from two threads 985``` 986// thread A 987p3 = p2; // reads p2, writes p3 988 989// thread B 990// p2 goes out of scope: undefined, the destructor is considered a "write access" 991``` 992 993.Writing a `shared_ptr` from two threads 994``` 995// thread A 996p3.reset(new int(1)); 997 998// thread B 999p3.reset(new int(2)); // undefined, multiple writes 1000``` 1001 1002Starting with Boost release 1.33.0, `shared_ptr` uses a lock-free implementation on most common platforms. 1003 1004If your program is single-threaded and does not link to any libraries that might have used `shared_ptr` in its default configuration, 1005you can `#define` the macro `BOOST_SP_DISABLE_THREADS` on a project-wide basis to switch to ordinary non-atomic reference count updates. 1006 1007(Defining `BOOST_SP_DISABLE_THREADS` in some, but not all, translation units is technically a violation of the One Definition Rule and 1008undefined behavior. Nevertheless, the implementation attempts to do its best to accommodate the request to use non-atomic updates in those 1009translation units. No guarantees, though.) 1010 1011You can define the macro `BOOST_SP_USE_PTHREADS` to turn off the lock-free platform-specific implementation and fall back to the generic 1012`pthread_mutex_t`-based code. 1013 1014## Frequently Asked Questions 1015 1016[qanda] 1017There 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?:: 1018 1019 An important goal of `shared_ptr` is to provide a standard shared-ownership pointer. Having a single pointer type is important for stable 1020 library interfaces, since different shared pointers typically cannot interoperate, i.e. a reference counted pointer (used by library A) 1021 cannot share ownership with a linked pointer (used by library B.) 1022 1023Why doesn't shared_ptr have template parameters supplying traits or policies to allow extensive user customization?:: 1024 1025 Parameterization discourages users. The `shared_ptr` template is carefully crafted to meet common needs without extensive parameterization. 1026 1027I am not convinced. Default parameters can be used where appropriate to hide the complexity. Again, why not policies?:: 1028 1029 Template parameters affect the type. See the answer to the first question above. 1030 1031Why doesn't `shared_ptr` use a linked list implementation?:: 1032 1033 A linked list implementation does not offer enough advantages to offset the added cost of an extra pointer. In addition, it is expensive to 1034 make a linked list implementation thread safe. 1035 1036Why doesn't `shared_ptr` (or any of the other Boost smart pointers) supply an automatic conversion to T*?:: 1037 1038 Automatic conversion is believed to be too error prone. 1039 1040Why does `shared_ptr` supply `use_count()`?:: 1041 1042 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 1043 a complex project that turned out to have cyclic-dependencies. 1044 1045Why doesn't `shared_ptr` specify complexity requirements?:: 1046 1047 Because complexity requirements limit implementors and complicate the specification without apparent benefit to `shared_ptr` users. For example, 1048 error-checking implementations might become non-conforming if they had to meet stringent complexity requirements. 1049 1050Why doesn't `shared_ptr` provide a `release()` function?:: 1051 1052 `shared_ptr` cannot give away ownership unless it's `unique()` because the other copy will still destroy the object. 1053+ 1054Consider: 1055+ 1056``` 1057shared_ptr<int> a(new int); 1058shared_ptr<int> b(a); // a.use_count() == b.use_count() == 2 1059 1060int * p = a.release(); 1061 1062// Who owns p now? b will still call delete on it in its destructor. 1063``` 1064+ 1065Furthermore, the pointer returned by `release()` would be difficult to deallocate reliably, as the source `shared_ptr` could have been created with a 1066custom deleter, or may have pointed to an object of a different type. 1067 1068Why is `operator\->()` const, but its return value is a non-const pointer to the element type?:: 1069 1070 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 1071 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". 1072