23 General utilities library [utilities]

23.11 Smart pointers [smartptr]

23.11.2 Shared-ownership pointers [util.smartptr]

23.11.2.1 Class bad_­weak_­ptr [util.smartptr.weak.bad]

namespace std {
  class bad_weak_ptr : public exception {
  public:
    bad_weak_ptr() noexcept;
  };
}
1
#

An exception of type bad_­weak_­ptr is thrown by the shared_­ptr constructor taking a weak_­ptr.

bad_weak_ptr() noexcept;

2
#

Postconditions: what() returns an implementation-defined ntbs.

23.11.2.2 Class template shared_­ptr [util.smartptr.shared]

1
#

The shared_­ptr class template stores a pointer, usually obtained via new. shared_­ptr implements semantics of shared ownership; the last remaining owner of the pointer is responsible for destroying the object, or otherwise releasing the resources associated with the stored pointer. A shared_­ptr is said to be empty if it does not own a pointer.

namespace std {
  template<class T> class shared_ptr {
  public:
    using element_type = remove_extent_t<T>;
    using weak_type    = weak_ptr<T>;

    // [util.smartptr.shared.const], constructors
    constexpr shared_ptr() noexcept;
    template<class Y> explicit shared_ptr(Y* p);
    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(nullptr_t p, D d);
    template <class D, class A> shared_ptr(nullptr_t p, D d, A a);
    template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
    shared_ptr(const shared_ptr& r) noexcept;
    template<class Y> shared_ptr(const shared_ptr<Y>& r) noexcept;
    shared_ptr(shared_ptr&& r) noexcept;
    template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;
    template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
    template <class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);
    constexpr shared_ptr(nullptr_t) noexcept : shared_ptr() { }

    // [util.smartptr.shared.dest], destructor
    ~shared_ptr();

