Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/libs/smart_ptr/intrusive_ptr.html @ 14

Last change on this file since 14 was 12, checked in by landauf, 17 years ago
added boost
File size: 13.5 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2	<html>
3	<head>
4	<title>intrusive_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><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle">intrusive_ptr
9	class template</h1>
10	<p>
11	<A href="#Introduction">Introduction</A><br>
12	<A href="#Synopsis">Synopsis</A><br>
13	<A href="#Members">Members</A><br>
14	<A href="#functions">Free Functions</A><br>
15	</p>
16	<h2><a name="Introduction">Introduction</a></h2>
17	<p>The <b>intrusive_ptr</b> class template stores a pointer to an object with an
18	embedded reference count. Every new <b>intrusive_ptr</b> instance increments
19	the reference count by using an unqualified call to the function <STRONG>intrusive_ptr_add_ref</STRONG>,
20	passing it the pointer as an argument. Similarly, when an <STRONG>intrusive_ptr</STRONG>
21	is destroyed, it calls <STRONG>intrusive_ptr_release</STRONG>; this function is
22	responsible for destroying the object when its reference count drops to zero.
23	The user is expected to provide suitable definitions of these two functions. On
24	compilers that support argument-dependent lookup, <STRONG>intrusive_ptr_add_ref</STRONG>
25	and <STRONG>intrusive_ptr_release</STRONG> should be defined in the namespace
26	that corresponds to their parameter; otherwise, the definitions need to go in
27	namespace <STRONG>boost</STRONG>.</p>
28	<p>The class template is parameterized on <b>T</b>, the type of the object pointed
29	to. <STRONG>intrusive_ptr<T></STRONG> can be implicitly converted to <STRONG>intrusive_ptr<U></STRONG>
30	whenever <STRONG>T</STRONG> can be implicitly converted to <STRONG>U</STRONG>.</p>
31	<P>The main reasons to use <STRONG>intrusive_ptr</STRONG> are:</P>
32	<UL>
33	<LI>
34	Some existing frameworks or OSes provide objects with embedded reference
35	counts;</LI>
36	<LI>
37	The memory footprint of <STRONG>intrusive_ptr</STRONG> is the same as the
38	corresponding raw pointer;</LI>
39	<LI>
40	<STRONG>intrusive_ptr<T></STRONG> can be constructed from an arbitrary
41	raw pointer of type <STRONG>T *</STRONG>.</LI></UL>
42	<P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG> better
43	fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based
44	design first.</P>
45	<h2><a name="Synopsis">Synopsis</a></h2>
46	<pre>namespace boost {
47
48	template<class T> class intrusive_ptr {
49
50	public:
51
52	typedef T <A href="#element_type" >element_type</A>;
53
54	<A href="#constructors" >intrusive_ptr</A>(); // never throws
55	<A href="#constructors" >intrusive_ptr</A>(T * p, bool add_ref = true);
56
57	<A href="#constructors" >intrusive_ptr</A>(intrusive_ptr const & r);
58	template<class Y> <A href="#constructors" >intrusive_ptr</A>(intrusive_ptr<Y> const & r);
59
60	<A href="#destructor" >~intrusive_ptr</A>();
61
62	intrusive_ptr & <A href="#assignment" >operator=</A>(intrusive_ptr const & r);
63	template<class Y> intrusive_ptr & <A href="#assignment" >operator=</A>(intrusive_ptr<Y> const & r);
64	template<class Y> intrusive_ptr & <A href="#assignment" >operator=</A>(T * r);
65
66	T & <A href="#indirection" >operator*</A>() const; // never throws
67	T * <A href="#indirection" >operator-></A>() const; // never throws
68	T * <A href="#get" >get</A>() const; // never throws
69
70	operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws
71
72	void <A href="#swap" >swap</A>(intrusive_ptr & b); // never throws
73	};
74
75	template<class T, class U>
76	bool <A href="#comparison" >operator==</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
77
78	template<class T, class U>
79	bool <A href="#comparison" >operator!=</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
80
81	template<class T>
82	bool <A href="#comparison" >operator==</A>(intrusive_ptr<T> const & a, T * b); // never throws
83
84	template<class T>
85	bool <A href="#comparison" >operator!=</A>(intrusive_ptr<T> const & a, T * b); // never throws
86
87	template<class T>
88	bool <A href="#comparison" >operator==</A>(T * a, intrusive_ptr<T> const & b); // never throws
89
90	template<class T>
91	bool <A href="#comparison" >operator!=</A>(T * a, intrusive_ptr<T> const & b); // never throws
92
93	template<class T, class U>
94	bool <A href="#comparison" >operator<</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
95
96	template<class T> void <A href="#free-swap" >swap</A>(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws
97
98	template<class T> T * <A href="#get_pointer" >get_pointer</A>(intrusive_ptr<T> const & p); // never throws
99
100	template<class T, class U>
101	intrusive_ptr<T> <A href="#static_pointer_cast" >static_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws
102
103	template<class T, class U>
104	intrusive_ptr<T> <A href="#const_pointer_cast" >const_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws
105
106	template<class T, class U>
107	intrusive_ptr<T> <A href="#dynamic_pointer_cast" >dynamic_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws
108
109	template<class E, class T, class Y>
110	std::basic_ostream<E, T> & <A href="#insertion-operator" >operator<<</A> (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);
111
112	}</pre>
113	<h2><a name="Members">Members</a></h2>
114	<h3><a name="element_type">element_type</a></h3>
115	<pre>typedef T element_type;</pre>
116	<blockquote>
117	<p>Provides the type of the template parameter T.</p>
118	</blockquote>
119	<h3><a name="constructors">constructors</a></h3>
120	<pre>intrusive_ptr(); // never throws</pre>
121	<blockquote>
122	<p><b>Postconditions:</b> <code>get() == 0</code>.</p>
123	<p><b>Throws:</b> nothing.</p>
124	</blockquote>
125	<pre>intrusive_ptr(T * p, bool add_ref = true);</pre>
126	<blockquote>
127	<p><b>Effects:</b> <code>if(p != 0 && add_ref) intrusive_ptr_add_ref(p);</code>.</p>
128	<p><b>Postconditions:</b> <code>get() == p</code>.</p>
129	</blockquote>
130	<pre>intrusive_ptr(intrusive_ptr const & r); // never throws
131	template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r); // never throws</pre>
132	<blockquote>
133	<p><b>Effects:</b> <code>if(r.get() != 0) intrusive_ptr_add_ref(r.get());</code>.</p>
134	<p><b>Postconditions:</b> <code>get() == r.get()</code>.</p>
135	</blockquote>
136	<h3><a name="destructor">destructor</a></h3>
137	<pre>~intrusive_ptr();</pre>
138	<BLOCKQUOTE>
139	<P><B>Effects:</B> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</P>
140	</BLOCKQUOTE>
141	<H3><a name="assignment">assignment</a></H3>
142	<pre>intrusive_ptr & operator=(intrusive_ptr const & r); // never throws
143	template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r); // never throws
144	intrusive_ptr & operator=(T * r);</pre>
145	<BLOCKQUOTE>
146	<P><B>Effects:</B> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</P>
147	<P><B>Returns:</B> <code>*this</code>.</P>
148	</BLOCKQUOTE>
149	<h3><a name="indirection">indirection</a></h3>
150	<pre>T & operator*() const; // never throws</pre>
151	<blockquote>
152	<p><b>Requirements:</b> <code>get() != 0</code>.</p>
153	<p><b>Returns:</b> <code>*get()</code>.</p>
154	<p><b>Throws:</b> nothing.</p>
155	</blockquote>
156	<pre>T * operator->() const; // never throws</pre>
157	<blockquote>
158	<p><b>Requirements:</b> <code>get() != 0</code>.</p>
159	<p><b>Returns:</b> <code>get()</code>.</p>
160	<p><b>Throws:</b> nothing.</p>
161	</blockquote>
162	<h3><a name="get">get</a></h3>
163	<pre>T * get() const; // never throws</pre>
164	<blockquote>
165	<p><b>Returns:</b> the stored pointer.</p>
166	<p><b>Throws:</b> nothing.</p>
167	</blockquote>
168	<h3><a name="conversions">conversions</a></h3>
169	<pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
170	<blockquote>
171	<p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
172	equivalent to <code>get() != 0</code>.</p>
173	<p><b>Throws:</b> nothing.</p>
174	<P><B>Notes:</B> This conversion operator allows <b>intrusive_ptr</b> objects to be
175	used in boolean contexts, like <code>if (p && p->valid()) {}</code>.
176	The actual target type is typically a pointer to a member function, avoiding
177	many of the implicit conversion pitfalls.</P>
178	</blockquote>
179	<h3><a name="swap">swap</a></h3>
180	<pre>void swap(intrusive_ptr & b); // never throws</pre>
181	<blockquote>
182	<p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
183	<p><b>Throws:</b> nothing.</p>
184	</blockquote>
185	<h2><a name="functions">Free Functions</a></h2>
186	<h3><a name="comparison">comparison</a></h3>
187	<pre>template<class T, class U>
188	bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
189	<blockquote>
190	<p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
191	<p><b>Throws:</b> nothing.</p>
192	</blockquote>
193	<pre>template<class T, class U>
194	bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
195	<blockquote>
196	<p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
197	<p><b>Throws:</b> nothing.</p>
198	</blockquote>
199	<pre>template<class T>
200	bool operator==(intrusive_ptr<T> const & a, T * b); // never throws</pre>
201	<blockquote>
202	<p><b>Returns:</b> <code>a.get() == b</code>.</p>
203	<p><b>Throws:</b> nothing.</p>
204	</blockquote>
205	<pre>template<class T>
206	bool operator!=(intrusive_ptr<T> const & a, T * b); // never throws</pre>
207	<blockquote>
208	<p><b>Returns:</b> <code>a.get() != b</code>.</p>
209	<p><b>Throws:</b> nothing.</p>
210	</blockquote>
211	<pre>template<class T>
212	bool operator==(T * a, intrusive_ptr<T> const & b); // never throws</pre>
213	<blockquote>
214	<p><b>Returns:</b> <code>a == b.get()</code>.</p>
215	<p><b>Throws:</b> nothing.</p>
216	</blockquote>
217	<pre>template<class T>
218	bool operator!=(T * a, intrusive_ptr<T> const & b); // never throws</pre>
219	<blockquote>
220	<p><b>Returns:</b> <code>a != b.get()</code>.</p>
221	<p><b>Throws:</b> nothing.</p>
222	</blockquote>
223	<pre>template<class T, class U>
224	bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre>
225	<blockquote>
226	<p><b>Returns:</b> <code>std::less<T *>()(a.get(), b.get())</code>.</p>
227	<p><b>Throws:</b> nothing.</p>
228	<P><B>Notes:</B> Allows <STRONG>intrusive_ptr</STRONG> objects to be used as keys
229	in associative containers.</P>
230	</blockquote>
231	<h3><a name="free-swap">swap</a></h3>
232	<pre>template<class T>
233	void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws</pre>
234	<BLOCKQUOTE>
235	<P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P>
236	<P><B>Throws:</B> nothing.</P>
237	<P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to
238	generic programming.</P>
239	</BLOCKQUOTE>
240	<h3><a name="get_pointer">get_pointer</a></h3>
241	<pre>template<class T>
242	T * get_pointer(intrusive_ptr<T> const & p); // never throws</pre>
243	<BLOCKQUOTE>
244	<P><B>Returns:</B> <code>p.get()</code>.</P>
245	<P><B>Throws:</B> nothing.</P>
246	<P><B>Notes:</B> Provided as an aid to generic programming. Used by <A href="../bind/mem_fn.html">
247	mem_fn</A>.</P>
248	</BLOCKQUOTE>
249	<h3><a name="static_pointer_cast">static_pointer_cast</a></h3>
250	<pre>template<class T, class U>
251	intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre>
252	<BLOCKQUOTE>
253	<P><B>Returns:</B> <code>intrusive_ptr<T>(static_cast<T*>(r.get()))</code>.</P>
254	<P><B>Throws:</B> nothing.</P>
255	</BLOCKQUOTE>
256	<h3><a name="const_pointer_cast">const_pointer_cast</a></h3>
257	<pre>template<class T, class U>
258	intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre>
259	<BLOCKQUOTE>
260	<P><B>Returns:</B> <code>intrusive_ptr<T>(const_cast<T*>(r.get()))</code>.</P>
261	<P><B>Throws:</B> nothing.</P>
262	</BLOCKQUOTE>
263	<h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3>
264	<pre>template<class T, class U>
265	intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r);</pre>
266	<BLOCKQUOTE>
267	<P><B>Returns:</B> <code>intrusive_ptr<T>(dynamic_cast<T*>(r.get()))</code>.</P>
268	<P><B>Throws:</B> nothing.</P>
269	</BLOCKQUOTE>
270	<h3><a name="insertion-operator">operator<<</a></h3>
271	<pre>template<class E, class T, class Y>
272	std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);</pre>
273	<BLOCKQUOTE>
274	<p><STRONG>Effects:</STRONG> <code>os << p.get();</code>.</p>
275	<P><B>Returns:</B> <code>os</code>.</P>
276	</BLOCKQUOTE>
277	<hr>
278	<p>
279	$Date: 2004/10/05 15:45:50 $</p>
280	<p>
281	<small>Copyright © 2003 Peter Dimov. Permission to copy, use, modify, sell and
282	distribute this document is granted provided this copyright notice appears in
283	all copies. This document is provided "as is" without express or implied
284	warranty, and with no claim as to its suitability for any purpose.</small></p>
285	</body>
286	</html>

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

Download in other formats: