Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/boost/thread.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: 14.7 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Class thread</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.thread.hpp" title="Header &lt;boost/thread/thread.hpp&gt;">
9<link rel="prev" href="timed_read_write_mutex.html" title="Class timed_read_write_mutex">
10<link rel="next" href="thread_group.html" title="Class thread_group">
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="timed_read_write_mutex.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.thread.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="thread_group.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="refentry" lang="en">
26<a name="boost.thread"></a><div class="titlepage"></div>
27<div class="refnamediv">
28<h2><span class="refentrytitle">Class thread</span></h2>
29<p>boost::thread &#8212; <p>The <a href="thread.html" title="Class thread">thread</a> class represents threads of
30                        execution, and provides the functionality to create and manage
31                        threads within the <span class="bold"><strong>Boost.Thread</strong></span> library. See
32                        <a href="../thread.html#thread.glossary" title="Glossary">Glossary</a> for a precise description of
33                        <a href="../thread.html#thread.glossary.thread">thread of execution</a>,
34                        and for definitions of threading-related terms and of thread states such as
35                        <a href="../thread.html#thread.glossary.thread-state">blocked</a>.</p></p>
36</div>
37<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
38<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis">
39<span class="bold"><strong>class</strong></span> thread : <span class="bold"><strong>private</strong></span> boost::noncopyable   <span class="emphasis"><em>// Exposition only</em></span>
40{
41<span class="bold"><strong>public</strong></span>:
42  <span class="emphasis"><em>// <a href="thread.html#boost.threadconstruct-copy-destruct">construct/copy/destruct</a></em></span>
43  <a href="thread.html#id1291354-bb">thread</a>();
44  <span class="bold"><strong>explicit</strong></span> <a href="thread.html#id1291385-bb">thread</a>(<span class="bold"><strong>const</strong></span> boost::function0&lt;<span class="bold"><strong>void</strong></span>&gt;&amp;);
45  <a href="thread.html#id1286822-bb">~thread</a>();
46
47  <span class="emphasis"><em>// <a href="thread.html#id1281873-bb">comparison</a></em></span>
48  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="thread.html#id1281877-bb"><span class="bold"><strong>operator</strong></span>==</a>() <span class="bold"><strong>const</strong></span>;
49  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="thread.html#id1314629-bb"><span class="bold"><strong>operator</strong></span>!=</a>() <span class="bold"><strong>const</strong></span>;
50
51  <span class="emphasis"><em>// <a href="thread.html#id1252540-bb">modifier</a></em></span>
52  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id1252545-bb">join</a>();
53
54  <span class="emphasis"><em>// <a href="thread.html#id1252594-bb">static</a></em></span>
55  <span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id1252598-bb">sleep</a>(<span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">xtime</a>&amp;);
56  <span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id1252632-bb">yield</a>();
57};</pre></div>
58<div class="refsect1" lang="en">
59<a name="id1744071"></a><h2>Description</h2>
60<p>A <a href="../thread.html#thread.glossary.thread">thread of execution</a>
61                        has an initial function. For the program's initial thread, the initial
62                        function is <code class="computeroutput">main()</code>. For other threads, the initial
63                        function is <code class="computeroutput">operator()</code> of the function object passed to
64                        the <a href="thread.html" title="Class thread">thread</a> object's constructor.</p>
65<p>A thread of execution  is said to be "finished"
66                        or to have "finished execution" when its initial function returns or
67                        is terminated. This includes completion of all thread cleanup
68                        handlers, and completion of the normal C++ function return behaviors,
69                        such as destruction of automatic storage (stack) objects and releasing
70                        any associated implementation resources.</p>
71<p>A thread object has an associated state which is either
72                        "joinable" or "non-joinable".</p>
73<p>Except as described below, the policy used by an implementation
74                        of <span class="bold"><strong>Boost.Thread</strong></span> to schedule transitions between thread states is
75                        unspecified.</p>
76<div class="note"><table border="0" summary="Note">
77<tr>
78<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
79<th align="left">Note</th>
80</tr>
81<tr><td align="left" valign="top">Just as the lifetime of a file may be different from the
82                        lifetime of an <code class="computeroutput">iostream</code> object which represents the file, the lifetime
83                        of a thread of execution may be different from the
84                        <a href="thread.html" title="Class thread">thread</a> object which represents the thread of
85                        execution. In particular, after a call to <code class="computeroutput">join()</code>,
86                        the thread of execution will no longer exist even though the
87                        <a href="thread.html" title="Class thread">thread</a> object continues to exist until the
88                        end of its normal lifetime. The converse is also possible; if
89                        a <a href="thread.html" title="Class thread">thread</a> object is destroyed without
90                        <code class="computeroutput">join()</code> first having been called, the thread of execution
91                        continues until its initial function completes.</td></tr>
92</table></div>
93<div class="refsect2" lang="en">
94<a name="id1744185"></a><h3>
95<a name="boost.threadconstruct-copy-destruct"></a><code class="computeroutput">thread</code> construct/copy/destruct</h3>
96<div class="orderedlist"><ol type="1">
97<li>
98<pre class="literallayout"><a name="id1291354-bb"></a>thread();</pre>
99<div class="variablelist"><table border="0">
100<col align="left" valign="top">
101<tbody>
102<tr>
103<td>
104<span class="term">Effects:</span></td>
105<td>Constructs a <a href="thread.html" title="Class thread">thread</a> object
106                        representing the current thread of execution.</td>
107</tr>
108<tr>
109<td>
110<span class="term">Postconditions:</span></td>
111<td>
112<code class="computeroutput">*this</code> is non-joinable.</td>
113</tr>
114<tr>
115<td>
116<span class="term">Notes:</span></td>
117<td>
118<span class="bold"><strong>Danger:</strong></span><code class="computeroutput">*this</code> is valid only within the current thread.</td>
119</tr>
120</tbody>
121</table></div>
122</li>
123<li>
124<pre class="literallayout"><span class="bold"><strong>explicit</strong></span> <a name="id1291385-bb"></a>thread(<span class="bold"><strong>const</strong></span> boost::function0&lt;<span class="bold"><strong>void</strong></span>&gt;&amp; threadfunc);</pre>
125<div class="variablelist"><table border="0">
126<col align="left" valign="top">
127<tbody>
128<tr>
129<td>
130<span class="term">Effects:</span></td>
131<td>
132                                Starts a new thread of execution and constructs a
133                                <a href="thread.html" title="Class thread">thread</a> object representing it.
134                                Copies <code class="computeroutput">threadfunc</code> (which in turn copies
135                                the function object wrapped by <code class="computeroutput">threadfunc</code>)
136                                to an internal location which persists for the lifetime
137                                of the new thread of execution. Calls <code class="computeroutput">operator()</code>
138                                on the copy of the <code class="computeroutput">threadfunc</code> function object
139                                in the new thread of execution.
140                        </td>
141</tr>
142<tr>
143<td>
144<span class="term">Postconditions:</span></td>
145<td>
146<code class="computeroutput">*this</code> is joinable.</td>
147</tr>
148<tr>
149<td>
150<span class="term">Throws:</span></td>
151<td>
152<code class="computeroutput">boost::thread_resource_error</code> if a new thread
153                        of execution cannot be started.</td>
154</tr>
155</tbody>
156</table></div>
157</li>
158<li>
159<pre class="literallayout"><a name="id1286822-bb"></a>~thread();</pre>
160<div class="variablelist"><table border="0">
161<col align="left" valign="top">
162<tbody>
163<tr>
164<td>
165<span class="term">Effects:</span></td>
166<td>Destroys <code class="computeroutput">*this</code>. The actual thread of
167                        execution may continue to execute after the
168                        <a href="thread.html" title="Class thread">thread</a> object has been destroyed.
169                        </td>
170</tr>
171<tr>
172<td>
173<span class="term">Notes:</span></td>
174<td>If <code class="computeroutput">*this</code> is joinable the actual thread
175                        of execution becomes "detached". Any resources used
176                        by the thread will be reclaimed when the thread of execution
177                        completes. To ensure such a thread of execution runs to completion
178                        before the <a href="thread.html" title="Class thread">thread</a> object is destroyed, call
179                        <code class="computeroutput">join()</code>.</td>
180</tr>
181</tbody>
182</table></div>
183</li>
184</ol></div>
185</div>
186<div class="refsect2" lang="en">
187<a name="id1744429"></a><h3>
188<a name="id1281873-bb"></a><code class="computeroutput">thread</code> comparison</h3>
189<div class="orderedlist"><ol type="1">
190<li>
191<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1281877-bb"></a><span class="bold"><strong>operator</strong></span>==( rhs) <span class="bold"><strong>const</strong></span>;</pre>
192<div class="variablelist"><table border="0">
193<col align="left" valign="top">
194<tbody>
195<tr>
196<td>
197<span class="term">Requires:</span></td>
198<td>The thread is non-terminated or <code class="computeroutput">*this</code>
199                                is joinable.</td>
200</tr>
201<tr>
202<td>
203<span class="term">Returns:</span></td>
204<td>
205<code class="computeroutput">true</code> if <code class="computeroutput">*this</code> and
206                                <code class="computeroutput">rhs</code> represent the same thread of
207                                execution.</td>
208</tr>
209</tbody>
210</table></div>
211</li>
212<li>
213<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1314629-bb"></a><span class="bold"><strong>operator</strong></span>!=( rhs) <span class="bold"><strong>const</strong></span>;</pre>
214<div class="variablelist"><table border="0">
215<col align="left" valign="top">
216<tbody>
217<tr>
218<td>
219<span class="term">Requires:</span></td>
220<td>The thread is non-terminated or <code class="computeroutput">*this</code>
221                                is joinable.</td>
222</tr>
223<tr>
224<td>
225<span class="term">Returns:</span></td>
226<td>
227<code class="computeroutput">!(*this==rhs)</code>.</td>
228</tr>
229</tbody>
230</table></div>
231</li>
232</ol></div>
233</div>
234<div class="refsect2" lang="en">
235<a name="id1744577"></a><h3>
236<a name="id1252540-bb"></a><code class="computeroutput">thread</code> modifier</h3>
237<div class="orderedlist"><ol type="1"><li>
238<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1252545-bb"></a>join();</pre>
239<div class="variablelist"><table border="0">
240<col align="left" valign="top">
241<tbody>
242<tr>
243<td>
244<span class="term">Requires:</span></td>
245<td>
246<code class="computeroutput">*this</code> is joinable.</td>
247</tr>
248<tr>
249<td>
250<span class="term">Effects:</span></td>
251<td>The current thread of execution blocks until the
252                                initial function of the thread of execution represented by
253                                <code class="computeroutput">*this</code> finishes and all resources are
254                                reclaimed.</td>
255</tr>
256<tr>
257<td>
258<span class="term">Notes:</span></td>
259<td>If <code class="computeroutput">*this == thread()</code> the result is
260                                implementation-defined. If the implementation doesn't
261                                detect this the result will be
262                                <a href="../thread.html#thread.glossary.deadlock">deadlock</a>.
263                                </td>
264</tr>
265</tbody>
266</table></div>
267</li></ol></div>
268</div>
269<div class="refsect2" lang="en">
270<a name="id1744664"></a><h3>
271<a name="id1252594-bb"></a><code class="computeroutput">thread</code> static</h3>
272<div class="orderedlist"><ol type="1">
273<li>
274<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1252598-bb"></a>sleep(<span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">xtime</a>&amp; xt);</pre>
275<div class="variablelist"><table border="0">
276<col align="left" valign="top">
277<tbody><tr>
278<td>
279<span class="term">Effects:</span></td>
280<td>The current thread of execution blocks until
281                                <code class="computeroutput">xt</code> is reached.</td>
282</tr></tbody>
283</table></div>
284</li>
285<li>
286<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1252632-bb"></a>yield();</pre>
287<div class="variablelist"><table border="0">
288<col align="left" valign="top">
289<tbody>
290<tr>
291<td>
292<span class="term">Effects:</span></td>
293<td>The current thread of execution is placed in the
294                                <a href="../thread.html#thread.glossary.thread-state">ready</a> 
295                                state.</td>
296</tr>
297<tr>
298<td>
299<span class="term">Notes:</span></td>
300<td>Allow the current thread to give up the rest of its
301                                        time slice (or other scheduling quota) to another thread.
302                                        Particularly useful in non-preemptive implementations.</td>
303</tr>
304</tbody>
305</table></div>
306</li>
307</ol></div>
308</div>
309</div>
310</div>
311<table width="100%"><tr>
312<td align="left"></td>
313<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
314</tr></table>
315<hr>
316<div class="spirit-nav">
317<a accesskey="p" href="timed_read_write_mutex.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.thread.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="thread_group.html"><img src="../images/next.png" alt="Next"></a>
318</div>
319</body>
320</html>
Note: See TracBrowser for help on using the repository browser.