diff --git a/include/boost/weak_ptr.hpp b/include/boost/weak_ptr.hpp index e04b4f1..c76cb28 100644 --- a/include/boost/weak_ptr.hpp +++ b/include/boost/weak_ptr.hpp @@ -76,7 +76,7 @@ public: this_type().swap(*this); } - T * get() const // never throws; unsafe in multithreaded programs! + T * get() const // never throws; deprecated, removal pending, don't use { return pn.use_count() == 0? 0: px; } @@ -168,6 +168,10 @@ template shared_ptr make_shared(weak_ptr const & r) // never thro } } +// Note: there is no get_pointer overload for weak_ptr. +// This is intentional. Even get() will disappear in a +// future release; these accessors are too error-prone. + } // namespace boost #ifdef BOOST_MSVC diff --git a/weak_ptr.htm b/weak_ptr.htm index 8e284d1..92bc284 100644 --- a/weak_ptr.htm +++ b/weak_ptr.htm @@ -7,10 +7,15 @@

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 last shared_ptr to the object - goes away and the object is deleted, all weak_ptr objects have their - stored pointers set to 0.

+

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 function + make_shared. 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 boost::use_count_is_zero, + and make_shared will return a default constructed (null) 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 @@ -20,8 +25,9 @@ common requirements.

Compared to shared_ptr, weak_ptr provides a very limited subset of operations since accessing its stored pointer is - unsafe in multithreaded programs (that is, it may invoke undefined - behavior.) Consider, for example, this innocent piece of code:

+ often dangerous in multithreaded programs, and sometimes unsafe even + within a single thread (that is, it may invoke undefined behavior.) + Consider, for example, this innocent piece of code:

 shared_ptr<int> p(new int(5));
 weak_ptr<int> q(p);
@@ -72,7 +78,7 @@ if(shared_ptr<int> r = make_shared(q))
       template<typename Y> weak_ptr & operator=(shared_ptr<Y> const & r); // never throws
 
       void reset();
-      T * get() const; // never throws; unsafe in multithreaded code!
+      T * get() const; // never throws; deprecated, will disappear
 
       long use_count() const; // never throws
       bool expired() const; // never throws
@@ -164,6 +170,11 @@ template<typename Y> weak_ptr & operator=(sh
 				function returns, the pointed-to object may be destroyed by a different thread, 
 				since the weak_ptr doesn't affect its use_count.

 		
+		
[get is very error-prone. Even single-threaded code may experience 
+				problems, as the returned pointer may be invalidated at any time, for example, 
+				indirectly by a member function of the pointee.

+		
get is deprecated, and it will disappear in a future 
+				release. Do not use it.]

 		
use_count

 		
long use_count() const; // never throws

 		

@@ -231,8 +242,12 @@ template<typename T, typename U>
 			
Returns: r.expired()? shared_ptr<T>(): shared_ptr<T>(r).

 			
Throws: nothing.

 		

+		
[The current implementation of make_shared can propagate 
+				an exception thrown by the shared_ptr default 
+				constructor, so it doesn't meet the stated requirements. In a future 
+				release, this default constructor will not throw.]

 		

-		
Revised 12 March 2002

+		
Revised 29 August 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