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
252
253
254
255
256
257
258
259
260
261
262
|
<html>
<head>
<meta http-equiv="Content-Type" content=
"text/html; charset=iso-8859-1">
<meta name="keywords" content=
"threads, Boost.Threads, thread library, C++">
<link rel="stylesheet" type="text/css" href="styles.css">
<title>Boost.Threads, thread</title>
</head>
<body bgcolor="#ffffff" link="#0000ff" vlink="#800080">
<table summary="header" border="0" cellpadding="7" cellspacing="0"
width="100%">
<tr>
<td valign="top" width="300">
<h3><img height="86" alt="C++ Boost" src=
"../../../c++boost.gif" width="277"></h3>
</td>
<td valign="top">
<h1 align="center">Boost.Threads</h1>
<h2 align="center">Class thread</h2>
</td>
</tr>
</table>
<hr>
<p><a href="#Introduction">Introduction</a><br>
<a href="#Header">Header</a><br>
<a href="#Synopsis">Synopsis</a><br>
<a href="#Members">Members</a><br>
<a href="#Example">Example</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>The <code>thread</code> class represents threads of execution, and
provides the functionality to create and manage threads within the <b>
Boost.Threads</b> library. See <a href="definitions.html">
Definitions</a> for a precise description of "thread of
execution", and for definitions of threading related terms and of
thread states such as "blocked".</p>
<p>A thread of execution has an initial function. For the program's
initial thread, the initial function is <code>main()</code>. For other
threads, the initial function is <code>operator()</code> of the
function object passed to the class <code>thread</code>
constructor.</p>
<p>A thread of execution is said to be "finished" or
"finished execution" when its initial function returns or is
terminated. This includes completion of all thread cleanup handlers,
and completion of the normal C++ function return behaviors, such as
destruction of automatic storage (stack) objects and releasing any
associated implementation resources.</p>
<p>A thread object has an associated state which is either
"joinable" or "non-joinable".</p>
<p>Except as described below, the policy used by an implementation of
<b>Boost.Threads</b> to schedule transitions between thread states is
unspecified.</p>
<p><b>Note:</b> Just as the lifetime of a file may be different from
the lifetime of an iostream object which represents the file, the
lifetime of a thread of execution may be different from the <code>
thread</code> object which represents the thread of execution. In
particular, after a call to <code>join()</code>, the thread of
execution will no longer exist even though the <code>thread</code>
object continues to exist until the end of its normal lifetime. The
converse is also possible; if a <code>thread</code> object is destroyed
without <code>join()</code> having first been called, the thread of
execution continues until its initial function completes.</p>
<h2><a name="Header">Header</a></h2>
<pre>
#include <a href=
"../../../boost/thread/thread.hpp"><boost/thread/thread.hpp></a>
</pre>
<h2><a name="Synopsis">Synopsis</a></h2>
<pre>
namespace boost {
class thread : <a href=
"../../utility/utility.htm#noncopyable">boost::noncopyable</a> // Exposition only.
// Class thread meets the <a href=
"overview.html#NonCopyable">NonCopyable</a> requirement.
{
public:
thread();
explicit thread(const boost::function0<void>& threadfunc);
~thread();
bool operator==(const thread& rhs) const;
bool operator!=(const thread& rhs) const;
void join();
static void sleep(const xtime& xt);
static void yield();
};
} // namespace boost
</pre>
<h2><a name="Members">Members</a></h2>
<hr>
<h3>Constructors</h3>
<pre>
thread();
</pre>
<p><b>Effects:</b> Constructs a <code>thread</code> object representing
the current thread of execution.</p>
<p><b>Postcondition:</b> <code>*this</code> is non-joinable.</p>
<p><b>Danger:</b> <code>*this</code> is valid only within the current
thread.</p>
<pre>
thread(const <a href=
"../../function/index.html">boost::function0</a><void>& threadfunc);
</pre>
<p><b>Effects:</b> Starts a new thread of execution and constructs a
<code>thread</code> object representing it. Copies <code>
threadfunc</code> (which in turn copies the function object wrapped by
<code>threadfunc</code>) to an internal location which persists for the
lifetime of the new thread of execution. Calls <code>operator()</code>
on the copy of the <code>threadfunc</code> function object in the new
thread of execution.</p>
<p><b>Postcondition:</b> <code>*this</code> is joinable.</p>
<p><b>Throws:</b> <code>boost::thread_resource_error</code> if a new
thread of execution cannot be started.</p>
<hr>
<h3>Destructor</h3>
<pre>
~thread();
</pre>
<p><b>Effects:</b> Destroys <code>*this</code>. The actual thread of
execution may continue to execute after the <code>thread</code> object
has been destroyed.</p>
<p><b>Notes:</b> If <code>*this</code> is joinable the actual thread of
execution becomes "detached". Any resources used by the
thread will be reclaimed when the thread of execution completes. To
ensure such a thread of execution runs to completion before the <code>
thread</code> object is destroyed, call <code>join()</code>.</p>
<hr>
<h3>Comparison Operators</h3>
<pre>
bool operator==(const thread& rhs);
</pre>
<p><b>Requires:</b> The thread is non-terminated or <code>*this</code>
is joinable.</p>
<p><b>Returns:</b> <code>true</code> if <code>*this</code> and <code>
rhs</code> represent the same thread of execution.</p>
<pre>
bool operator!=(const thread& rhs);
</pre>
<p><b>Returns:</b> <code>!(*this==rhs)</code>.</p>
<hr>
<h3>join</h3>
<pre>
void join();
</pre>
<p><b>Requires:</b> <code>*this</code> is joinable.</p>
<p><b>Effects:</b> The current thread of execution blocks until the
initial function of the thread of execution represented by <code>
*this</code> finishes and all resources are reclaimed.</p>
<p><b>Postcondition:</b> <code>*this</code> is non-joinable.</p>
<p><b>Note:</b> If <code>*this == thread()</code> the result is
implementation defined. If the implementation doesn't detect this
the result will be <a href="definitions.html#Deadlock">
deadlock</a>.</p>
<hr>
<h3>sleep</h3>
<pre>
static void sleep(const <a href="xtime.html">xtime</a>& xt);
</pre>
<p><b>Effects:</b> The current thread of execution blocks until <code>
xt</code> is reached.</p>
<hr>
<h3>yield</h3>
<pre>
static void yield();
</pre>
<p><b>Effects:</b> The current thread of execution is placed in the
"ready" state.</p>
<p><b>Notes:</b> Allow the current thread to give up the rest of its
time slice (or other scheduling quota) to another thread. Particularly
useful in non-preemptive implementations.</p>
<hr>
<h2><a name="Example">Example Usage</a></h2>
<pre>
#include <boost/thread/thread.hpp>
#include <iostream>
struct thread_alarm
{
thread_alarm(int secs) : m_secs(secs) { }
void operator()()
{
boost::xtime xt;
boost::xtime_get(&xt, boost::TIME_UTC);
xt.sec += m_secs;
boost::thread::sleep(xt);
std::cout << "alarm sounded..." << std::endl;
}
int m_secs;
};
int main(int argc, char* argv[])
{
int secs = 5;
std::cout << "setting alarm for 5 seconds..." << std::endl;
thread_alarm alarm(secs);
boost::thread thrd(alarm);
thrd.join();
}
</pre>
<p>The output is:</p>
<pre>
setting alarm for 5 seconds...
alarm sounded...
</pre>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->05 November, 2001<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">
William E. Kempf</a> 2001 all rights reserved.</i></p>
</body>
</html>
|
