The weak_ptr class template stores a pointer to an object that's already managed by a shared_ptr. When the object last shared_ptr to the object goes away and the object is deleted, all weak_ptr objects have their stored pointers set to 0.
Every weak_ptr meets the CopyConstructible and Assignable requirements of the C++ Standard Library, and so can be used in standard library containers. Comparison operators are supplied so that weak_ptr works with the standard library's associative containers.
The class template is parameterized on T, the type of the object pointed to. T must meet the smart pointer common requirements.
namespace boost { template<typename T> class weak_ptr { public: typedef T element_type; explicit weak_ptr(); template<typename Y> weak_ptr(shared_ptr<Y> const & r); // never throws ~weak_ptr(); // never throws weak_ptr(weak_ptr const & r); // never throws template<typename Y> weak_ptr(weak_ptr<Y> const & r); // never throws weak_ptr & operator=(weak_ptr const & r); // never throws template<typename Y> weak_ptr & operator=(weak_ptr<Y> const & r); // never throws template<typename Y> weak_ptr & operator=(shared_ptr<Y> const & r); // never throws void reset(); // never throws T & operator*() const; // never throws T * operator->() const; // never throws T * get() const; // never throws long use_count() const; // never throws void swap(weak_ptr<T> & b); // never throws }; template<typename T, typename U> bool operator==(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws template<typename T, typename U> bool operator!=(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws template<typename T, typename U> bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws template<typename T> void swap(weak_ptr<T> & a, weak_ptr<T> & b); // never throws template<typename T, typename U> weak_ptr<T> shared_static_cast(weak_ptr<U> const & r); // never throws template<typename T, typename U> weak_ptr<T> shared_dynamic_cast(weak_ptr<U> const & r); }
typedef T element_type;
Provides the type of the stored pointer.
explicit weak_ptr();
Constructs a weak_ptr, with 0 as its stored pointer. The only exception which may be thrown by this constructor is std::bad_alloc. If an exception is thrown, the constructor has no effect.
template<typename Y> weak_ptr(shared_ptr<Y> const & r); // never throws
Constructs a weak_ptr, as if by storing a copy of the pointer stored in r. Afterwards, the use count for all copies is unchanged. When the last shared_ptr is destroyed, the use count and stored pointer become 0.
weak_ptr(weak_ptr const & r); // never throws template<typename Y> weak_ptr(weak_ptr<Y> const & r); // never throws
Constructs a weak_ptr, as if by storing a copy of the pointer stored in r.
~weak_ptr(); // never throws
Destroys this weak_ptr but has no effect on the object its stored pointer points to. T need not be a complete type. See the smart pointer common requirements.
weak_ptr & operator=(weak_ptr const & r); // never throws template<typename Y> weak_ptr & operator=(weak_ptr<Y> const & r); // never throws template<typename Y> weak_ptr & operator=(shared_ptr<Y> const & r); // never throws
Constructs a new weak_ptr as described above, then replaces this weak_ptr with the new one, destroying the replaced object.
void reset();
Constructs a new weak_ptr as described above, then replaces this weak_ptr with the new one, destroying the replaced object. The only exception which may be thrown is std::bad_alloc. If an exception is thrown, the reset has no effect.
T & operator*() const; // never throws
Returns a reference to the object pointed to by the stored pointer. Behavior is undefined if the stored pointer is 0. Note that the stored pointer becomes 0 if all shared_ptr objects for that pointer are destroyed.
T * operator->() const; // never throws
Returns the stored pointer. Behavior is undefined if the stored pointer is 0. Note that the stored pointer becomes 0 if all shared_ptr objects for that pointer are destroyed.
T * get() const; // never throws
Returns the stored pointer. Note that the stored pointer becomes 0 if all shared_ptr objects for that pointer are destroyed. T need not be a complete type. See the smart pointer common requirements.
long use_count() const; // never throws
Returns the number of shared_ptr objects sharing ownership of the stored pointer. T need not be a complete type. See the smart pointer common requirements.
Because use_count is not necessarily efficient to implement for implementations of weak_ptr that do not use an explicit reference count, it might be removed from some future version. Thus it should be used for debugging purposes only, and get should be used for production code.
void swap(weak_ptr & b); // never throws
Exchanges the contents of the two smart pointers. T need not be a complete type. See the smart pointer common requirements.
template<typename T, typename U> bool operator==(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws template<typename T, typename U> bool operator!=(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws template<typename T, typename U> bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
Compares the stored pointers of the two smart pointers. T need not be a complete type. See the smart pointer common requirements.
The operator< overload is provided to define an ordering so that weak_ptr objects can be used in associative containers such as std::map. The implementation uses std::less<T *> to perform the comparison. This ensures that the comparison is handled correctly, since the standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel] paragraph 2) but std::less<> on pointers is well-defined (20.3.3 [lib.comparisons] paragraph 8).
template<typename T> void swap(weak_ptr<T> & a, weak_ptr<T> & b) // never throws
Equivalent to a.swap(b). Matches the interface of std::swap. Provided as an aid to generic programming.
template<typename T, typename U> weak_ptr<T> shared_static_cast(weak_ptr<U> const & r); // never throws
Perform a static_cast on the stored pointer, returning another weak_ptr. The resulting smart pointer will share its use count with the original pointer.
template<typename T, typename U> weak_ptr<T> shared_dynamic_cast(weak_ptr<U> const & r);
Perform a dynamic_cast on the stored pointer, returning another weak_ptr. The resulting smart pointer will share its use count with the original pointer unless the result of the cast is 0. The only exception which may be thrown is std::bad_alloc, which may be thrown during the construction of the new weak_ptr if the result of the cast is 0. If an exception is thrown, the cast has no effect.
Revised 1 February 2002
Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.