    // [util.smartptr.shared.assign], assignment
    shared_ptr& operator=(const shared_ptr& r) noexcept;
    template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
    shared_ptr& operator=(shared_ptr&& r) noexcept;
    template<class Y> shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
    template <class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);

    // [util.smartptr.shared.mod], modifiers
    void swap(shared_ptr& r) noexcept;
    void reset() noexcept;
    template<class Y> void reset(Y* p);
    template<class Y, class D> void reset(Y* p, D d);
    template<class Y, class D, class A> void reset(Y* p, D d, A a);

    // [util.smartptr.shared.obs], observers
    element_type* get() const noexcept;
    T& operator*() const noexcept;
    T* operator->() const noexcept;
    element_type& operator[](ptrdiff_t i) const;
    long use_count() const noexcept;
    explicit operator bool() const noexcept;
    template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
    template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
  };

  template<class T> shared_ptr(weak_ptr<T>) -> shared_ptr<T>;
  template<class T, class D> shared_ptr(unique_ptr<T, D>) -> shared_ptr<T>;

  // [util.smartptr.shared.create], shared_­ptr creation
  template<class T, class... Args>
    shared_ptr<T> make_shared(Args&&... args);
  template<class T, class A, class... Args>
    shared_ptr<T> allocate_shared(const A& a, Args&&... args);

  // [util.smartptr.shared.cmp], shared_­ptr comparisons
  template<class T, class U>
    bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    bool operator!=(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    bool operator<(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    bool operator>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    bool operator<=(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
  template<class T, class U>
    bool operator>=(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;

  template <class T>
    bool operator==(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator==(nullptr_t, const shared_ptr<T>& b) noexcept;
  template <class T>
    bool operator!=(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator!=(nullptr_t, const shared_ptr<T>& b) noexcept;
  template <class T>
    bool operator<(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator<(nullptr_t, const shared_ptr<T>& b) noexcept;
  template <class T>
    bool operator<=(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator<=(nullptr_t, const shared_ptr<T>& b) noexcept;
  template <class T>
    bool operator>(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator>(nullptr_t, const shared_ptr<T>& b) noexcept;
  template <class T>
    bool operator>=(const shared_ptr<T>& a, nullptr_t) noexcept;
  template <class T>
    bool operator>=(nullptr_t, const shared_ptr<T>& b) noexcept;

  // [util.smartptr.shared.spec], shared_­ptr specialized algorithms
  template<class T>
    void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;

  // [util.smartptr.shared.cast], shared_­ptr casts
  template<class T, class U>
    shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;
  template<class T, class U>
    shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;

  // [util.smartptr.getdeleter], shared_­ptr get_­deleter
  template<class D, class T>
    D* get_deleter(const shared_ptr<T>& p) noexcept;

  // [util.smartptr.shared.io], shared_­ptr I/O
  template<class E, class T, class Y>
    basic_ostream<E, T>& operator<< (basic_ostream<E, T>& os, const shared_ptr<Y>& p);
}
2
#

Specializations of shared_­ptr shall be CopyConstructible, CopyAssignable, and LessThanComparable, allowing their use in standard containers. Specializations of shared_­ptr shall be contextually convertible to bool, allowing their use in boolean expressions and declarations in conditions. The template parameter T of shared_­ptr may be an incomplete type.

3
#

[ Example: 

if (shared_ptr<X> px = dynamic_pointer_cast<X>(py)) {
  // do something with px
}

 — end example ]

4
#

For purposes of determining the presence of a data race, member functions shall access and modify only the shared_­ptr and weak_­ptr objects themselves and not objects they refer to. Changes in use_­count() do not reflect modifications that can introduce data races.

5
#

For the purposes of subclause [util.smartptr], a pointer type Y* is said to be compatible with a pointer type T* when either Y* is convertible to T* or Y is U[N] and T is cv U[].

23.11.2.2.1 shared_­ptr constructors [util.smartptr.shared.const]

1
#

In the constructor definitions below, enables shared_­from_­this with p, for a pointer p of type Y*, means that if Y has an unambiguous and accessible base class that is a specialization of enable_­shared_­from_­this, then remove_­cv_­t<Y>* shall be implicitly convertible to T* and the constructor evaluates the statement: 

if (p != nullptr && p->weak_this.expired())
  p->weak_this = shared_ptr<remove_cv_t<Y>>(*this, const_cast<remove_cv_t<Y>*>(p));

The assignment to the weak_­this member is not atomic and conflicts with any potentially concurrent access to the same object ([intro.multithread]).

constexpr shared_ptr() noexcept;

2
#

Effects: Constructs an empty shared_­ptr object.

3
#

Postconditions: use_­count() == 0 && get() == nullptr.

template<class Y> explicit shared_ptr(Y* p);

4
#

Requires: Y shall be a complete type. The expression delete[] p, when T is an array type, or delete p, when T is not an array type, shall have well-defined behavior, and shall not throw exceptions.

5
#

Effects: When T is not an array type, constructs a shared_­ptr object that owns the pointer p. Otherwise, constructs a shared_­ptr that owns p and a deleter of an unspecified type that calls delete[] p. When T is not an array type, enables shared_­from_­this with p. If an exception is thrown, delete p is called when T is not an array type, delete[] p otherwise.

6
#

Postconditions: use_­count() == 1 && get() == p.

7
#

Throws: bad_­alloc, or an implementation-defined exception when a resource other than memory could not be obtained.

8
#

Remarks: When T is an array type, this constructor shall not participate in overload resolution unless the expression delete[] p is well-formed and either T is U[N] and Y(*)[N] is convertible to T*, or T is U[] and Y(*)[] is convertible to T*. When T is not an array type, this constructor shall not participate in overload resolution unless the expression delete p is well-formed and Y* is convertible to T*.

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(nullptr_t p, D d); template <class D, class A> shared_ptr(nullptr_t p, D d, A a);

9
#

Requires: Construction of d and a deleter of type D initialized with std​::​move(d) shall not throw exceptions. The expression d(p) shall have well-defined behavior and shall not throw exceptions. A shall be an allocator ([allocator.requirements]).

10
#

Effects: Constructs a shared_­ptr object that owns the object p and the deleter d. When T is not an array type, the first and second constructors enable shared_­from_­this with p. The second and fourth constructors shall use a copy of a to allocate memory for internal use. If an exception is thrown, d(p) is called.

11
#

Postconditions: use_­count() == 1 && get() == p.

12
#

Throws: bad_­alloc, or an implementation-defined exception when a resource other than memory could not be obtained.

13
#

Remarks: When T is an array type, this constructor shall not participate in overload resolution unless is_­move_­constructible_­v<D> is true, the expression d(p) is well-formed, and either T is U[N] and Y(*)[N] is convertible to T*, or T is U[] and Y(*)[] is convertible to T*. When T is not an array type, this constructor shall not participate in overload resolution unless is_­move_­constructible_­v<D> is true, the expression d(p) is well-formed, and Y* is convertible to T*.

template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;

14
#

Effects: Constructs a shared_­ptr instance that stores p and shares ownership with r.

15
#

Postconditions: get() == p && use_­count() == r.use_­count().

16
#

[ Note: To avoid the possibility of a dangling pointer, the user of this constructor must ensure that p remains valid at least until the ownership group of r is destroyed.  — end note ]

17
#

[ Note: This constructor allows creation of an empty shared_­ptr instance with a non-null stored pointer.  — end note ]

shared_ptr(const shared_ptr& r) noexcept; template<class Y> shared_ptr(const shared_ptr<Y>& r) noexcept;

18
#

Remarks: The second constructor shall not participate in overload resolution unless Y* is compatible with T*.

19
#

Effects: If r is empty, constructs an empty shared_­ptr object; otherwise, constructs a shared_­ptr object that shares ownership with r.

20
#

Postconditions: get() == r.get() && use_­count() == r.use_­count().

shared_ptr(shared_ptr&& r) noexcept; template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;

21
#

Remarks: The second constructor shall not participate in overload resolution unless Y* is compatible with T*.

22
#

Effects: Move constructs a shared_­ptr instance from r.

23
#

Postconditions: *this shall contain the old value of r. r shall be empty. r.get() == nullptr.

template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);

24
#

Effects: Constructs a shared_­ptr object that shares ownership with r and stores a copy of the pointer stored in r. If an exception is thrown, the constructor has no effect.

25
#

Postconditions: use_­count() == r.use_­count().

26
#

Throws: bad_­weak_­ptr when r.expired().

27
#

Remarks: This constructor shall not participate in overload resolution unless Y* is compatible with T*.

template <class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);

28
#

Remarks: This constructor shall not participate in overload resolution unless Y* is compatible with T* and unique_­ptr<Y, D>​::​pointer is convertible to element_­type*.

29
#

Effects: If r.get() == nullptr, equivalent to shared_­ptr(). Otherwise, if D is not a reference type, equivalent to shared_­ptr(r.release(), r.get_­deleter()). Otherwise, equivalent to shared_­ptr(r.release(), ref(r.get_­deleter())). If an exception is thrown, the constructor has no effect.

23.11.2.2.2 shared_­ptr destructor [util.smartptr.shared.dest]

~shared_ptr();

1
#

Effects:

  • (1.1)

    If *this is empty or shares ownership with another shared_­ptr instance (use_­count() > 1), there are no side effects.

  • (1.2)

    Otherwise, if *this owns an object p and a deleter d, d(p) is called.

  • (1.3)

    Otherwise, *this owns a pointer p, and delete p is called.

2
#

[ Note: Since the destruction of *this decreases the number of instances that share ownership with *this by one, after *this has been destroyed all shared_­ptr instances that shared ownership with *this will report a use_­count() that is one less than its previous value.  — end note ]

23.11.2.2.3 shared_­ptr assignment [util.smartptr.shared.assign]

shared_ptr& operator=(const shared_ptr& r) noexcept; template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;

1
#

Effects: Equivalent to shared_­ptr(r).swap(*this).

2
#

Returns: *this.

3
#

[ Note: The use count updates caused by the temporary object construction and destruction are not observable side effects, so the implementation may meet the effects (and the implied guarantees) via different means, without creating a temporary. In particular, in the example: 

shared_ptr<int> p(new int);
shared_ptr<void> q(p);
p = p;
q = p;

both assignments may be no-ops.  — end note ]

shared_ptr& operator=(shared_ptr&& r) noexcept; template<class Y> shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;

4
#

Effects: Equivalent to shared_­ptr(std​::​move(r)).swap(*this).

5
#

Returns: *this.

template <class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);

6
#

Effects: Equivalent to shared_­ptr(std​::​move(r)).swap(*this).

7
#

Returns: *this.

23.11.2.2.4 shared_­ptr modifiers [util.smartptr.shared.mod]

void swap(shared_ptr& r) noexcept;

1
#

Effects: Exchanges the contents of *this and r.

void reset() noexcept;

2
#

Effects: Equivalent to shared_­ptr().swap(*this).

template<class Y> void reset(Y* p);

3
#

Effects: Equivalent to shared_­ptr(p).swap(*this).

template<class Y, class D> void reset(Y* p, D d);

4
#

Effects: Equivalent to shared_­ptr(p, d).swap(*this).

template<class Y, class D, class A> void reset(Y* p, D d, A a);

5
#

Effects: Equivalent to shared_­ptr(p, d, a).swap(*this).

23.11.2.2.5 shared_­ptr observers [util.smartptr.shared.obs]

element_type* get() const noexcept;

1
#

Returns: The stored pointer.

T& operator*() const noexcept;

2
#

Requires: get() != 0.

3
#

Returns: *get().

4
#

Remarks: When T is an array type or cv void, it is unspecified whether this member function is declared. If it is declared, it is unspecified what its return type is, except that the declaration (although not necessarily the definition) of the function shall be well formed.

T* operator->() const noexcept;

5
#

Requires: get() != 0.

6
#

Returns: get().

7
#

Remarks: When T is an array type, it is unspecified whether this member function is declared. If it is declared, it is unspecified what its return type is, except that the declaration (although not necessarily the definition) of the function shall be well formed.

element_type& operator[](ptrdiff_t i) const;

8
#

Requires: get() != 0 && i >= 0. If T is U[N], i < N.

9
#

Returns: get()[i].

10
#

Remarks: When T is not an array type, it is unspecified whether this member function is declared. If it is declared, it is unspecified what its return type is, except that the declaration (although not necessarily the definition) of the function shall be well formed.

11
#

Throws: Nothing.

long use_count() const noexcept;

12
#

Returns: The number of shared_­ptr objects, *this included, that share ownership with *this, or 0 when *this is empty.

13
#

Synchronization: None.

14
#

[ Note: get() == nullptr does not imply a specific return value of use_­count().  — end note ]

15
#

[ Note: weak_­ptr<T>​::​lock() can affect the return value of use_­count().  — end note ]

16
#

[ Note: When multiple threads can affect the return value of use_­count(), the result should be treated as approximate. In particular, use_­count() == 1 does not imply that accesses through a previously destroyed shared_­ptr have in any sense completed.  — end note ]

explicit operator bool() const noexcept;

17
#

Returns: get() != 0.

template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept; template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;

18
#

Returns: An unspecified value such that

  • (18.1)

    x.owner_­before(y) defines a strict weak ordering as defined in [alg.sorting];

  • (18.2)

    under the equivalence relation defined by owner_­before, !a.owner_­before(b) && !b.owner_­before(a), two shared_­ptr or weak_­ptr instances are equivalent if and only if they share ownership or are both empty.

23.11.2.2.6 shared_­ptr creation [util.smartptr.shared.create]

template<class T, class... Args> shared_ptr<T> make_shared(Args&&... args); template<class T, class A, class... Args> shared_ptr<T> allocate_shared(const A& a, Args&&... args);

1
#

Requires: The expression ​::​new (pv) T(std​::​forward<Args>(args)...), where pv has type void* and points to storage suitable to hold an object of type T, shall be well formed. A shall be an allocator. The copy constructor and destructor of A shall not throw exceptions.

2
#

Effects: Allocates memory suitable for an object of type T and constructs an object in that memory via the placement new-expression ​::​new (pv) T(std​::​forward<Args>(args)...). The template allocate_­shared uses a copy of a to allocate memory. If an exception is thrown, the functions have no effect.

3
#

Returns: A shared_­ptr instance that stores and owns the address of the newly constructed object of type T.

4
#

Postconditions: get() != 0 && use_­count() == 1.

5
#

Throws: bad_­alloc, or an exception thrown from A​::​allocate or from the constructor of T.

6
#

Remarks: The shared_­ptr constructor called by this function enables shared_­from_­this with the address of the newly constructed object of type T. Implementations should perform no more than one memory allocation. [ Note: This provides efficiency equivalent to an intrusive smart pointer.  — end note ]

7
#

[ Note: These functions will typically allocate more memory than sizeof(T) to allow for internal bookkeeping structures such as the reference counts.  — end note ]

23.11.2.2.7 shared_­ptr comparison [util.smartptr.shared.cmp]

template<class T, class U> bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;

1
#

Returns: a.get() == b.get().

template<class T, class U> bool operator<(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;

2
#

Returns: less<>()(a.get(), b.get()).

3
#

[ Note: Defining a comparison function allows shared_­ptr objects to be used as keys in associative containers.  — end note ]

template <class T> bool operator==(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator==(nullptr_t, const shared_ptr<T>& a) noexcept;

4
#

Returns: !a.

template <class T> bool operator!=(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator!=(nullptr_t, const shared_ptr<T>& a) noexcept;

5
#

Returns: (bool)a.

template <class T> bool operator<(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator<(nullptr_t, const shared_ptr<T>& a) noexcept;

6
#

Returns: The first function template returns less<shared_­ptr<T>​::​element_­type*>()(a.get(), nullptr). The second function template returns less<shared_­ptr<T>​::​element_­type*>()(nullptr, a.get()).

template <class T> bool operator>(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator>(nullptr_t, const shared_ptr<T>& a) noexcept;

7
#

Returns: The first function template returns nullptr < a. The second function template returns a < nullptr.

template <class T> bool operator<=(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator<=(nullptr_t, const shared_ptr<T>& a) noexcept;

8
#

Returns: The first function template returns !(nullptr < a). The second function template returns !(a < nullptr).

template <class T> bool operator>=(const shared_ptr<T>& a, nullptr_t) noexcept; template <class T> bool operator>=(nullptr_t, const shared_ptr<T>& a) noexcept;

9
#

Returns: The first function template returns !(a < nullptr). The second function template returns !(nullptr < a).

23.11.2.2.8 shared_­ptr specialized algorithms [util.smartptr.shared.spec]

template<class T> void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;

1
#

Effects: Equivalent to a.swap(b).

23.11.2.2.9 shared_­ptr casts [util.smartptr.shared.cast]

template<class T, class U> shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;

1
#

Requires: The expression static_­cast<T*>((U*)0) shall be well formed.

2
#

Returns: 

shared_ptr<T>(r, static_cast<typename shared_ptr<T>::element_type*>(r.get()))
3
#

[ Note: The seemingly equivalent expression shared_­ptr<T>(static_­cast<T*>(r.get())) will eventually result in undefined behavior, attempting to delete the same object twice.  — end note ]

template<class T, class U> shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;

4
#

Requires: The expression dynamic_­cast<T*>((U*)0) shall be well formed and shall have well defined behavior.

5
#

Returns:

  • (5.1)

    When dynamic_­cast<typename shared_­ptr<T>​::​element_­type*>(r.get()) returns a nonzero value p, shared_­ptr<T>(r, p).

  • (5.2)

    Otherwise, shared_­ptr<T>().

6
#

[ Note: The seemingly equivalent expression shared_­ptr<T>(dynamic_­cast<T*>(r.get())) will eventually result in undefined behavior, attempting to delete the same object twice.  — end note ]

template<class T, class U> shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;

7
#

Requires: The expression const_­cast<T*>((U*)0) shall be well formed.

8
#

Returns: 

shared_ptr<T>(r, const_cast<typename shared_ptr<T>::element_type*>(r.get()))
9
#

[ Note: The seemingly equivalent expression shared_­ptr<T>(const_­cast<T*>(r.get())) will eventually result in undefined behavior, attempting to delete the same object twice.  — end note ]

template<class T, class U> shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;

10
#

Requires: The expression reinterpret_­cast<T*>((U*)0) shall be well formed.

11
#

Returns: 

shared_ptr<T>(r, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()))
12
#

[ Note: The seemingly equivalent expression shared_­ptr<T>(reinterpret_­cast<T*>(r.get())) will eventually result in undefined behavior, attempting to delete the same object twice.  — end note ]

23.11.2.2.10 get_­deleter [util.smartptr.getdeleter]

template<class D, class T> D* get_deleter(const shared_ptr<T>& p) noexcept;

1
#

Returns: If p owns a deleter d of type cv-unqualified D, returns addressof(d); otherwise returns nullptr. The returned pointer remains valid as long as there exists a shared_­ptr instance that owns d. [ Note: It is unspecified whether the pointer remains valid longer than that. This can happen if the implementation doesn't destroy the deleter until all weak_­ptr instances that share ownership with p have been destroyed.  — end note ]

23.11.2.2.11 shared_­ptr I/O [util.smartptr.shared.io]

template<class E, class T, class Y> basic_ostream<E, T>& operator<< (basic_ostream<E, T>& os, const shared_ptr<Y>& p);

1
#

Effects: As if by: os << p.get();

2
#

Returns: os.

23.11.2.3 Class template weak_­ptr [util.smartptr.weak]

1
#

The weak_­ptr class template stores a weak reference to an object that is already managed by a shared_­ptr. To access the object, a weak_­ptr can be converted to a shared_­ptr using the member function lock.

namespace std {
  template<class T> class weak_ptr {
  public:
    using element_type = T;

    // [util.smartptr.weak.const], constructors
    constexpr weak_ptr() noexcept;
    template<class Y> weak_ptr(const shared_ptr<Y>& r) noexcept;
    weak_ptr(const weak_ptr& r) noexcept;
    template<class Y> weak_ptr(const weak_ptr<Y>& r) noexcept;
    weak_ptr(weak_ptr&& r) noexcept;
    template<class Y> weak_ptr(weak_ptr<Y>&& r) noexcept;

    // [util.smartptr.weak.dest], destructor
    ~weak_ptr();

    // [util.smartptr.weak.assign], assignment
    weak_ptr& operator=(const weak_ptr& r) noexcept;
    template<class Y> weak_ptr& operator=(const weak_ptr<Y>& r) noexcept;
    template<class Y> weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;
    weak_ptr& operator=(weak_ptr&& r) noexcept;
    template<class Y> weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;

    // [util.smartptr.weak.mod], modifiers
    void swap(weak_ptr& r) noexcept;
    void reset() noexcept;

    // [util.smartptr.weak.obs], observers
    long use_count() const noexcept;
    bool expired() const noexcept;
    shared_ptr<T> lock() const noexcept;
    template<class U> bool owner_before(const shared_ptr<U>& b) const;
    template<class U> bool owner_before(const weak_ptr<U>& b) const;
  };

  template<class T> weak_ptr(shared_ptr<T>) -> weak_ptr<T>;


  // [util.smartptr.weak.spec], specialized algorithms
  template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
}
2
#

Specializations of weak_­ptr shall be CopyConstructible and CopyAssignable, allowing their use in standard containers. The template parameter T of weak_­ptr may be an incomplete type.

23.11.2.3.1 weak_­ptr constructors [util.smartptr.weak.const]

constexpr weak_ptr() noexcept;

1
#

Effects: Constructs an empty weak_­ptr object.

2
#

Postconditions: use_­count() == 0.

weak_ptr(const weak_ptr& r) noexcept; template<class Y> weak_ptr(const weak_ptr<Y>& r) noexcept; template<class Y> weak_ptr(const shared_ptr<Y>& r) noexcept;

3
#

Remarks: The second and third constructors shall not participate in overload resolution unless Y* is compatible with T*.

4
#

Effects: If r is empty, constructs an empty weak_­ptr object; otherwise, constructs a weak_­ptr object that shares ownership with r and stores a copy of the pointer stored in r.

5
#

Postconditions: use_­count() == r.use_­count().

weak_ptr(weak_ptr&& r) noexcept; template<class Y> weak_ptr(weak_ptr<Y>&& r) noexcept;

6
#

Remarks: The second constructor shall not participate in overload resolution unless Y* is compatible with T*.

7
#

Effects: Move constructs a weak_­ptr instance from r.

8
#

Postconditions: *this shall contain the old value of r. r shall be empty. r.use_­count() == 0.

23.11.2.3.2 weak_­ptr destructor [util.smartptr.weak.dest]

~weak_ptr();
1
#

Effects: Destroys this weak_­ptr object but has no effect on the object its stored pointer points to.

23.11.2.3.3 weak_­ptr assignment [util.smartptr.weak.assign]

weak_ptr& operator=(const weak_ptr& r) noexcept; template<class Y> weak_ptr& operator=(const weak_ptr<Y>& r) noexcept; template<class Y> weak_ptr& operator=(const shared_ptr<Y>& r) noexcept;

1
#

Effects: Equivalent to weak_­ptr(r).swap(*this).

2
#

Remarks: The implementation may meet the effects (and the implied guarantees) via different means, without creating a temporary.

3
#

Returns: *this.

weak_ptr& operator=(weak_ptr&& r) noexcept; template<class Y> weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;

4
#

Effects: Equivalent to weak_­ptr(std​::​move(r)).swap(*this).

5
#

Returns: *this.

23.11.2.3.4 weak_­ptr modifiers [util.smartptr.weak.mod]

void swap(weak_ptr& r) noexcept;

1
#

Effects: Exchanges the contents of *this and r.

void reset() noexcept;

2
#

Effects: Equivalent to weak_­ptr().swap(*this).

23.11.2.3.5 weak_­ptr observers [util.smartptr.weak.obs]

long use_count() const noexcept;

1
#

Returns: 0 if *this is empty; otherwise, the number of shared_­ptr instances that share ownership with *this.

bool expired() const noexcept;

2
#

Returns: use_­count() == 0.

shared_ptr<T> lock() const noexcept;

3
#

Returns: expired() ? shared_­ptr<T>() : shared_­ptr<T>(*this), executed atomically.

template<class U> bool owner_before(const shared_ptr<U>& b) const; template<class U> bool owner_before(const weak_ptr<U>& b) const;

4
#

Returns: An unspecified value such that

  • (4.1)

    x.owner_­before(y) defines a strict weak ordering as defined in [alg.sorting];

  • (4.2)

    under the equivalence relation defined by owner_­before, !a.owner_­before(b) && !b.owner_­before(a), two shared_­ptr or weak_­ptr instances are equivalent if and only if they share ownership or are both empty.

23.11.2.3.6 weak_­ptr specialized algorithms [util.smartptr.weak.spec]

template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
1
#

Effects: Equivalent to a.swap(b).

23.11.2.4 Class template owner_­less [util.smartptr.ownerless]

1
#

The class template owner_­less allows ownership-based mixed comparisons of shared and weak pointers.

namespace std {
  template<class T = void> struct owner_less;

  template<class T> struct owner_less<shared_ptr<T>> {
    bool operator()(const shared_ptr<T>&, const shared_ptr<T>&) const noexcept;
    bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
  };

  template<class T> struct owner_less<weak_ptr<T>> {
    bool operator()(const weak_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const shared_ptr<T>&, const weak_ptr<T>&) const noexcept;
    bool operator()(const weak_ptr<T>&, const shared_ptr<T>&) const noexcept;
  };

  template<> struct owner_less<void> {
    template<class T, class U>
      bool operator()(const shared_ptr<T>&, const shared_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const shared_ptr<T>&, const weak_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const weak_ptr<T>&, const shared_ptr<U>&) const noexcept;
    template<class T, class U>
      bool operator()(const weak_ptr<T>&, const weak_ptr<U>&) const noexcept;

    using is_transparent = unspecified;
  };
}

2
#

operator()(x, y) shall return x.owner_­before(y). [ Note: Note that

  • (2.1)

    operator() defines a strict weak ordering as defined in [alg.sorting];

  • (2.2)

    under the equivalence relation defined by operator(), !operator()(a, b) && !operator()(b, a), two shared_­ptr or weak_­ptr instances are equivalent if and only if they share ownership or are both empty.

 — end note ]

23.11.2.5 Class template enable_­shared_­from_­this [util.smartptr.enab]

1
#

A class T can inherit from enable_­shared_­from_­this<T> to inherit the shared_­from_­this member functions that obtain a shared_­ptr instance pointing to *this.

2
#

[ Example: 

struct X: public enable_shared_from_this<X> { };

int main() {
  shared_ptr<X> p(new X);
  shared_ptr<X> q = p->shared_from_this();
  assert(p == q);
  assert(!p.owner_before(q) && !q.owner_before(p)); // p and q share ownership
}

 — end example ] 

namespace std {
  template<class T> class enable_shared_from_this {
  protected:
    constexpr enable_shared_from_this() noexcept;
    enable_shared_from_this(const enable_shared_from_this&) noexcept;
    enable_shared_from_this& operator=(const enable_shared_from_this&) noexcept;
    ~enable_shared_from_this();
  public:
    shared_ptr<T> shared_from_this();
    shared_ptr<T const> shared_from_this() const;
    weak_ptr<T> weak_from_this() noexcept;
    weak_ptr<T const> weak_from_this() const noexcept;
  private:
    mutable weak_ptr<T> weak_this; // exposition only
  };
}
3
#

The template parameter T of enable_­shared_­from_­this may be an incomplete type.

constexpr enable_shared_from_this() noexcept; enable_shared_from_this(const enable_shared_from_this<T>&) noexcept;

4
#

Effects: Value-initializes weak_­this.

enable_shared_from_this<T>& operator=(const enable_shared_from_this<T>&) noexcept;

5
#

Returns: *this.

6
#

[ Note: weak_­this is not changed.  — end note ]

shared_ptr<T> shared_from_this(); shared_ptr<T const> shared_from_this() const;

7
#

Returns: shared_­ptr<T>(weak_­this).

weak_ptr<T> weak_from_this() noexcept; weak_ptr<T const> weak_from_this() const noexcept;

8
#

Returns: weak_­this.

23.11.2.6 shared_­ptr atomic access [util.smartptr.shared.atomic]

1
#

Concurrent access to a shared_­ptr object from multiple threads does not introduce a data race if the access is done exclusively via the functions in this section and the instance is passed as their first argument.

2
#

The meaning of the arguments of type memory_­order is explained in [atomics.order].

template<class T> bool atomic_is_lock_free(const shared_ptr<T>* p);

3
#

Requires: p shall not be null.

4
#

Returns: true if atomic access to *p is lock-free, false otherwise.

5
#

Throws: Nothing.

template<class T> shared_ptr<T> atomic_load(const shared_ptr<T>* p);
6
#

Requires: p shall not be null.

7
#

Returns: atomic_­load_­explicit(p, memory_­order_­seq_­cst).

8
#

Throws: Nothing.

template<class T> shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);
9
#

Requires: p shall not be null.

10
#

Requires: mo shall not be memory_­order_­release or memory_­order_­acq_­rel.

11
#

Returns: *p.

12
#

Throws: Nothing.

template<class T> void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);

13
#

Requires: p shall not be null.

14
#

Effects: As if by atomic_­store_­explicit(p, r, memory_­order_­seq_­cst).

15
#

Throws: Nothing.

template<class T> void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);

16
#

Requires: p shall not be null.

17
#

Requires: mo shall not be memory_­order_­acquire or memory_­order_­acq_­rel.

18
#

Effects: As if by p->swap(r).

19
#

Throws: Nothing.

template<class T> shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);

20
#

Requires: p shall not be null.

21
#

Returns: atomic_­exchange_­explicit(p, r, memory_­order_­seq_­cst).

22
#

Throws: Nothing.

template<class T> shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);

23
#

Requires: p shall not be null.

24
#

Effects: As if by p->swap(r).

25
#

Returns: The previous value of *p.

26
#

Throws: Nothing.

template<class T> bool atomic_compare_exchange_weak(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);

27
#

Requires: p shall not be null and v shall not be null.

28
#

Returns: 

atomic_compare_exchange_weak_explicit(p, v, w, memory_order_seq_cst, memory_order_seq_cst)
29
#

Throws: Nothing.

template<class T> bool atomic_compare_exchange_strong(shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w);

30
#

Returns: 

atomic_compare_exchange_strong_explicit(p, v, w, memory_order_seq_cst, memory_order_seq_cst)

template<class T> bool atomic_compare_exchange_weak_explicit( shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w, memory_order success, memory_order failure); template<class T> bool atomic_compare_exchange_strong_explicit( shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w, memory_order success, memory_order failure);

31
#

Requires: p shall not be null and v shall not be null. The failure argument shall not be memory_­order_­release nor memory_­order_­acq_­rel.

32
#

Effects: If *p is equivalent to *v, assigns w to *p and has synchronization semantics corresponding to the value of success, otherwise assigns *p to *v and has synchronization semantics corresponding to the value of failure.

33
#

Returns: true if *p was equivalent to *v, false otherwise.

34
#

Throws: Nothing.

35
#

Remarks: Two shared_­ptr objects are equivalent if they store the same pointer value and share ownership. The weak form may fail spuriously. See [atomics.types.operations].

23.11.2.7 Smart pointer hash support [util.smartptr.hash]

template <class T, class D> struct hash<unique_ptr<T, D>>;

1
#

Letting UP be unique_­ptr<T,D>, the specialization hash<UP> is enabled ([unord.hash]) if and only if hash<typename UP​::​pointer> is enabled. When enabled, for an object p of type UP, hash<UP>()(p) shall evaluate to the same value as hash<typename UP​::​pointer>()(p.get()). The member functions are not guaranteed to be noexcept.

template <class T> struct hash<shared_ptr<T>>;

2
#

For an object p of type shared_­ptr<T>, hash<shared_­ptr<T>>()(p) shall evaluate to the same value as hash<typename shared_­ptr<T>​::​element_­type*>()(p.get()).