Returns: an implementation-defined value such that operator<
+
Returns: an implementation-defined value such that operator<
is a strict weak ordering as described in section 25.3 [lib.alg.sorting]
of the C++ standard.
Throws: nothing.
@@ -343,7 +343,7 @@ q = p;Throws: std::bad_alloc.
-Exception safety: If an exception is thrown, the function has no +
Exception safety: If an exception is thrown, the function has no effect.
Notes: the seemingly equivalent expression
shared_ptr<T>(dynamic_cast<T*>(r.get()))
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 {
+
+ weak_ptr
+
+
+
+ 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 {
@@ -48,12 +38,10 @@ pointed to. T must meet the smart pointer
template<typename Y> weak_ptr & operator=(shared_ptr<Y> const & r); // never throws
void reset();
-
- T & operator*() const; // never throws
- T * operator->() const; // never throws
- T * get() const; // never throws
+ T * get() const; // never throws; unsafe in multithreaded code!
long use_count() const; // never throws
+ bool expired() const; // never throws
void swap(weak_ptr<T> & b); // never throws
};
@@ -67,174 +55,218 @@ pointed to. T must meet the smart pointer
template<typename T> void swap(weak_ptr<T> & a, weak_ptr<T> & b); // never throws
+ template<typename T>
+ shared_ptr<T> make_shared(weak_ptr<T> const & r); // never throws
+
template<typename T, typename U>
- weak_ptr<T> shared_static_cast(weak_ptr<U> const & r); // never throws
+ 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);
+ weak_ptr<T> shared_dynamic_cast(weak_ptr<U> const & r);
template<typename T, typename U>
- weak_ptr<T> shared_polymorphic_cast(weak_ptr<U> const & r);
+ weak_ptr<T> shared_polymorphic_cast(weak_ptr<U> const & r);
template<typename T, typename U>
- weak_ptr<T> shared_polymorphic_downcast(weak_ptr<U> const & r); // never throws
+ weak_ptr<T> shared_polymorphic_downcast(weak_ptr<U> const & r); // never throws
-}
-
-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
+}
+
+ Members
+ element_type
+ typedef T element_type;
+
+ Provides the type of the template parameter T.
+
+ constructors
+ explicit weak_ptr();
+
+ Effects: Constructs a weak_ptr.
+ Postconditions: use count is 0; the stored
+ pointer is 0.
+ Throws: std::bad_alloc.
+ Exception safety: If an exception is thrown, the constructor has no
+ effect.
+ Notes: T need not be a complete type. See the smart pointer
+ common requirements.
+
+ template<typename Y> weak_ptr(shared_ptr<Y> const & r); // never throws
+
+ Effects: Constructs a weak_ptr, as if by storing a copy of the
+ pointer stored in r.
+ Throws: nothing.
+ Notes: 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
+
+ Effects: Constructs a weak_ptr, as if by storing a copy of the
+ pointer stored in r.
+ Throws: nothing.
+ Notes: The use count for all copies is
+ unchanged.
+
+ destructor
+ ~weak_ptr(); // never throws
+
+ Effects: Destroys this weak_ptr but has no effect on the object
+ its stored pointer points to.
+ Throws: nothing.
+ Notes: 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>
+
+ 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.
+
+ reset
+ void reset();
+
+ Effects: Equivalent to weak_ptr().swap(*this).
+
+ get
+ T * get() const; // never throws
+
+ Returns: the stored pointer (0 if all shared_ptr objects for that
+ pointer are destroyed.)
+ Throws: nothing.
+ Notes: Using get in multithreaded code is dangerous. After the
+ function returns, the pointed-to object may be destroyed by a different thread,
+ since the weak_ptr doesn't affect its use_count.
+
+ use_count
+ long use_count() const; // never throws
+
+ Returns: the number of shared_ptr objects sharing ownership of the
+ stored pointer.
+ Throws: nothing.
+ Notes: use_count() is not necessarily efficient. Use only
+ for debugging and testing purposes, not for production code. T need not
+ be a complete type. See the smart pointer
+ common requirements.
+
+ expired
+ bool expired() const; // never throws
+
+ Returns: use_count() == 0.
+ Throws: nothing.
+ Notes: expired() may be faster than use_count().
+ T need not be a complete type. See the smart pointer
+ common requirements.
+
+ swap
+ void swap(weak_ptr & b); // never throws
+
+ Effects: Exchanges the contents of the two smart pointers.
+ Throws: nothing.
+ Notes: 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>
+ bool operator!=(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
+
+ Returns: a.get() == b.get().
+ Throws: nothing.
+ Notes: T need not be a complete type. See the smart pointer
+ common requirements.
+
+ template<typename T>
bool operator<(weak_ptr<T> const & a, weak_ptr<T> 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>
+
+ Returns: an implementation-defined value such that operator< is
+ a strict weak ordering as described in section 25.3 [lib.alg.sorting]
+ of the C++ standard.
+ Throws: nothing.
+ Notes: Allows weak_ptr objects to be used as keys in
+ associative containers. T need not be a complete type. See the smart
+ pointer common requirements.
+
+ 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.
-
-shared_polymorphic_cast
-template<typename T, typename U>
- weak_ptr<T> shared_polymorphic_cast(weak_ptr<U> const & r);
-Perform a polymorphic_cast on the stored pointer,
-returning another weak_ptr.
-The resulting smart pointer will share its use count with the original pointer.
-The only exception which may be thrown is std::bad_cast, if the pointer type can not be converted.
-If an exception is thrown, the cast has no effect.
-
-shared_polymorphic_downcast
-template<typename T, typename U>
- weak_ptr<T> shared_polymorphic_downcast(weak_ptr<U> const & r); // never throws
-Perform a polymorphic_downcast on the stored pointer,
-returning another weak_ptr.
-The resulting smart pointer will share its use count with the original pointer.
-
-
-
-Revised 8 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.
-
-
-
+
+ Effects: Equivalent to a.swap(b).
+ Throws: nothing.
+ Notes: Matches the interface of std::swap. Provided as an aid to
+ generic programming.
+
+ make_shared
+ template<typename T>
+ shared_ptr<T> make_shared(weak_ptr<T> & const r) // never throws
+
+ Returns: r.expired()? shared_ptr<T>(): shared_ptr<T>(r).
+ Throws: nothing.
+
+ shared_static_cast
+ template<typename T, typename U>
+ weak_ptr<T> shared_static_cast(weak_ptr<U> const & r); // never throws
+
+ Requires: The expression static_cast<T*>(r.get())
+ must be well-formed.
+ Returns: A weak_ptr<T> object that stores a copy
+ of static_cast<T*>(r.get()) and shares ownership with r.
+ Throws: nothing.
+
+ shared_dynamic_cast
+ template<typename T, typename U>
+ weak_ptr<T> shared_dynamic_cast(weak_ptr<U> const & r);
+
+ Requires: The expression dynamic_cast<T*>(r.get())
+ must be well-formed and its behavior defined.
+ Returns:
+
+ -
+ When
dynamic_cast<T*>(r.get()) returns a nonzero
+ value, a weak_ptr<T> object that stores a copy of
+ it and shares ownership with r;
+ -
+ Otherwise, a default-constructed weak_ptr<T> object.
+ Throws: std::bad_alloc.
+ Exception safety: If an exception is thrown, the function has no effect.
+
+ shared_polymorphic_cast
+ template<typename T, typename U>
+ weak_ptr<T> shared_polymorphic_cast(weak_ptr<U> const & r);
+
+ Requires: The expression
+ polymorphic_cast<T*>(r.get()) must be well-formed and
+ its behavior defined.
+ Returns: A weak_ptr<T> object that stores a copy
+ of polymorphic_cast<T*>(r.get())
+ and shares ownership with r.
+ Throws: std::bad_cast when the pointer cannot be
+ converted.
+ Exception safety: If an exception is thrown, the function has no effect.
+
+ shared_polymorphic_downcast
+ template<typename T, typename U>
+ weak_ptr<T> shared_polymorphic_downcast(weak_ptr<U> const & r); // never throws
+
+ Requires: The expression
+ polymorphic_downcast<T*>(r.get()) must be well-formed
+ and its behavior defined.
+ Returns: A weak_ptr<T> object that stores a copy
+ of polymorphic_downcast<T*>(r.get())
+ and shares ownership with r.
+ Throws: nothing.
+
+
+ Revised
+ 8 March 2002
+ Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
+ Copyright 2002 Peter Dimov. 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.
+
+