[util.sharedptr] (original) (raw)

20 Memory management library [mem]

20.3 Smart pointers [smartptr]

20.3.2 Shared-ownership pointers [util.sharedptr]

20.3.2.1 Class bad_weak_ptr [util.smartptr.weak.bad]

namespace std { class bad_weak_ptr : public exception { public: const char* what() const noexcept override;};}

An exception of type bad_weak_ptr is thrown by the shared_ptrconstructor taking a weak_ptr.

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

20.3.2.3 Class template weak_ptr [util.smartptr.weak]

20.3.2.3.1 General [util.smartptr.weak.general]

The weak_ptr class template stores a weak reference to an object that is already managed by a shared_ptr.

To access the object, aweak_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 = remove_extent_t<T>;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;~weak_ptr(); 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;void swap(weak_ptr& r) noexcept;void reset() noexcept;long use_count() const noexcept;bool expired() const noexcept; shared_ptr<T> lock() const noexcept;template<class U> bool owner_before(const shared_ptr& b) const noexcept;template<class U> bool owner_before(const weak_ptr& b) const noexcept; size_t owner_hash() const noexcept;template<class U> bool owner_equal(const shared_ptr& b) const noexcept;template<class U> bool owner_equal(const weak_ptr& b) const noexcept;};template<class T> weak_ptr(shared_ptr<T>) -> weak_ptr<T>;}

The template parameter T of weak_ptr may be an incomplete type.

20.3.2.3.2 Constructors [util.smartptr.weak.const]

constexpr weak_ptr() noexcept;

Effects: Constructs an empty weak_ptr object that stores a null pointer value.

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;

Constraints: For the second and third constructors, Y* is compatible with T*.

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

Postconditions: use_count() == r.use_count().

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

Constraints: For the second constructor, Y* is compatible with T*.

Effects: Move constructs a weak_ptr instance from r.

Postconditions: *this contains the old value of r.

r is empty, stores a null pointer value, and r.use_count() == 0.

20.3.2.3.3 Destructor [util.smartptr.weak.dest]

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

20.3.2.3.4 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;

Effects: Equivalent to weak_ptr(r).swap(*this).

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

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

Effects: Equivalent to weak_ptr(std::move(r)).swap(*this).

20.3.2.3.5 Modifiers [util.smartptr.weak.mod]

void swap(weak_ptr& r) noexcept;

Effects: Exchanges the contents of *this and r.

Effects: Equivalent to weak_ptr().swap(*this).

20.3.2.3.6 Observers [util.smartptr.weak.obs]

long use_count() const noexcept;

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

bool expired() const noexcept;

Returns: use_count() == 0.

shared_ptr<T> lock() const noexcept;

Returns: expired() ? shared_ptr<T>() : shared_ptr<T>(*this), executed atomically.

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

Returns: An unspecified value such that

owner_before(b) defines a strict weak ordering as defined in [alg.sorting];
!owner_before(b) && !b.owner_before(*this) is trueif and only if owner_equal(b) is true.

size_t owner_hash() const noexcept;

Returns: An unspecified value such that, for any object x where owner_equal(x) is true,owner_hash() == x.owner_hash() is true.

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

Returns: true if and only if*this and b share ownership or are both empty.

Otherwise returns false.

Remarks: owner_equal is an equivalence relation.

20.3.2.3.7 Specialized algorithms [util.smartptr.weak.spec]

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

Effects: Equivalent to a.swap(b).

20.3.2.4 Class template owner_less [util.smartptr.ownerless]

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&) const noexcept;template<class T, class U> bool operator()(const shared_ptr<T>&, const weak_ptr&) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>&, const shared_ptr&) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>&, const weak_ptr&) const noexcept;using is_transparent = unspecified;};}

operator()(x, y) returns x.owner_before(y).

[Note 1:

Note that

operator() defines a strict weak ordering as defined in [alg.sorting];
!operator()(a, b) && !operator()(b, a) is trueif and only if a.owner_equal(b) is true.

— _end note_]

20.3.2.5 Struct owner_hash [util.smartptr.owner.hash]

The class owner_hash provides ownership-based hashing.

namespace std { struct owner_hash { template<class T> size_t operator()(const shared_ptr<T>&) const noexcept;template<class T> size_t operator()(const weak_ptr<T>&) const noexcept;using is_transparent = unspecified;};}

template<class T> size_t operator()(const shared_ptr<T>& x) const noexcept;template<class T> size_t operator()(const weak_ptr<T>& x) const noexcept;

[Note 1:

For any object y where x.owner_equal(y) is true,x.owner_hash() == y.owner_hash() is true.

— _end note_]

20.3.2.6 Struct owner_equal [util.smartptr.owner.equal]

The class owner_equal provides ownership-based mixed equality comparisons of shared and weak pointers.

namespace std { struct owner_equal { template<class T, class U> bool operator()(const shared_ptr<T>&, const shared_ptr&) const noexcept;template<class T, class U> bool operator()(const shared_ptr<T>&, const weak_ptr&) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>&, const shared_ptr&) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>&, const weak_ptr&) const noexcept;using is_transparent = unspecified;};}

template<class T, class U> bool operator()(const shared_ptr<T>& x, const shared_ptr& y) const noexcept;template<class T, class U> bool operator()(const shared_ptr<T>& x, const weak_ptr& y) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>& x, const shared_ptr& y) const noexcept;template<class T, class U> bool operator()(const weak_ptr<T>& x, const weak_ptr& y) const noexcept;

Returns: x.owner_equal(y).

[Note 1:

x.owner_equal(y) is trueif and only if x and y share ownership or are both empty.

— _end note_]

20.3.2.7 Class template enable_shared_from_this [util.smartptr.enab]

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.

[Example 1: 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_equal(q)); } — _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; };}

The template parameter T of enable_shared_from_thismay be an incomplete type.

Effects: Value-initializes weak-this.

[Note 1:

weak-this is not changed.

— _end note_]

Returns: shared_ptr<T>(weak-this).