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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Class thread_specific_ptr</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<link rel="start" href="index.html" title="The Boost C++ Libraries">
<link rel="up" href="threads/reference.html#id1220687" title="Header <boost/thread/tss.hpp>">
<link rel="prev" href="thread_group.html" title="Class thread_group">
<link rel="next" href="id869148.html" title="Type xtime_clock_types">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%">
<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../boost.png"></td>
<td align="center"><a href="../../index.htm">Home</a></td>
<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="../../people/people.htm">People</a></td>
<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
<td align="center"><a href="../../more/index.htm">More</a></td>
</table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="thread_group.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id1220687"><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="id869148.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="refentry" lang="en">
<a name="thread_specific_ptr"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2><span class="refentrytitle">Class thread_specific_ptr</span></h2>
<p>boost::thread_specific_ptr —
The <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> class defines
an interface for using thread specific storage.
</p>
</div>
<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis">
<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>
{
<span class="bold"><strong>public</strong></span>:
<span class="emphasis"><em>// <a href="thread_specific_ptr.html#thread_specific_ptrconstruct-copy-destruct">construct/copy/destruct</a></em></span>
<a href="thread_specific_ptr.html#id1256792-bb">thread_specific_ptr</a>();
<a href="thread_specific_ptr.html#id1182613-bb">thread_specific_ptr</a>(<span class="bold"><strong>void</strong></span> (*cleanup)(<span class="bold"><strong>void</strong></span>*));
<a href="thread_specific_ptr.html#id657055-bb">~thread_specific_ptr</a>();
<span class="emphasis"><em>// <a href="thread_specific_ptr.html#id1208148-bb">modifier functions</a></em></span>
<span class="type">T*</span> <a href="thread_specific_ptr.html#id824439-bb">release</a>();
<span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread_specific_ptr.html#id1038351-bb">reset</a>(T* = 0);
<span class="emphasis"><em>// <a href="thread_specific_ptr.html#id1009546-bb">observer functions</a></em></span>
<span class="type">T*</span> <a href="thread_specific_ptr.html#id1213997-bb">get</a>() <span class="bold"><strong>const</strong></span>;
<span class="type">T*</span> <a href="thread_specific_ptr.html#id658761-bb"><span class="bold"><strong>operator</strong></span>-></a>() <span class="bold"><strong>const</strong></span>;
<span class="type">T&</span> <a href="thread_specific_ptr.html#id687750-bb"><span class="bold"><strong>operator</strong></span>*()</a>() <span class="bold"><strong>const</strong></span>;
};</pre></div>
<div class="refsect1" lang="en">
<a name="id1564986"></a><h2>Description</h2>
<p>Thread specific storage is data associated with
individual threads and is often used to make operations
that rely on global data
<a href="threads.html#threads.glossary.thread-safe">thread-safe</a>.
</p>
<p>Template <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a>
stores a pointer to an object obtained on a thread-by-thread
basis and calls a specified cleanup handler on the contained
pointer when the thread terminates. The cleanup handlers are
called in the reverse order of construction of the
<a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a>s, and for the
initial thread are called by the destructor, providing the
same ordering guarantees as for normal declarations. Each
thread initially stores the null pointer in each
<a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> instance.</p>
<p>The template <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a>
is useful in the following cases:
</p>
<div class="itemizedlist"><ul type="disc">
<li>An interface was originally written assuming
a single thread of control and it is being ported to a
multithreaded environment.</li>
<li>Each thread of control invokes sequences of
methods that share data that are physically unique
for each thread, but must be logically accessed
through a globally visible access point instead of
being explicitly passed.</li>
</ul></div>
<div class="refsect2" lang="en">
<a name="id1565058"></a><h3>
<a name="thread_specific_ptrconstruct-copy-destruct"></a><code class="computeroutput">thread_specific_ptr</code> construct/copy/destruct</h3>
<div class="orderedlist"><ol type="1">
<li>
<pre class="literallayout"><a name="id1256792-bb"></a>thread_specific_ptr();</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
The expression <code class="computeroutput">delete get()</code> is well
formed.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
A thread-specific data key is allocated and visible to
all threads in the process. Upon creation, the value
<code class="computeroutput">NULL</code> will be associated with the new key in all
active threads. A cleanup method is registered with the key
that will call <code class="computeroutput">delete</code> on the value associated
with the key for a thread when it exits. When a thread exits,
if a key has a registered cleanup method and the thread has a
non-<code class="computeroutput">NULL</code> value associated with that key, the value
of the key is set to <code class="computeroutput">NULL</code> and then the cleanup
method is called with the previously associated value as its
sole argument. The order in which registered cleanup methods
are called when a thread exits is undefined. If after all the
cleanup methods have been called for all non-<code class="computeroutput">NULL</code>
values, there are still some non-<code class="computeroutput">NULL</code> values
with associated cleanup handlers 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>:
<a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
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>:
There may be an implementation specific limit to the
number of thread specific storage objects that can be created,
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>:
The most common need for cleanup will be to call
<code class="computeroutput">delete</code> on the associated value. If other forms
of cleanup are required the overloaded constructor should be
called instead.</p>
</li>
<li>
<pre class="literallayout"><a name="id1182613-bb"></a>thread_specific_ptr(<span class="bold"><strong>void</strong></span> (*cleanup)(<span class="bold"><strong>void</strong></span>*) cleanup);</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
A thread-specific data key is allocated and visible to
all threads in the process. Upon creation, the value
<code class="computeroutput">NULL</code> will be associated with the new key in all
active threads. The <code class="computeroutput">cleanup</code> method is registered
with the key and will be called for a thread with the value
associated with the key for that thread when it exits. When a
thread exits, if a key has a registered cleanup method and the
thread has a non-<code class="computeroutput">NULL</code> value associated with that
key, the value of the key is set to <code class="computeroutput">NULL</code> and then
the cleanup method is called with the previously associated
value as its sole argument. The order in which registered
cleanup methods are called when a thread exits is undefined.
If after all the cleanup methods have been called for all
non-<code class="computeroutput">NULL</code> values, there are still some
non-<code class="computeroutput">NULL</code> values with associated cleanup handlers
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>:
<a href="thread_resource_error.html" title="Class thread_resource_error">boost::thread_resource_error</a> if
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>:
There may be an implementation specific limit to the
number of thread specific storage objects that can be created,
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>:
There is the occasional need to register
specialized cleanup methods, or to register no cleanup method
at all (done by passing <code class="computeroutput">NULL</code> to this constructor.
</p>
</li>
<li>
<pre class="literallayout"><a name="id657055-bb"></a>~thread_specific_ptr();</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
Deletes the thread-specific data key allocated by the
constructor. The thread-specific data values associated with
the key need not be <code class="computeroutput">NULL</code>. It is the responsibility
of the application to perform any cleanup actions for data
associated with the key.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
Does not destroy any data that may be stored in any
thread's thread specific storage. For this reason you should
not destroy a <a href="thread_specific_ptr.html" title="Class thread_specific_ptr">thread_specific_ptr</a> object
until you are certain there are no threads running that have
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>:
Associated data is not cleaned up because registered
cleanup methods need to be run in the thread that allocated the
associated data to be guarranteed to work correctly. There's no
safe way to inject the call into another thread's execution
path, making it impossible to call the cleanup methods safely.
</p>
</li>
</ol></div>
</div>
<div class="refsect2" lang="en">
<a name="id1565378"></a><h3>
<a name="id1208148-bb"></a><code class="computeroutput">thread_specific_ptr</code> modifier functions</h3>
<div class="orderedlist"><ol type="1">
<li>
<pre class="literallayout"><span class="type">T*</span> <a name="id824439-bb"></a>release();</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
<code class="computeroutput">*this</code> holds the null pointer
for the current thread.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
<code class="computeroutput">this->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>:
This method provides a mechanism for the user to
relinquish control of the data associated with the
thread-specific key.</p>
</li>
<li>
<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1038351-bb"></a>reset(T* p = 0);</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
If <code class="computeroutput">this->get() != p &&
this->get() != NULL</code> then call the
associated cleanup function.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
<code class="computeroutput">*this</code> holds the pointer
<code class="computeroutput">p</code> for the current thread.</p>
</li>
</ol></div>
</div>
<div class="refsect2" lang="en">
<a name="id1565499"></a><h3>
<a name="id1009546-bb"></a><code class="computeroutput">thread_specific_ptr</code> observer functions</h3>
<div class="orderedlist"><ol type="1">
<li>
<pre class="literallayout"><span class="type">T*</span> <a name="id1213997-bb"></a>get() <span class="bold"><strong>const</strong></span>;</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
The object stored in thread specific storage for
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>:
Each thread initially returns 0.</p>
</li>
<li>
<pre class="literallayout"><span class="type">T*</span> <a name="id658761-bb"></a><span class="bold"><strong>operator</strong></span>->() <span class="bold"><strong>const</strong></span>;</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
<code class="computeroutput">this->get()</code>.</p>
</li>
<li>
<pre class="literallayout"><span class="type">T&</span> <a name="id687750-bb"></a><span class="bold"><strong>operator</strong></span>*()() <span class="bold"><strong>const</strong></span>;</pre>
<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
<code class="computeroutput">this->get() != 0</code><br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
<code class="computeroutput">this->get()</code>.</p>
</li>
</ol></div>
</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="thread_group.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id1220687"><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="id869148.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
