From c17f8c36c12246d0beb0ddee4742a898dd74907c Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Fri, 8 Mar 2002 16:56:16 +0000 Subject: [PATCH] weak_ptr::expired() added; weak_ptr documentation updated. [SVN r13141] --- include/boost/weak_ptr.hpp | 7 +- shared_ptr.htm | 4 +- weak_ptr.htm | 416 ++++++++++++++++++++----------------- 3 files changed, 232 insertions(+), 195 deletions(-) diff --git a/include/boost/weak_ptr.hpp b/include/boost/weak_ptr.hpp index 9e9f1a2..33d762d 100644 --- a/include/boost/weak_ptr.hpp +++ b/include/boost/weak_ptr.hpp @@ -97,7 +97,7 @@ public: T * get() const // never throws; unsafe in multithreaded programs! { - return use_count() == 0? 0: px; + return pn.use_count() == 0? 0: px; } long use_count() const // never throws @@ -105,6 +105,11 @@ public: return pn.use_count(); } + bool expired() const // never throws + { + return pn.use_count() == 0; + } + void swap(this_type & other) // never throws { std::swap(px, other.px); diff --git a/shared_ptr.htm b/shared_ptr.htm index 8dbd3a1..49649e2 100644 --- a/shared_ptr.htm +++ b/shared_ptr.htm @@ -297,7 +297,7 @@ q = p; 
template<typename T>
   bool operator<(shared_ptr<T> const & a, shared_ptr<T> const & b); // never throws
-

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;
  • Otherwise, a default-constructed shared_ptr<T> object.

    • 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()))

    diff --git a/weak_ptr.htm b/weak_ptr.htm index 9ef44d4..6c1d5dd 100644 --- a/weak_ptr.htm +++ b/weak_ptr.htm @@ -1,35 +1,25 @@ - - - - -weak_ptr - - - - -

    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 {
+	
+		weak_ptr
+		
+	
+	
+		
    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 {
 
@@ -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.
    
+		
+