c++boost.gif (8819 bytes)weak_ptr class template

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.

Synopsis

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

}

Members

element_type

typedef T element_type;

Provides the type of the stored pointer.

constructors

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.

destructor

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

assignment

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.

reset

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.

indirection

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.

get

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.

use_count

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.

swap

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.

Free Functions

comparison

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

swap

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.

shared_static_cast

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.

shared_dynamic_cast

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.