1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<!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>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.</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 <b>std::less<T *></b> 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 <b>std::less<></b> 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>
|
