Share via


weak_ptr Class

 

The latest version of this topic can be found at weak_ptr Class.

Wraps a weakly linked pointer.

Syntax

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

weak_ptr::element_type

The type of the element.

typedef Ty element_type;  

Remarks

The type is a synonym for the template parameter Ty.

Example

// std_tr1__memory__weak_ptr_element_type.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
int main()   
    {   
    std::shared_ptr<int> sp0(new int(5));   
    std::weak_ptr<int> wp0(sp0);   
    std::weak_ptr<int>::element_type val = *wp0.lock();   
  
    std::cout << "*wp0.lock() == " << val << std::endl;   
  
    return (0);   
    }  
  
*wp0.lock
() == 5  

weak_ptr::expired

Tests if ownership has expired.

bool expired() const;

Remarks

The member function returns true if *this has expired, otherwise false.

Example

// std_tr1__memory__weak_ptr_expired.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
struct deleter   
    {   
    void operator()(int *p)   
        {   
        delete p;   
        }   
    };   
  
int main()   
    {   
    std::weak_ptr<int> wp;   
  
     {   
    std::shared_ptr<int> sp(new int(10));   
    wp = sp;   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
    std::cout << "*wp.lock() == " << *wp.lock() << std::endl;   
     }   
  
// check expired after sp is destroyed   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
    std::cout << "(bool)wp.lock() == " << std::boolalpha   
        << (bool)wp.lock() << std::endl;   
  
    return (0);   
    }  
  
wp.expired
() == false  
*wp.lock
() == 10  
wp.expired
() == true  
(bool)wp.lock
() == false  

weak_ptr::lock

Obtains exclusive ownership of a resource.

shared_ptr<Ty> lock() const;

Remarks

The member function returns an empty shared_ptr object if *this has expired; otherwise it returns a shared_ptr Class<Ty> object that owns the resource that *this points to.

Example

// std_tr1__memory__weak_ptr_lock.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
struct deleter   
    {   
    void operator()(int *p)   
        {   
        delete p;   
        }   
    };   
  
int main()   
    {   
    std::weak_ptr<int> wp;   
  
     {   
    std::shared_ptr<int> sp(new int(10));   
    wp = sp;   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
    std::cout << "*wp.lock() == " << *wp.lock() << std::endl;   
     }   
  
// check expired after sp is destroyed   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
    std::cout << "(bool)wp.lock() == " << std::boolalpha   
        << (bool)wp.lock() << std::endl;   
  
    return (0);   
    }  
  
wp.expired
() == false  
*wp.lock
() == 10  
wp.expired
() == true  
(bool)wp.lock
() == false  

weak_ptr::operator=

Replaces owned resource.

weak_ptr& operator=(const weak_ptr& wp);

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

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

Parameters

Other
The type controlled by the argument shared/weak pointer.

wp
The weak pointer to copy.

sp
The shared pointer to copy.

Remarks

The operators all release the resource currently pointed to by *this and assign ownership of the resource named by the operand sequence to *this. If an operator fails it leaves *this unchanged.

Example

// std_tr1__memory__weak_ptr_operator_as.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
int main()   
    {   
    std::shared_ptr<int> sp0(new int(5));   
    std::weak_ptr<int> wp0(sp0);   
    std::cout << "*wp0.lock() == " << *wp0.lock() << std::endl;   
  
    std::shared_ptr<int> sp1(new int(10));   
    wp0 = sp1;   
    std::cout << "*wp0.lock() == " << *wp0.lock() << std::endl;   
  
    std::weak_ptr<int> wp1;   
    wp1 = wp0;   
    std::cout << "*wp1.lock() == " << *wp1.lock() << std::endl;   
  
    return (0);   
    }  
  
*wp0.lock
() == 5  
*wp0.lock
() == 10  
*wp1.lock
() == 10  

weak_ptr::owner_before

Returns true if this weak_ptr is ordered before (or less than) the provided pointer.

template <class Other>  
bool owner_before(const shared_ptr<Other>& ptr);

template <class Other>  
bool owner_before(const weak_ptr<Other>& ptr);

Parameters

ptr
An lvalue reference to either a shared_ptr or a weak_ptr.

