Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/boost/thread_specific_ptr.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 15.5 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Class thread_specific_ptr</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../thread/reference.html#header.boost.thread.tss.hpp" title="Header &lt;boost/thread/tss.hpp&gt;">
9<link rel="prev" href="thread_group.html" title="Class thread_group">
10<link rel="next" href="xtime_clock_types.html" title="Type xtime_clock_types">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="thread_group.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.tss.hpp"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xtime_clock_types.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="refentry" lang="en">
26<a name="boost.thread_specific_ptr"></a><div class="titlepage"></div>
27<div class="refnamediv">
28<h2><span class="refentrytitle">Class thread_specific_ptr</span></h2>
29<p>boost::thread_specific_ptr &#8212; 
30                                The <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> class defines
31                                an interface for using thread specific storage.
32                        </p>
33</div>
34<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
35<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis">
36<span class="bold"><strong>class</strong></span> thread_specific_ptr : <span class="bold"><strong>private</strong></span> boost::noncopyable   <span class="emphasis"><em>// Exposition only</em></span>
37{
38<span class="bold"><strong>public</strong></span>:
39  <span class="emphasis"><em>// <a href="thread_specific_ptr.html#boost.thread_specific_ptrconstruct-copy-destruct">construct/copy/destruct</a></em></span>
40  <a href="thread_specific_ptr.html#id997050-bb">thread_specific_ptr</a>();
41  <a href="thread_specific_ptr.html#id1281765-bb">thread_specific_ptr</a>(<span class="bold"><strong>void</strong></span> (*cleanup)(<span class="bold"><strong>void</strong></span>*));
42  <a href="thread_specific_ptr.html#id1255605-bb">~thread_specific_ptr</a>();
43
44  <span class="emphasis"><em>// <a href="thread_specific_ptr.html#id1314265-bb">modifier functions</a></em></span>
45  <span class="type">T*</span> <a href="thread_specific_ptr.html#id1314269-bb">release</a>();
46  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread_specific_ptr.html#id1314298-bb">reset</a>(T* = 0);
47
48  <span class="emphasis"><em>// <a href="thread_specific_ptr.html#id792573-bb">observer functions</a></em></span>
49  <span class="type">T*</span> <a href="thread_specific_ptr.html#id792578-bb">get</a>() <span class="bold"><strong>const</strong></span>;
50  <span class="type">T*</span> <a href="thread_specific_ptr.html#id1038441-bb"><span class="bold"><strong>operator</strong></span>-&gt;</a>() <span class="bold"><strong>const</strong></span>;
51  <span class="type">T&amp;</span> <a href="thread_specific_ptr.html#id1255500-bb"><span class="bold"><strong>operator</strong></span>*()</a>() <span class="bold"><strong>const</strong></span>;
52};</pre></div>
53<div class="refsect1" lang="en">
54<a name="id1745620"></a><h2>Description</h2>
55<p>Thread specific storage is data associated with
56                                individual threads and is often used to make operations
57                                that rely on global data
58                                <a href="../thread.html#thread.glossary.thread-safe">thread-safe</a>.
59                                </p>
60<p>Template <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> 
61                                stores a pointer to an object obtained on a thread-by-thread
62                                basis and calls a specified cleanup handler on the contained
63                                pointer when the thread terminates. The cleanup handlers are
64                                called in the reverse order of construction of the
65                                <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a>s, and for the
66                                initial thread are called by the destructor, providing the
67                                same ordering guarantees as for normal declarations. Each
68                                thread initially stores the null pointer in each
69                                <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> instance.</p>
70<p>The template <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a>
71                                is useful in the following cases:
72                                        </p>
73<div class="itemizedlist"><ul type="disc">
74<li>An interface was originally written assuming
75                                                a single thread of control and it is being ported to a
76                                                multithreaded environment.</li>
77<li>Each thread of control invokes sequences of
78                                                methods that share data that are physically unique
79                                                for each thread, but must be logically accessed
80                                                through a globally visible access point instead of
81                                                being explicitly passed.</li>
82</ul></div>
83<p>
84                                </p>
85<div class="refsect2" lang="en">
86<a name="id1745699"></a><h3>
87<a name="boost.thread_specific_ptrconstruct-copy-destruct"></a><code class="computeroutput">thread_specific_ptr</code> construct/copy/destruct</h3>
88<div class="orderedlist"><ol type="1">
89<li>
90<pre class="literallayout"><a name="id997050-bb"></a>thread_specific_ptr();</pre>
91<div class="variablelist"><table border="0">
92<col align="left" valign="top">
93<tbody>
94<tr>
95<td>
96<span class="term">Requires:</span></td>
97<td>The expression <code class="computeroutput">delete get()</code> is well
98                                formed.</td>
99</tr>
100<tr>
101<td>
102<span class="term">Effects:</span></td>
103<td>A thread-specific data key is allocated and visible to
104                                all threads in the process. Upon creation, the value
105                                <code class="computeroutput">NULL</code> will be associated with the new key in all
106                                active threads. A cleanup method is registered with the key
107                                that will call <code class="computeroutput">delete</code> on the value associated
108                                with the key for a thread when it exits. When a thread exits,
109                                if a key has a registered cleanup method and the thread has a
110                                non-<code class="computeroutput">NULL</code> value associated with that key, the value
111                                of the key is set to <code class="computeroutput">NULL</code> and then the cleanup
112                                method is called with the previously associated value as its
113                                sole argument. The order in which registered cleanup methods
114                                are called when a thread exits is undefined. If after all the
115                                cleanup methods have been called for all non-<code class="computeroutput">NULL</code>
116                                values, there are still some non-<code class="computeroutput">NULL</code> values
117                                with associated cleanup handlers the result is undefined
118                                behavior.</td>
119</tr>
120<tr>
121<td>
122<span class="term">Throws:</span></td>
123<td>
124<a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
125                                the necessary resources can not be obtained.</td>
126</tr>
127<tr>
128<td>
129<span class="term">Notes:</span></td>
130<td>There may be an implementation specific limit to the
131                                number of thread specific storage objects that can be created,
132                                and this limit may be small.</td>
133</tr>
134<tr>
135<td>
136<span class="term">Rationale:</span></td>
137<td>The most common need for cleanup will be to call
138                                <code class="computeroutput">delete</code> on the associated value. If other forms
139                                of cleanup are required the overloaded constructor should be
140                                called instead.</td>
141</tr>
142</tbody>
143</table></div>
144</li>
145<li>
146<pre class="literallayout"><a name="id1281765-bb"></a>thread_specific_ptr(<span class="bold"><strong>void</strong></span> (*cleanup)(<span class="bold"><strong>void</strong></span>*) cleanup);</pre>
147<div class="variablelist"><table border="0">
148<col align="left" valign="top">
149<tbody>
150<tr>
151<td>
152<span class="term">Effects:</span></td>
153<td>A thread-specific data key is allocated and visible to
154                                all threads in the process. Upon creation, the value
155                                <code class="computeroutput">NULL</code> will be associated with the new key in all
156                                active threads. The <code class="computeroutput">cleanup</code> method is registered
157                                with the key and will be called for a thread with the value
158                                associated with the key for that thread when it exits. When a
159                                thread exits, if a key has a registered cleanup method and the
160                                thread has a non-<code class="computeroutput">NULL</code> value associated with that
161                                key, the value of the key is set to <code class="computeroutput">NULL</code> and then
162                                the cleanup method is called with the previously associated
163                                value as its sole argument. The order in which registered
164                                cleanup methods are called when a thread exits is undefined.
165                                If after all the cleanup methods have been called for all
166                                non-<code class="computeroutput">NULL</code> values, there are still some
167                                non-<code class="computeroutput">NULL</code> values with associated cleanup handlers
168                                the result is undefined behavior.</td>
169</tr>
170<tr>
171<td>
172<span class="term">Throws:</span></td>
173<td>
174<a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
175                                the necessary resources can not be obtained.</td>
176</tr>
177<tr>
178<td>
179<span class="term">Notes:</span></td>
180<td>There may be an implementation specific limit to the
181                                number of thread specific storage objects that can be created,
182                                 and this limit may be small.</td>
183</tr>
184<tr>
185<td>
186<span class="term">Rationale:</span></td>
187<td>There is the occasional need to register
188                                 specialized cleanup methods, or to register no cleanup method
189                                 at all (done by passing <code class="computeroutput">NULL</code> to this constructor.
190                                 </td>
191</tr>
192</tbody>
193</table></div>
194</li>
195<li>
196<pre class="literallayout"><a name="id1255605-bb"></a>~thread_specific_ptr();</pre>
197<div class="variablelist"><table border="0">
198<col align="left" valign="top">
199<tbody>
200<tr>
201<td>
202<span class="term">Effects:</span></td>
203<td>Deletes the thread-specific data key allocated by the
204                                constructor. The thread-specific data values associated with
205                                the key need not be <code class="computeroutput">NULL</code>. It is the responsibility
206                                of the application to perform any cleanup actions for data
207                                associated with the key.</td>
208</tr>
209<tr>
210<td>
211<span class="term">Notes:</span></td>
212<td>Does not destroy any data that may be stored in any
213                                thread's thread specific storage. For this reason you should
214                                not destroy a <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> object
215                                until you are certain there are no threads running that have
216                                made use of its thread specific storage.</td>
217</tr>
218<tr>
219<td>
220<span class="term">Rationale:</span></td>
221<td>Associated data is not cleaned up because registered
222                                cleanup methods need to be run in the thread that allocated the
223                                associated data to be guarranteed to work correctly. There's no
224                                safe way to inject the call into another thread's execution
225                                path, making it impossible to call the cleanup methods safely.
226                                </td>
227</tr>
228</tbody>
229</table></div>
230</li>
231</ol></div>
232</div>
233<div class="refsect2" lang="en">
234<a name="id1746025"></a><h3>
235<a name="id1314265-bb"></a><code class="computeroutput">thread_specific_ptr</code> modifier functions</h3>
236<div class="orderedlist"><ol type="1">
237<li>
238<pre class="literallayout"><span class="type">T*</span> <a name="id1314269-bb"></a>release();</pre>
239<div class="variablelist"><table border="0">
240<col align="left" valign="top">
241<tbody>
242<tr>
243<td>
244<span class="term">Postconditions:</span></td>
245<td>
246<code class="computeroutput">*this</code> holds the null pointer
247                                        for the current thread.</td>
248</tr>
249<tr>
250<td>
251<span class="term">Returns:</span></td>
252<td>
253<code class="computeroutput">this-&gt;get()</code> prior to the call.</td>
254</tr>
255<tr>
256<td>
257<span class="term">Rationale:</span></td>
258<td>This method provides a mechanism for the user to
259                                        relinquish control of the data associated with the
260                                        thread-specific key.</td>
261</tr>
262</tbody>
263</table></div>
264</li>
265<li>
266<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1314298-bb"></a>reset(T* p = 0);</pre>
267<div class="variablelist"><table border="0">
268<col align="left" valign="top">
269<tbody>
270<tr>
271<td>
272<span class="term">Effects:</span></td>
273<td>If <code class="computeroutput">this-&gt;get() != p &amp;&amp; 
274                                        this-&gt;get() != NULL</code> then call the
275                                        associated cleanup function.</td>
276</tr>
277<tr>
278<td>
279<span class="term">Postconditions:</span></td>
280<td>
281<code class="computeroutput">*this</code> holds the pointer
282                                        <code class="computeroutput">p</code> for the current thread.</td>
283</tr>
284</tbody>
285</table></div>
286</li>
287</ol></div>
288</div>
289<div class="refsect2" lang="en">
290<a name="id1746149"></a><h3>
291<a name="id792573-bb"></a><code class="computeroutput">thread_specific_ptr</code> observer functions</h3>
292<div class="orderedlist"><ol type="1">
293<li>
294<pre class="literallayout"><span class="type">T*</span> <a name="id792578-bb"></a>get() <span class="bold"><strong>const</strong></span>;</pre>
295<div class="variablelist"><table border="0">
296<col align="left" valign="top">
297<tbody>
298<tr>
299<td>
300<span class="term">Returns:</span></td>
301<td>The object stored in thread specific storage for
302                                        the current thread for <code class="computeroutput">*this</code>.</td>
303</tr>
304<tr>
305<td>
306<span class="term">Notes:</span></td>
307<td>Each thread initially returns 0.</td>
308</tr>
309</tbody>
310</table></div>
311</li>
312<li>
313<pre class="literallayout"><span class="type">T*</span> <a name="id1038441-bb"></a><span class="bold"><strong>operator</strong></span>-&gt;() <span class="bold"><strong>const</strong></span>;</pre>
314<div class="variablelist"><table border="0">
315<col align="left" valign="top">
316<tbody><tr>
317<td>
318<span class="term">Returns:</span></td>
319<td>
320<code class="computeroutput">this-&gt;get()</code>.</td>
321</tr></tbody>
322</table></div>
323</li>
324<li>
325<pre class="literallayout"><span class="type">T&amp;</span> <a name="id1255500-bb"></a><span class="bold"><strong>operator</strong></span>*()() <span class="bold"><strong>const</strong></span>;</pre>
326<div class="variablelist"><table border="0">
327<col align="left" valign="top">
328<tbody>
329<tr>
330<td>
331<span class="term">Requires:</span></td>
332<td><code class="computeroutput">this-&gt;get() != 0</code></td>
333</tr>
334<tr>
335<td>
336<span class="term">Returns:</span></td>
337<td>
338<code class="computeroutput">this-&gt;get()</code>.</td>
339</tr>
340</tbody>
341</table></div>
342</li>
343</ol></div>
344</div>
345</div>
346</div>
347<table width="100%"><tr>
348<td align="left"></td>
349<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
350</tr></table>
351<hr>
352<div class="spirit-nav">
353<a accesskey="p" href="thread_group.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.tss.hpp"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="xtime_clock_types.html"><img src="../images/next.png" alt="Next"></a>
354</div>
355</body>
356</html>
Note: See TracBrowser for help on using the repository browser.