2002-02-02 18:36:12 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
|
<html>
|
2002-03-08 16:56:16 +00:00
|
|
|
<head>
|
|
|
|
|
<title>weak_ptr</title>
|
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
|
|
|
</head>
|
|
|
|
|
<body bgcolor="#ffffff" text="#000000">
|
|
|
|
|
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">weak_ptr
|
|
|
|
|
class template</h1>
|
2002-08-29 15:18:04 +00:00
|
|
|
<p>The <b>weak_ptr</b> class template stores a "weak reference" to an
|
|
|
|
|
object that's already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>
|
|
|
|
|
weak_ptr</STRONG> can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
|
|
|
|
|
the <STRONG>shared_ptr</STRONG> constructor</A> or the function <STRONG><A href="#make_shared">
|
|
|
|
|
make_shared</A></STRONG>. When the last <b>shared_ptr</b> to the object
|
|
|
|
|
goes away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
|
|
|
|
|
from the <b>weak_ptr</b> instances that refer to the deleted object will
|
|
|
|
|
fail: the constructor will throw an exception of type <STRONG>boost::use_count_is_zero</STRONG>,
|
|
|
|
|
and <STRONG>make_shared</STRONG> will return a default constructed (null) <STRONG>shared_ptr</STRONG>.</p>
|
2002-03-08 16:56:16 +00:00
|
|
|
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
|
|
|
|
|
of the C++ Standard Library, and so can be used in standard library containers.
|
|
|
|
|
Comparison operators are supplied so that <b>weak_ptr</b> works with the
|
|
|
|
|
standard library's associative containers.</p>
|
|
|
|
|
<p>The class template is parameterized on <b>T</b>, the type of the object pointed
|
|
|
|
|
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</a>.</p>
|
2002-03-12 14:39:22 +00:00
|
|
|
<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides
|
|
|
|
|
a very limited subset of operations since accessing its stored pointer is
|
2002-08-29 15:18:04 +00:00
|
|
|
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:</P>
|
2002-03-12 14:39:22 +00:00
|
|
|
<pre>
|
|
|
|
|
shared_ptr<int> p(new int(5));
|
|
|
|
|
weak_ptr<int> q(p);
|
|
|
|
|
|
|
|
|
|
// some time later
|
|
|
|
|
|
|
|
|
|
if(int * r = q.get())
|
|
|
|
|
{
|
2002-07-15 12:52:29 +00:00
|
|
|
// use *r
|
2002-03-12 14:39:22 +00:00
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
<P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG>
|
|
|
|
|
is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG>
|
|
|
|
|
is a dangling pointer.</P>
|
|
|
|
|
<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
|
|
|
|
|
from <STRONG>q</STRONG>:</P>
|
|
|
|
|
<pre>
|
|
|
|
|
shared_ptr<int> p(new int(5));
|
|
|
|
|
weak_ptr<int> q(p);
|
|
|
|
|
|
|
|
|
|
// some time later
|
|
|
|
|
|
|
|
|
|
if(shared_ptr<int> r = <a href="#make_shared">make_shared</a>(q))
|
|
|
|
|
{
|
2002-07-15 12:52:29 +00:00
|
|
|
// use *r
|
2002-03-12 14:39:22 +00:00
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
|
|
|
|
|
Even if <code>p.reset()</code> is executed in another thread, the object will
|
|
|
|
|
stay alive until <STRONG>r</STRONG> goes out of scope (or is reset.)</p>
|
2002-03-08 16:56:16 +00:00
|
|
|
<h2><a name="Synopsis">Synopsis</a></h2>
|
|
|
|
|
<pre>namespace boost {
|
2002-02-02 18:36:12 +00:00
|
|
|
|
|
|
|
|
template<typename T> class weak_ptr {
|
|
|
|
|
|
|
|
|
|
public:
|
|
|
|
|
typedef T <a href="#element_type">element_type</a>;
|
|
|
|
|
|
2002-02-09 01:18:00 +00:00
|
|
|
<a href="#constructors">weak_ptr</a>();
|
2002-02-02 18:36:12 +00:00
|
|
|
template<typename Y> <a href="#constructors">weak_ptr</a>(shared_ptr<Y> const & r); // never throws
|
|
|
|
|
<a href="#destructor">~weak_ptr</a>(); // never throws
|
|
|
|
|
|
|
|
|
|
<a href="#constructors">weak_ptr</a>(weak_ptr const & r); // never throws
|
|
|
|
|
template<typename Y> <a href="#constructors">weak_ptr</a>(weak_ptr<Y> const & r); // never throws
|
|
|
|
|
|
|
|
|
|
weak_ptr & <a href="#assignment">operator=</a>(weak_ptr const & r); // never throws
|
|
|
|
|
template<typename Y> weak_ptr & <a href="#assignment">operator=</a>(weak_ptr<Y> const & r); // never throws
|
|
|
|
|
template<typename Y> weak_ptr & <a href="#assignment">operator=</a>(shared_ptr<Y> const & r); // never throws
|
|
|
|
|
|
2002-02-08 20:45:04 +00:00
|
|
|
void <a href="#reset">reset</a>();
|
2002-08-29 15:18:04 +00:00
|
|
|
T * <a href="#get">get</a>() const; // never throws; deprecated, will disappear
|
2002-02-02 18:36:12 +00:00
|
|
|
|
|
|
|
|
long <a href="#use_count">use_count</a>() const; // never throws
|
2002-03-08 16:56:16 +00:00
|
|
|
bool <a href="#expired">expired</a>() const; // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
|
|
|
|
|
void <a href="#swap">swap</a>(weak_ptr<T> & b); // never throws
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
template<typename T, typename U>
|
2002-02-09 01:18:00 +00:00
|
|
|
bool <a href="#comparison">operator==</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
template<typename T, typename U>
|
2002-02-09 01:18:00 +00:00
|
|
|
bool <a href="#comparison">operator!=</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
2002-02-08 20:45:04 +00:00
|
|
|
template<typename T>
|
2002-02-09 01:18:00 +00:00
|
|
|
bool <a href="#comparison">operator<</a>(weak_ptr<T> const & a, weak_ptr<T> const & b); // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
|
|
|
|
|
template<typename T> void <a href="#free-swap">swap</a>(weak_ptr<T> & a, weak_ptr<T> & b); // never throws
|
|
|
|
|
|
2002-03-08 16:56:16 +00:00
|
|
|
template<typename T>
|
|
|
|
|
shared_ptr<T> <a href="#make_shared">make_shared</a>(weak_ptr<T> const & r); // never throws
|
|
|
|
|
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
<h2><a name="Members">Members</a></h2>
|
|
|
|
|
<h3><a name="element_type">element_type</a></h3>
|
|
|
|
|
<pre>typedef T element_type;</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p>Provides the type of the template parameter T.</p>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h3><a name="constructors">constructors</a></h3>
|
2002-07-15 12:52:29 +00:00
|
|
|
<pre> weak_ptr();</pre>
|
2002-03-08 16:56:16 +00:00
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Effects:</b> Constructs a <b>weak_ptr</b>.</p>
|
|
|
|
|
<p><b>Postconditions:</b> <A href="#use_count">use count</A> is 0; the stored
|
|
|
|
|
pointer is 0.</p>
|
|
|
|
|
<p><b>Throws:</b> <b>std::bad_alloc</b>.</p>
|
|
|
|
|
<p><b>Exception safety:</b> If an exception is thrown, the constructor has no
|
|
|
|
|
effect.</p>
|
|
|
|
|
<P><B>Notes:</B> <B>T</B> need not be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<pre>template<typename Y> weak_ptr</A>(shared_ptr<Y> const & r); // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Effects:</b> Constructs a <b>weak_ptr</b>, as if by storing a copy of the
|
|
|
|
|
pointer stored in <b>r</b>.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> The <a href="#use_count">use count</a> for all copies is
|
|
|
|
|
unchanged. When the last <b>shared_ptr</b> is destroyed, the use count and
|
|
|
|
|
stored pointer become 0.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<pre>weak_ptr(weak_ptr const & r); // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
template<typename Y> weak_ptr(weak_ptr<Y> const & r); // never throws</pre>
|
2002-03-08 16:56:16 +00:00
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Effects:</b> Constructs a <b>weak_ptr</b>, as if by storing a copy of the
|
|
|
|
|
pointer stored in <b>r</b>.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> The <a href="#use_count">use count</a> for all copies is
|
|
|
|
|
unchanged.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h3><a name="destructor">destructor</a></h3>
|
|
|
|
|
<pre>~weak_ptr(); // never throws</pre>
|
|
|
|
|
<BLOCKQUOTE>
|
|
|
|
|
<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
|
|
|
|
|
its stored pointer points to.</P>
|
|
|
|
|
<P><B>Throws:</B> nothing.</P>
|
|
|
|
|
<P><B>Notes:</B> <B>T</B> need not be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</BLOCKQUOTE>
|
|
|
|
|
<h3><a name="assignment">assignment</a></h3>
|
|
|
|
|
<pre>weak_ptr & <a href="#assignment">operator=</a>(weak_ptr const & r); // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
template<typename Y> weak_ptr & <a href="#assignment">operator=</a>(weak_ptr<Y> const & r); // never throws
|
|
|
|
|
template<typename Y> weak_ptr & <a href="#assignment">operator=</a>(shared_ptr<Y> const & r); // never throws</pre>
|
2002-03-08 16:56:16 +00:00
|
|
|
<BLOCKQUOTE>
|
|
|
|
|
<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
|
|
|
|
|
<P><B>Throws:</B> nothing.</P>
|
|
|
|
|
<P><B>Notes:</B> The implementation is free to meet the effects (and the implied
|
|
|
|
|
guarantees) via different means, without creating a temporary.</P>
|
|
|
|
|
</BLOCKQUOTE>
|
|
|
|
|
<h3><a name="reset">reset</a></h3>
|
|
|
|
|
<pre>void reset();</pre>
|
|
|
|
|
<BLOCKQUOTE>
|
|
|
|
|
<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
|
|
|
|
|
</BLOCKQUOTE>
|
|
|
|
|
<h3><a name="get">get</a></h3>
|
|
|
|
|
<pre>T * get() const; // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Returns:</b> the stored pointer (0 if all <b>shared_ptr</b> objects for that
|
|
|
|
|
pointer are destroyed.)</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> Using <b>get</b> in multithreaded code is dangerous. After the
|
|
|
|
|
function returns, the pointed-to object may be destroyed by a different thread,
|
|
|
|
|
since the <b>weak_ptr</b> doesn't affect its <b>use_count</b>.</P>
|
|
|
|
|
</blockquote>
|
2002-08-29 15:18:04 +00:00
|
|
|
<P><EM>[<b>get</b> 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.</EM></P>
|
|
|
|
|
<P><EM><STRONG>get</STRONG> is deprecated, and it will disappear in a future
|
|
|
|
|
release. Do not use it.]</EM></P>
|
2002-03-08 16:56:16 +00:00
|
|
|
<h3><a name="use_count">use_count</a></h3>
|
|
|
|
|
<pre>long use_count() const; // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Returns:</b> the number of <b>shared_ptr</b> objects sharing ownership of the
|
|
|
|
|
stored pointer.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
|
|
|
|
|
for debugging and testing purposes, not for production code. <B>T</B> need not
|
|
|
|
|
be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h3><a name="expired">expired</a></h3>
|
|
|
|
|
<pre>bool expired() const; // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Returns:</b> <code>use_count() == 0</code>.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.
|
|
|
|
|
<B>T</B> need not be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h3><a name="swap">swap</a></h3>
|
|
|
|
|
<pre>void swap(weak_ptr & b); // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> <B>T</B> need not be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h2><a name="functions">Free Functions</a></h2>
|
|
|
|
|
<h3><a name="comparison">comparison</a></h3>
|
|
|
|
|
<pre>template<typename T, typename U>
|
2002-02-09 01:18:00 +00:00
|
|
|
bool operator==(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
2002-02-02 18:36:12 +00:00
|
|
|
template<typename T, typename U>
|
2002-03-08 16:56:16 +00:00
|
|
|
bool operator!=(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws</pre>
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> <B>T</B> need not be a complete type. See the smart pointer <A href="smart_ptr.htm#Common requirements">
|
|
|
|
|
common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<pre>template<typename T>
|
2002-02-09 01:18:00 +00:00
|
|
|
bool operator<(weak_ptr<T> const & a, weak_ptr<T> const & b); // never throws</pre>
|
2002-03-08 16:56:16 +00:00
|
|
|
<blockquote>
|
|
|
|
|
<p><b>Returns:</b> an implementation-defined value such that <b>operator<</b> is
|
|
|
|
|
a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
|
|
|
|
|
of the C++ standard.</p>
|
|
|
|
|
<p><b>Throws:</b> nothing.</p>
|
|
|
|
|
<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
|
|
|
|
|
associative containers. <B>T</B> need not be a complete type. See the smart
|
|
|
|
|
pointer <A href="smart_ptr.htm#Common requirements">common requirements</A>.</P>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<h3><a name="free-swap">swap</a></h3>
|
|
|
|
|
<pre>template<typename T>
|
2002-02-02 18:36:12 +00:00
|
|
|
void swap(weak_ptr<T> & a, weak_ptr<T> & b) // never throws</pre>
|
2002-03-08 16:56:16 +00:00
|
|
|
<BLOCKQUOTE>
|
|
|
|
|
<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
|
|
|
|
|
<P><B>Throws:</B> nothing.</P>
|
|
|
|
|
<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
|
|
|
|
|
generic programming.</P>
|
|
|
|
|
</BLOCKQUOTE>
|
|
|
|
|
<h3><a name="make_shared">make_shared</a></h3>
|
|
|
|
|
<pre>template<typename T>
|
|
|
|
|
shared_ptr<T> make_shared(weak_ptr<T> & const r) // never throws</pre>
|
|
|
|
|
<BLOCKQUOTE>
|
|
|
|
|
<P><B>Returns:</B> <code>r.expired()? shared_ptr<T>(): shared_ptr<T>(r)</code>.</P>
|
|
|
|
|
<P><B>Throws:</B> nothing.</P>
|
|
|
|
|
</BLOCKQUOTE>
|
2002-08-29 15:18:04 +00:00
|
|
|
<P><EM>[The current implementation of <STRONG>make_shared</STRONG> can propagate
|
|
|
|
|
an exception thrown by the <STRONG>shared_ptr</STRONG> default
|
|
|
|
|
constructor, so it doesn't meet the stated requirements</EM><EM>. In a future
|
|
|
|
|
release, this default constructor will not throw.]</EM></P>
|
2002-03-08 16:56:16 +00:00
|
|
|
<hr>
|
2002-08-29 15:18:04 +00:00
|
|
|
<p>Revised 29 August 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
|
2002-03-08 16:56:16 +00:00
|
|
|
<p>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.</p>
|
|
|
|
|
</A>
|
|
|
|
|
</body>
|
2002-02-02 18:36:12 +00:00
|
|
|
</html>
|
