forked from boostorg/smart_ptr
Darin Adler
1a7cd887e4
library. Changing includes to include the new individual smart pointer headers. Replacing old smart pointer library with an include of the new smart pointer headers. Simplify ifdefs that involve the member templates macros now that BOOST_MSVC6_MEMBER_TEMPLATES is also guaranteed to bet set for platforms that have full member templates. [SVN r12647]
234 lines
11 KiB
HTML
234 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<title>weak_ptr</title>
|
|
</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>
|
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
<a href="#Synopsis">Synopsis</a><br>
|
|
<a href="#Members">Members</a><br>
|
|
<a href="#functions">Free Functions</a><br>
|
|
<a href="#example">Example</a><br>
|
|
<a href="#Handle/Body">Handle/Body Idiom</a><br>
|
|
<a href="#FAQ">Frequently Asked Questions</a><br>
|
|
<a href="smarttests.htm">Smart Pointer Timings</a></p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>The <b>weak_ptr</b> class template stores a pointer to an
|
|
object that's already managed by a <b>shared_ptr</b>. When the
|
|
object last <b>shared_ptr</b> to the object goes away and the object
|
|
is deleted, all <b>weak_ptr</b> objects have their stored pointers
|
|
set to 0.</p>
|
|
|
|
<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>
|
|
|
|
<h2><a name="Synopsis">Synopsis</a></h2>
|
|
|
|
<pre>namespace boost {
|
|
|
|
template<typename T> class weak_ptr {
|
|
|
|
public:
|
|
typedef T <a href="#element_type">element_type</a>;
|
|
|
|
explicit <a href="#constructors">weak_ptr</a>();
|
|
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
|
|
|
|
void <a href="#reset">reset</a>(); // never throws
|
|
|
|
T & <a href="#indirection">operator*</a>() const; // never throws
|
|
T * <a href="#indirection">operator-></a>() const; // never throws
|
|
T * <a href="#get">get</a>() const; // never throws
|
|
|
|
long <a href="#use_count">use_count</a>() const; // never throws
|
|
|
|
void <a href="#swap">swap</a>(weak_ptr<T> & b); // never throws
|
|
};
|
|
|
|
template<typename T, typename U>
|
|
bool <a href="#operator==">operator==</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
|
template<typename T, typename U>
|
|
bool <a href="#operator!=">operator!=</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
|
template<typename T, typename U>
|
|
bool <a href="#operator<">operator<</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
|
|
|
template<typename T> void <a href="#free-swap">swap</a>(weak_ptr<T> & a, weak_ptr<T> & b); // never throws
|
|
|
|
template<typename T, typename U>
|
|
weak_ptr<T> <a href="#shared_static_cast">shared_static_cast</a>(weak_ptr<U> const & r); // never throws
|
|
template<typename T, typename U>
|
|
weak_ptr<T> <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(weak_ptr<U> const & r);
|
|
|
|
}</pre>
|
|
|
|
<h2><a name="Members">Members</a></h2>
|
|
|
|
<h3><a name="element_type">element_type</a></h3>
|
|
<pre>typedef T element_type;</pre>
|
|
<p>Provides the type of the stored pointer.</p>
|
|
|
|
<h3><a name="constructors">constructors</a></h3>
|
|
|
|
<pre>explicit weak_ptr();</pre>
|
|
<p>Constructs a <b>weak_ptr</b>, with 0 as its stored pointer.
|
|
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
|
|
If an exception is thrown, the constructor has no effect.</p>
|
|
|
|
<pre>template<typename Y> weak_ptr</a>(shared_ptr<Y> const & r); // never throws</pre>
|
|
<p>Constructs a <b>weak_ptr</b>, as if by storing a copy of the pointer stored in <b>r</b>.
|
|
Afterwards, 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.
|
|
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
|
|
If an exception is thrown, the constructor has no effect.</p>
|
|
|
|
<pre>weak_ptr(weak_ptr const & r); // never throws
|
|
template<typename Y> weak_ptr(weak_ptr<Y> const & r); // never throws</pre>
|
|
<p>Constructs a <b>weak_ptr</b>, as if by storing a copy of the
|
|
pointer stored in <b>r</b>.</p>
|
|
|
|
<h3><a name="destructor">destructor</a></h3>
|
|
|
|
<pre>~weak_ptr(); // never throws</pre>
|
|
<p>Destroys this <b>weak_ptr</b> but has no effect on the object its stored pointer points to.
|
|
<b>T</b> need not be a complete type.
|
|
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
|
|
|
<h3><a name="operator=">assignment</a></h3>
|
|
|
|
<pre>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</pre>
|
|
<p>Constructs a new <b>weak_ptr</b> as described <a href="#constructors">above</a>,
|
|
then replaces this <b>weak_ptr</b> with the new one, destroying the replaced object.</p>
|
|
|
|
<h3><a name="reset">reset</a></h3>
|
|
|
|
<pre>void reset();</pre>
|
|
<p>Constructs a new <b>weak_ptr</b> as described <a href="#constructors">above</a>,
|
|
then replaces this <b>weak_ptr</b> with the new one, destroying the replaced object.
|
|
The only exception which may be thrown is <b>std::bad_alloc</b>. If
|
|
an exception is thrown, the <b>reset</b> has no effect.</p>
|
|
|
|
<h3><a name="indirection">indirection</a></h3>
|
|
|
|
<pre>T & operator*() const; // never throws</pre>
|
|
<p>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 <b>shared_ptr</b> objects for that
|
|
pointer are destroyed.</p>
|
|
|
|
<pre>T * operator->() const; // never throws</pre>
|
|
<p>Returns the stored pointer.
|
|
Behavior is undefined if the stored pointer is 0.
|
|
Note that the stored pointer becomes 0 if all <b>shared_ptr</b> objects for that
|
|
pointer are destroyed.</p>
|
|
|
|
<h3><a name="get">get</a></h3>
|
|
<pre>T * get() const; // never throws</pre>
|
|
<p>Returns the stored pointer.
|
|
Note that the stored pointer becomes 0 if all <b>shared_ptr</b> objects for that
|
|
pointer are destroyed.
|
|
<b>T</b> need not be a complete type.
|
|
See the smart pointer
|
|
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
|
|
|
<h3><a name="use_count">use_count</a></h3>
|
|
<pre>long use_count() const; // never throws</pre>
|
|
<p>Returns the number of <b>shared_ptr</b> objects sharing ownership of the
|
|
stored pointer.
|
|
<b>T</b> need not be a complete type.
|
|
See the smart pointer
|
|
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
|
<p>Because <b>use_count</b> is not necessarily efficient to implement for
|
|
implementations of <b>weak_ptr</b> 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 <b>get</b> should be used for
|
|
production code.</p>
|
|
|
|
<h3><a name="swap">swap</a></h3>
|
|
<pre>void swap(weak_ptr & b); // never throws</pre>
|
|
<p>Exchanges the contents of the two smart pointers.
|
|
<b>T</b> need not be a complete type.
|
|
See the smart pointer
|
|
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
|
|
|
<h2><a name="functions">Free Functions</a></h2>
|
|
|
|
<h3><a name="comparison">comparison</a></h3>
|
|
<pre>template<typename T, typename U>
|
|
bool <a href="#operator==">operator==</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
|
template<typename T, typename U>
|
|
bool <a href="#operator!=">operator!=</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws
|
|
template<typename T, typename U>
|
|
bool <a href="#operator<">operator<</a>(weak_ptr<T> const & a, weak_ptr<U> const & b); // never throws</pre>
|
|
<p>Compares the stored pointers of the two smart pointers.
|
|
<b>T</b> need not be a complete type.
|
|
See the smart pointer
|
|
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
|
<p>The <b>operator<</b> overload is provided to define an ordering so that <b>weak_ptr</b>
|
|
objects can be used in associative containers such as <b>std::map</b>.
|
|
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).</p>
|
|
|
|
<h3><a name="free-swap">swap</a></h3>
|
|
<pre>template<typename T>
|
|
void swap(weak_ptr<T> & a, weak_ptr<T> & b) // never throws</pre>
|
|
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
|
Provided as an aid to generic programming.</p>
|
|
|
|
<h3><a name="shared_static_cast">shared_static_cast</a></h3>
|
|
<pre>template<typename T, typename U>
|
|
weak_ptr<T> <a href="#shared_static_cast">shared_static_cast</a>(weak_ptr<U> const & r); // never throws</pre>
|
|
<p>Perform a <b>static_cast</b> on the stored pointer, returning another <b>weak_ptr</b>.
|
|
The resulting smart pointer will share its use count with the original pointer.</p>
|
|
|
|
<h3><a name="shared_dynamic_cast">shared_dynamic_cast</a></h3>
|
|
<pre>template<typename T, typename U>
|
|
weak_ptr<T> <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(weak_ptr<U> const & r);</pre>
|
|
<p>Perform a <b>dynamic_cast</b> on the stored pointer, returning another <b>weak_ptr</b>.
|
|
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 <b>std::bad_alloc</b>, which may be thrown during the
|
|
construction of the new <b>weak_ptr</b> if the result of the cast is 0. If an exception is thrown, the
|
|
cast has no effect.</p>
|
|
|
|
<hr>
|
|
|
|
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
|
|
|
|
<p>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.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|