Remarks

The template member function returns true if *this is ordered before``ptr.

weak_ptr::reset

Releases owned resource.

void reset();

Remarks

The member function releases the resource pointed to by *this and converts *this to an empty weak_ptr object.

Example

// std_tr1__memory__weak_ptr_reset.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
int main()   
    {   
    std::shared_ptr<int> sp(new int(5));   
    std::weak_ptr<int> wp(sp);   
    std::cout << "*wp.lock() == " << *wp.lock() << std::endl;   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
  
    wp.reset();   
    std::cout << "wp.expired() == " << std::boolalpha   
        << wp.expired() << std::endl;   
  
    return (0);   
    }  
  
*wp.lock
() == 5  
wp.expired
() == false  
wp.expired
() == true  

weak_ptr::swap

Swaps two weak_ptr objects.

void swap(weak_ptr& wp);

Parameters

wp
The weak pointer to swap with.

Remarks

The member function leaves the resource originally pointed to by *this subsequently pointed to by wp, and the resource originally pointed to by wp subsequently pointed to by *this. The function does not change the reference counts for the two resources and it does not throw any exceptions.

Example

// std_tr1__memory__weak_ptr_swap.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
struct deleter   
    {   
    void operator()(int *p)   
        {   
        delete p;   
        }   
    };   
  
int main()   
    {   
    std::shared_ptr<int> sp1(new int(5));   
    std::shared_ptr<int> sp2(new int(10));   
    std::cout << "*sp1 == " << *sp1 << std::endl;   
  
    sp1.swap(sp2);   
    std::cout << "*sp1 == " << *sp1 << std::endl;   
  
    swap(sp1, sp2);   
    std::cout << "*sp1 == " << *sp1 << std::endl;   
    std::cout << std::endl;   
  
    std::weak_ptr<int> wp1(sp1);   
    std::weak_ptr<int> wp2(sp2);   
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;   
  
    wp1.swap(wp2);   
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;   
  
    swap(wp1, wp2);   
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;   
  
    return (0);   
    }  
  
*sp1 == 5  
*sp1 == 10  
*sp1 == 5  
  
*wp1 == 5  
*wp1 == 10  
*wp1 == 5  

weak_ptr::use_count

Counts number of designated shared_ptr objects.

long use_count() const;

Remarks

The member function returns the number of shared_ptr objects that own the resource pointed to by *this.

Example

// std_tr1__memory__weak_ptr_use_count.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
int main()   
    {   
    std::shared_ptr<int> sp1(new int(5));   
    std::weak_ptr<int> wp(sp1);   
    std::cout << "wp.use_count() == "   
        << wp.use_count() << std::endl;   
  
    std::shared_ptr<int> sp2(sp1);   
    std::cout << "wp.use_count() == "   
        << wp.use_count() << std::endl;   
  
    return (0);   
    }  
  
wp.use_count
() == 1  
wp.use_count
() == 2  

weak_ptr::weak_ptr

Constructs a weak_ptr.

weak_ptr();

weak_ptr(const weak_ptr& wp);

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

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

Parameters

Other
The type controlled by the argument shared/weak pointer.

wp
The weak pointer to copy.

sp
The shared pointer to copy.

Remarks

The constructors each construct an object that points to the resource named by the operand sequence.

Example

// std_tr1__memory__weak_ptr_construct.cpp   
// compile with: /EHsc   
#include <memory>   
#include <iostream>   
  
int main()   
    {   
    std::weak_ptr<int> wp0;   
    std::cout << "wp0.expired() == " << std::boolalpha   
        << wp0.expired() << std::endl;   
  
    std::shared_ptr<int> sp1(new int(5));   
    std::weak_ptr<int> wp1(sp1);   
    std::cout << "*wp1.lock() == "   
        << *wp1.lock() << std::endl;   
  
    std::weak_ptr<int> wp2(wp1);   
    std::cout << "*wp2.lock() == "   
        << *wp2.lock() << std::endl;   
  
    return (0);   
    }  
  
wp0.expired
() == true  
*wp1.lock
() == 5  
*wp2.lock
() == 5  

See Also

shared_ptr Class