Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/thread_specific_ptr.html @ 25

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

added boost
File size: 15.6 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.69.1">
7<link rel="start" href="index.html" title="The Boost C++ Libraries">
8<link rel="up" href="threads/reference.html#id2547002" 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="id2545607.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.png (6897 bytes)" 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="threads/reference.html#id2547002"><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="id2545607.html"><img src="images/next.png" alt="Next"></a>
24</div>
25<div class="refentry" lang="en">
26<a name="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#thread_specific_ptrconstruct-copy-destruct">construct/copy/destruct</a></em></span>
40  <a href="thread_specific_ptr.html#id2626071-bb">thread_specific_ptr</a>();
41  <a href="thread_specific_ptr.html#id2597011-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#id2529847-bb">~thread_specific_ptr</a>();
43
44  <span class="emphasis"><em>// <a href="thread_specific_ptr.html#id2624424-bb">modifier functions</a></em></span>
45  <span class="type">T*</span> <a href="thread_specific_ptr.html#id2624428-bb">release</a>();
46  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread_specific_ptr.html#id2616183-bb">reset</a>(T* = 0);
47
48  <span class="emphasis"><em>// <a href="thread_specific_ptr.html#id2532919-bb">observer functions</a></em></span>
49  <span class="type">T*</span> <a href="thread_specific_ptr.html#id2600607-bb">get</a>() <span class="bold"><strong>const</strong></span>;
50  <span class="type">T*</span> <a href="thread_specific_ptr.html#id2535273-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#id2354136-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="id2785561"></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="threads.html#threads.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<div class="refsect2" lang="en">
84<a name="id2785631"></a><h3>
85<a name="thread_specific_ptrconstruct-copy-destruct"></a><code class="computeroutput">thread_specific_ptr</code> construct/copy/destruct</h3>
86<div class="orderedlist"><ol type="1">
87<li>
88<pre class="literallayout"><a name="id2626071-bb"></a>thread_specific_ptr();</pre>
89<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
90
91    The expression <code class="computeroutput">delete get()</code> is well
92                                formed.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
93
94    A thread-specific data key is allocated and visible to
95                                all threads in the process. Upon creation, the value
96                                <code class="computeroutput">NULL</code> will be associated with the new key in all
97                                active threads. A cleanup method is registered with the key
98                                that will call <code class="computeroutput">delete</code> on the value associated
99                                with the key for a thread when it exits. When a thread exits,
100                                if a key has a registered cleanup method and the thread has a
101                                non-<code class="computeroutput">NULL</code> value associated with that key, the value
102                                of the key is set to <code class="computeroutput">NULL</code> and then the cleanup
103                                method is called with the previously associated value as its
104                                sole argument. The order in which registered cleanup methods
105                                are called when a thread exits is undefined. If after all the
106                                cleanup methods have been called for all non-<code class="computeroutput">NULL</code>
107                                values, there are still some non-<code class="computeroutput">NULL</code> values
108                                with associated cleanup handlers the result is undefined
109                                behavior.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
110
111    <a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
112                                the necessary resources can not be obtained.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
113
114    There may be an implementation specific limit to the
115                                number of thread specific storage objects that can be created,
116                                and this limit may be small.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
117
118    The most common need for cleanup will be to call
119                                <code class="computeroutput">delete</code> on the associated value. If other forms
120                                of cleanup are required the overloaded constructor should be
121                                called instead.</p>
122</li>
123<li>
124<pre class="literallayout"><a name="id2597011-bb"></a>thread_specific_ptr(<span class="bold"><strong>void</strong></span> (*cleanup)(<span class="bold"><strong>void</strong></span>*) cleanup);</pre>
125<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
126
127    A thread-specific data key is allocated and visible to
128                                all threads in the process. Upon creation, the value
129                                <code class="computeroutput">NULL</code> will be associated with the new key in all
130                                active threads. The <code class="computeroutput">cleanup</code> method is registered
131                                with the key and will be called for a thread with the value
132                                associated with the key for that thread when it exits. When a
133                                thread exits, if a key has a registered cleanup method and the
134                                thread has a non-<code class="computeroutput">NULL</code> value associated with that
135                                key, the value of the key is set to <code class="computeroutput">NULL</code> and then
136                                the cleanup method is called with the previously associated
137                                value as its sole argument. The order in which registered
138                                cleanup methods are called when a thread exits is undefined.
139                                If after all the cleanup methods have been called for all
140                                non-<code class="computeroutput">NULL</code> values, there are still some
141                                non-<code class="computeroutput">NULL</code> values with associated cleanup handlers
142                                the result is undefined behavior.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
143
144    <a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
145                                the necessary resources can not be obtained.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
146
147    There may be an implementation specific limit to the
148                                number of thread specific storage objects that can be created,
149                                 and this limit may be small.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
150
151    There is the occasional need to register
152                                 specialized cleanup methods, or to register no cleanup method
153                                 at all (done by passing <code class="computeroutput">NULL</code> to this constructor.
154                                 </p>
155</li>
156<li>
157<pre class="literallayout"><a name="id2529847-bb"></a>~thread_specific_ptr();</pre>
158<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
159
160    Deletes the thread-specific data key allocated by the
161                                constructor. The thread-specific data values associated with
162                                the key need not be <code class="computeroutput">NULL</code>. It is the responsibility
163                                of the application to perform any cleanup actions for data
164                                associated with the key.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
165
166    Does not destroy any data that may be stored in any
167                                thread's thread specific storage. For this reason you should
168                                not destroy a <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> object
169                                until you are certain there are no threads running that have
170                                made use of its thread specific storage.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
171
172    Associated data is not cleaned up because registered
173                                cleanup methods need to be run in the thread that allocated the
174                                associated data to be guarranteed to work correctly. There's no
175                                safe way to inject the call into another thread's execution
176                                path, making it impossible to call the cleanup methods safely.
177                                </p>
178</li>
179</ol></div>
180</div>
181<div class="refsect2" lang="en">
182<a name="id2785956"></a><h3>
183<a name="id2624424-bb"></a><code class="computeroutput">thread_specific_ptr</code> modifier functions</h3>
184<div class="orderedlist"><ol type="1">
185<li>
186<pre class="literallayout"><span class="type">T*</span> <a name="id2624428-bb"></a>release();</pre>
187<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
188
189    <code class="computeroutput">*this</code> holds the null pointer
190                                        for the current thread.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
191
192    <code class="computeroutput">this-&gt;get()</code> prior to the call.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Rationale</span></b>:
193
194    This method provides a mechanism for the user to
195                                        relinquish control of the data associated with the
196                                        thread-specific key.</p>
197</li>
198<li>
199<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2616183-bb"></a>reset(T* p = 0);</pre>
200<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
201
202    If <code class="computeroutput">this-&gt;get() != p &amp;&amp; 
203                                        this-&gt;get() != NULL</code> then call the
204                                        associated cleanup function.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
205
206    <code class="computeroutput">*this</code> holds the pointer
207                                        <code class="computeroutput">p</code> for the current thread.</p>
208</li>
209</ol></div>
210</div>
211<div class="refsect2" lang="en">
212<a name="id2786079"></a><h3>
213<a name="id2532919-bb"></a><code class="computeroutput">thread_specific_ptr</code> observer functions</h3>
214<div class="orderedlist"><ol type="1">
215<li>
216<pre class="literallayout"><span class="type">T*</span> <a name="id2600607-bb"></a>get() <span class="bold"><strong>const</strong></span>;</pre>
217<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
218
219    The object stored in thread specific storage for
220                                        the current thread for <code class="computeroutput">*this</code>.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
221
222    Each thread initially returns 0.</p>
223</li>
224<li>
225<pre class="literallayout"><span class="type">T*</span> <a name="id2535273-bb"></a><span class="bold"><strong>operator</strong></span>-&gt;() <span class="bold"><strong>const</strong></span>;</pre>
226<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
227
228    <code class="computeroutput">this-&gt;get()</code>.</p>
229</li>
230<li>
231<pre class="literallayout"><span class="type">T&amp;</span> <a name="id2354136-bb"></a><span class="bold"><strong>operator</strong></span>*()() <span class="bold"><strong>const</strong></span>;</pre>
232<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
233
234    <code class="computeroutput">this-&gt;get() != 0</code><br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
235
236    <code class="computeroutput">this-&gt;get()</code>.</p>
237</li>
238</ol></div>
239</div>
240</div>
241</div>
242<table width="100%"><tr>
243<td align="left"></td>
244<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
245</tr></table>
246<hr>
247<div class="spirit-nav">
248<a accesskey="p" href="thread_group.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id2547002"><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="id2545607.html"><img src="images/next.png" alt="Next"></a>
249</div>
250</body>
251</html>
Note: See TracBrowser for help on using the repository browser.