CLASS TEMPLATE WE(3)

NAME
boost::interprocess::weak_ptr

SYNOPSIS

// In header: <boost/interprocess/smart_ptr/weak_ptr.hpp>
template<typename T, typename A, typename D>
class weak_ptr {
public:
  // types
  typedef T element_type;
  typedef T value_type;
  // construct/copy/destruct
  weak_ptr();
  template<typename Y> weak_ptr(weak_ptr< Y, A, D > const &);
  template<typename Y> weak_ptr(shared_ptr< Y, A, D > const &);
  template<typename Y> weak_ptr& operator=(weak_ptr< Y, A, D > const &);
  template<typename Y> weak_ptr& operator=(shared_ptr< Y, A, D > const &);
  // public member functions
  shared_ptr< T, A, D > lock() const;
  long use_count() const;
  bool expired() const;
  void reset();
  void swap(this_type &);
  bool _internal_less(weak_ptr< T2, A2, D2 > const &) const;
  template<typename Y> void _internal_assign(unspecified);
};

DESCRIPTION

The weak_ptr class template stores a "weak reference" to an object that's already managed by a shared_ptr. To access the object, a weak_ptr can be converted to a shared_ptr using the shared_ptr constructor or the member function lock. When the last shared_ptr to the object goes away and the object is deleted, the attempt to obtain a shared_ptr from the weak_ptr instances that refer to the deleted object will fail: the constructor will throw an exception of type bad_weak_ptr, and weak_ptr::lock will return an empty shared_ptr.

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.

weak_ptr operations never throw exceptions.

The class template is parameterized on T, the type of the object pointed to.

  weak_ptr public construct/copy/destruct

    1.

    weak_ptr();

    Effects: Constructs an empty weak_ptr. Postconditions: use_count() == 0.

    2.

    template<typename Y> weak_ptr(weak_ptr< Y, A, D > const & r);

    Effects: If r is empty, constructs an empty weak_ptr; otherwise, constructs a weak_ptr that shares ownership with r as if by storing a copy of the pointer stored in r.

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

    Throws: nothing.

    3.

    template<typename Y> weak_ptr(shared_ptr< Y, A, D > const & r);

    Effects: If r is empty, constructs an empty weak_ptr; otherwise, constructs a weak_ptr that shares ownership with r as if by storing a copy of the pointer stored in r.

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

    Throws: nothing.

    4.

    template<typename Y> weak_ptr& operator=(weak_ptr< Y, A, D > const & r);

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

    Throws: nothing.

    Notes: The implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary.

    5.

    template<typename Y> weak_ptr& operator=(shared_ptr< Y, A, D > const & r);

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

    Throws: nothing.

    Notes: The implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary.

  weak_ptr public member functions

    1.

    shared_ptr< T, A, D > lock() const;

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

    Throws: nothing.

    2.

    long use_count() const;

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

    Throws: nothing.

    Notes: use_count() is not necessarily efficient. Use only for debugging and testing purposes, not for production code.

    3.

    bool expired() const;

    Returns: Returns: use_count() == 0.

    Throws: nothing.

    Notes: expired() may be faster than use_count().

    4.

    void reset();

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

    5.

    void swap(this_type & other);

    Effects: Exchanges the contents of the two smart pointers.

    Throws: nothing.

    6.

    bool _internal_less(weak_ptr< T2, A2, D2 > const & rhs) const;
    @ template<class T2, class A2, class D2> .RE

        7.

        template<typename Y> void _internal_assign(unspecified pn2);