Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/smart_ptr/weak_ptr.htm @ 35

Last change on this file since 35 was 29, checked in by landauf, 16 years ago
updated boost from 1_33_1 to 1_34_1
File size: 10.8 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2	<html>
3	<head>
4	<title>weak_ptr</title>
5	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6	</head>
7	<body text="#000000" bgColor="#ffffff">
8	<h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle"
9	border="0"></A>weak_ptr class template</h1>
10	<p><A href="#Introduction">Introduction</A><br>
11	<A href="#Synopsis">Synopsis</A><br>
12	<A href="#Members">Members</A><br>
13	<A href="#functions">Free Functions</A><br>
14	<A href="#FAQ">Frequently Asked Questions</A>
15	</p>
16	<h2><a name="Introduction">Introduction</a></h2>
17	<p>The <b>weak_ptr</b> class template stores a "weak reference" to an object that's
18	already managed by a <b>shared_ptr</b>. To access the object, a <STRONG>weak_ptr</STRONG>
19	can be converted to a <STRONG>shared_ptr</STRONG> using <A href="shared_ptr.htm#constructors">
20	the <STRONG>shared_ptr</STRONG> constructor</A> or the member function <STRONG><A href="#lock">
21	lock</A></STRONG>. When the last <b>shared_ptr</b> to the object goes
22	away and the object is deleted, the attempt to obtain a <STRONG>shared_ptr</STRONG>
23	from the <b>weak_ptr</b> instances that refer to the deleted object will fail:
24	the constructor will throw an exception of type <STRONG>boost::bad_weak_ptr</STRONG>,
25	and <STRONG>weak_ptr::lock</STRONG> will return an <EM>empty</EM> <STRONG>shared_ptr</STRONG>.</p>
26	<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> requirements
27	of the C++ Standard Library, and so can be used in standard library containers.
28	Comparison operators are supplied so that <b>weak_ptr</b> works with the
29	standard library's associative containers.</p>
30	<P><STRONG>weak_ptr</STRONG> operations never throw exceptions.</P>
31	<p>The class template is parameterized on <b>T</b>, the type of the object pointed
32	to.</p>
33	<P>Compared to <STRONG>shared_ptr</STRONG>, <STRONG>weak_ptr</STRONG> provides a
34	very limited subset of operations since accessing its stored pointer is often
35	dangerous in multithreaded programs, and sometimes unsafe even within a single
36	thread (that is, it may invoke undefined behavior.) Pretend for a moment that <b>weak_ptr</b>
37	has a <b>get</b> member function that returns a raw pointer, and consider this
38	innocent piece of code:</P>
39	<pre>shared_ptr<int> p(new int(5));
40	weak_ptr<int> q(p);
41
42	// some time later
43
44	if(int * r = q.get())
45	{
46	// use *r
47	}
48	</pre>
49	<P>Imagine that after the <STRONG>if</STRONG>, but immediately before <STRONG>r</STRONG>
50	is used, another thread executes the statement <code>p.reset()</code>. Now <STRONG>r</STRONG>
51	is a dangling pointer.</P>
52	<P>The solution to this problem is to create a temporary <STRONG>shared_ptr</STRONG>
53	from <STRONG>q</STRONG>:</P>
54	<pre>shared_ptr<int> p(new int(5));
55	weak_ptr<int> q(p);
56
57	// some time later
58
59	if(shared_ptr<int> r = q.<A href="#lock" >lock</A>())
60	{
61	// use *r
62	}
63	</pre>
64	<p>Now <STRONG>r</STRONG> holds a reference to the object that was pointed by <STRONG>q</STRONG>.
65	Even if <code>p.reset()</code> is executed in another thread, the object will
66	stay alive until <STRONG>r</STRONG> goes out of scope or is reset. By obtaining
67	a <STRONG>shared_ptr</STRONG> to the object, we have effectively locked it
68	against destruction.</p>
69	<h2><a name="Synopsis">Synopsis</a></h2>
70	<pre>namespace boost {
71
72	template<class T> class weak_ptr {
73
74	public:
75	typedef T <A href="#element_type" >element_type</A>;
76
77	<A href="#default-constructor" >weak_ptr</A>();
78
79	template<class Y> <A href="#constructors" >weak_ptr</A>(shared_ptr<Y> const & r);
80	<A href="#constructors" >weak_ptr</A>(weak_ptr const & r);
81	template<class Y> <A href="#constructors" >weak_ptr</A>(weak_ptr<Y> const & r);
82
83	<A href="#destructor" >~weak_ptr</A>();
84
85	weak_ptr & <A href="#assignment" >operator=</A>(weak_ptr const & r);
86	template<class Y> weak_ptr & <A href="#assignment" >operator=</A>(weak_ptr<Y> const & r);
87	template<class Y> weak_ptr & <A href="#assignment" >operator=</A>(shared_ptr<Y> const & r);
88
89	long <A href="#use_count" >use_count</A>() const;
90	bool <A href="#expired" >expired</A>() const;
91	shared_ptr<T> <A href="#lock" >lock</A>() const;
92
93	void <A href="#reset" >reset</A>();
94	void <A href="#swap" >swap</A>(weak_ptr<T> & b);
95	};
96
97	template<class T, class U>
98	bool <A href="#comparison" >operator<</A>(weak_ptr<T> const & a, weak_ptr<U> const & b);
99
100	template<class T>
101	void <A href="#free-swap" >swap</A>(weak_ptr<T> & a, weak_ptr<T> & b);
102	}
103	</pre>
104	<h2><a name="Members">Members</a></h2>
105	<h3><a name="element_type">element_type</a></h3>
106	<pre>typedef T element_type;</pre>
107	<blockquote>
108	<p>Provides the type of the template parameter T.</p>
109	</blockquote>
110	<h3><a name="default-constructor">constructors</a></h3>
111	<pre>weak_ptr();</pre>
112	<blockquote>
113	<p><b>Effects:</b> Constructs an <EM>empty</EM> <b>weak_ptr</b>.</p>
114	<p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
115	<p><b>Throws:</b> nothing.</p>
116	</blockquote><a name="constructors"></a>
117	<pre>template<class Y> weak_ptr</A>(shared_ptr<Y> const & r);
118	weak_ptr(weak_ptr const & r);
119	template<class Y> weak_ptr(weak_ptr<Y> const & r);</pre>
120	<blockquote>
121	<p><b>Effects:</b> If <STRONG>r</STRONG> is <EM>empty</EM>, constructs an <EM>empty</EM>
122	<STRONG>weak_ptr</STRONG>; otherwise, constructs a <b>weak_ptr</b> that <EM>shares
123	ownership</EM> with <STRONG>r</STRONG> as if by storing a copy of the
124	pointer stored in <b>r</b>.</p>
125	<p><b>Postconditions:</b> <code>use_count() == r.use_count()</code>.</p>
126	<p><b>Throws:</b> nothing.</p>
127	</blockquote>
128	<h3><a name="destructor">destructor</a></h3>
129	<pre>~weak_ptr();</pre>
130	<BLOCKQUOTE>
131	<P><B>Effects:</B> Destroys this <b>weak_ptr</b> but has no effect on the object
132	its stored pointer points to.</P>
133	<P><B>Throws:</B> nothing.</P>
134	</BLOCKQUOTE>
135	<h3><a name="assignment">assignment</a></h3>
136	<pre>weak_ptr & operator=(weak_ptr const & r);
137	template<class Y> weak_ptr & operator=(weak_ptr<Y> const & r);
138	template<class Y> weak_ptr & operator=(shared_ptr<Y> const & r);</pre>
139	<BLOCKQUOTE>
140	<P><B>Effects:</B> Equivalent to <code>weak_ptr(r).swap(*this)</code>.</P>
141	<P><B>Throws:</B> nothing.</P>
142	<P><B>Notes:</B> The implementation is free to meet the effects (and the implied
143	guarantees) via different means, without creating a temporary.</P>
144	</BLOCKQUOTE>
145	<h3><a name="use_count">use_count</a></h3>
146	<pre>long use_count() const;</pre>
147	<blockquote>
148	<p><b>Returns:</b> 0 if <STRONG>*this</STRONG> is <EM>empty</EM>; otherwise, the
149	number of <b>shared_ptr</b> objects that <EM>share ownership</EM> with <STRONG>*this</STRONG>.</p>
150	<p><b>Throws:</b> nothing.</p>
151	<P><B>Notes:</B> <code>use_count()</code> is not necessarily efficient. Use only
152	for debugging and testing purposes, not for production code.</P>
153	</blockquote>
154	<h3><a name="expired">expired</a></h3>
155	<pre>bool expired() const;</pre>
156	<blockquote>
157	<p><b>Returns:</b> <code>use_count() == 0</code>.</p>
158	<p><b>Throws:</b> nothing.</p>
159	<P><B>Notes:</B> <code>expired()</code> may be faster than <code>use_count()</code>.</P>
160	</blockquote>
161	<h3><a name="lock">lock</a></h3>
162	<pre>shared_ptr<T> lock() const;</pre>
163	<BLOCKQUOTE>
164	<P><B>Returns:</B> <code>expired()? shared_ptr<T>(): shared_ptr<T>(*this)</code>.</P>
165	<P><B>Throws:</B> nothing.</P>
166	</BLOCKQUOTE>
167	<h3><a name="reset">reset</a></h3>
168	<pre>void reset();</pre>
169	<BLOCKQUOTE>
170	<P><B>Effects:</B> Equivalent to <code>weak_ptr().swap(*this)</code>.</P>
171	</BLOCKQUOTE>
172	<h3><a name="swap">swap</a></h3>
173	<pre>void swap(weak_ptr & b);</pre>
174	<blockquote>
175	<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
176	<p><b>Throws:</b> nothing.</p>
177	</blockquote>
178	<h2><a name="functions">Free Functions</a></h2>
179	<h3><a name="comparison">comparison</a></h3>
180	<pre>template<class T, class U>
181	bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b);</pre>
182	<blockquote>
183	<p><b>Returns:</b> an unspecified value such that</p>
184	<UL>
185	<LI>
186	<b>operator<</b> is a strict weak ordering as described in section 25.3 <code>[lib.alg.sorting]</code>
187	of the C++ standard;
188	<LI>
189	under the equivalence relation defined by <STRONG>operator<</STRONG>, <code>!(a
190	< b) && !(b < a)</code>, two <STRONG>weak_ptr</STRONG> instances
191	are equivalent if and only if they <EM>share ownership</EM> or are both <EM>empty</EM>.</LI></UL>
192	<p><b>Throws:</b> nothing.</p>
193	<P><B>Notes:</B> Allows <STRONG>weak_ptr</STRONG> objects to be used as keys in
194	associative containers.</P>
195	</blockquote>
196	<h3><a name="free-swap">swap</a></h3>
197	<pre>template<class T>
198	void swap(weak_ptr<T> & a, weak_ptr<T> & b)</pre>
199	<BLOCKQUOTE>
200	<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
201	<P><B>Throws:</B> nothing.</P>
202	<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
203	generic programming.</P>
204	</BLOCKQUOTE>
205	<h2><a name="FAQ">Frequently Asked Questions</a></h2>
206	<P><B>Q.</B> Can an object create a <STRONG>weak_ptr</STRONG> to itself in its
207	constructor?</P>
208	<P><b>A.</b> No. A <STRONG>weak_ptr</STRONG> can only be created from a <STRONG>shared_ptr</STRONG>,
209	and at object construction time no <STRONG>shared_ptr</STRONG> to the object
210	exists yet. Even if you could create a temporary <STRONG>shared_ptr</STRONG> to <STRONG>
211	this</STRONG>, it would go out of scope at the end of the constructor, and
212	all <STRONG>weak_ptr</STRONG> instances would instantly expire.</P>
213	<P>The solution is to make the constructor private, and supply a factory function
214	that returns a <STRONG>shared_ptr</STRONG>:<BR>
215	</P>
216	<pre>
217	class X
218	{
219	private:
220
221	X();
222
223	public:
224
225	static shared_ptr<X> create()
226	{
227	shared_ptr<X> px(new X);
228	// create weak pointers from px here
229	return px;
230	}
231	};
232	</pre>
233	<p><br>
234	</p>
235	<hr>
236	<p>$Date: 2005/09/25 21:54:19 $</p>
237	<p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
238	Copyright 2002-2005 Peter Dimov. Permission to copy, use, modify, sell and
239	distribute this document is granted provided this copyright notice appears in
240	all copies. This document is provided "as is" without express or implied
241	warranty, and with no claim as to its suitability for any purpose.</small></p>
242	</A>
243	</body>
244	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: