weak_ptr Class

Article
07/29/2015

Wraps a weakly linked pointer.

template<class Ty> class weak_ptr {
public:
    typedef Ty element_type;

    weak_ptr();
    weak_ptr(const weak_ptr&);
    template<class Other>
        weak_ptr(const weak_ptr<Other>&);
    template<class Other>
        weak_ptr(const shared_ptr<Other>&);

    weak_ptr& operator=(const weak_ptr&);
    template<class Other>
        weak_ptr& operator=(const weak_ptr<Other>&);
    template<class Other>
        weak_ptr& operator=(shared_ptr<Other>&);

    void swap(weak_ptr&);
    void reset();

    long use_count() const;
    bool expired() const;
    shared_ptr<Ty> lock() const;
    };

Parameters

Ty
The type controlled by the weak pointer.

Remarks

The template class describes an object that points to a resource that is managed by one or more shared_ptr Class objects. The weak_ptr objects that point to a resource do not affect the resource's reference count. Thus, when the last shared_ptr object that manages that resource is destroyed the resource will be freed, even if there are weak_ptr objects pointing to that resource. This is essential for avoiding cycles in data structures.

A weak_ptr object points to a resource if it was constructed from a shared_ptr object that owns that resource, if it was constructed from a weak_ptr object that points to that resource, or if that resource was assigned to it with weak_ptr::operator=. A weak_ptr object does not provide direct access to the resource that it points to. Code that needs to use the resource does so through a shared_ptr object that owns that resource, created by calling the member function weak_ptr::lock. A weak_ptr object has expired when the resource that it points to has been freed because all of the shared_ptr objects that own the resource have been destroyed. Calling lock on a weak_ptr object that has expired creates an empty shared_ptr object.

An empty weak_ptr object does not point to any resources and has no control block. Its member function lock returns an empty shared_ptr object.

A cycle occurs when two or more resources controlled by shared_ptr objects hold mutually referencing shared_ptr objects. For example, a circular linked list with three elements has a head node N0; that node holds a shared_ptr object that owns the next node, N1; that node holds a shared_ptr object that owns the next node, N2; that node, in turn, holds a shared_ptr object that owns the head node, N0, closing the cycle. In this situation, none of the reference counts will ever become zero, and the nodes in the cycle will not be freed. To eliminate the cycle, the last node N2 should hold a weak_ptr object pointing to N0 instead of a shared_ptr object. Since the weak_ptr object does not own N0 it doesn't affect N0's reference count, and when the program's last reference to the head node is destroyed the nodes in the list will also be destroyed.

Members

Constructors

weak_ptr::weak_ptr

Constructs a weak_ptr.

Methods

weak_ptr::element_type	The type of the element.
weak_ptr::expired	Tests if ownership has expired.
weak_ptr::lock	Obtains exclusive ownership of a resource.
weak_ptr::owner_before	Returns true if this weak_ptr is ordered before (or less than) the provided pointer.
weak_ptr::reset	Releases owned resource.
weak_ptr::swap	Swaps two weak_ptr objects.
weak_ptr::use_count	Counts number of designated shared_ptr objects.

Operators

weak_ptr::operator=

Replaces owned resource.

Requirements

Header: <memory>

Namespace: std

Share via