Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/thread.html @ 12

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

added boost
File size: 14.5 KB
RevLine 
[12]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.69.1">
7<link rel="start" href="index.html" title="The Boost C++ Libraries">
8<link rel="up" href="threads/reference.html#id2617127" title="Header &lt;boost/thread/thread.hpp&gt;">
9<link rel="prev" href="recursive_timed_mutex.html" title="Class recursive_timed_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.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="recursive_timed_mutex.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id2617127"><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="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.Threads</strong></span> library. See
32                        <a href="threads.html#threads.glossary" title="Glossary">Glossary</a> for a precise description of
33                        <a href="threads.html#threads.glossary.thread">thread of execution</a>,
34                        and for definitions of threading-related terms and of thread states such as
35                        <a href="threads.html#threads.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#threadconstruct-copy-destruct">construct/copy/destruct</a></em></span>
43  <a href="thread.html#id2622566-bb">thread</a>();
44  <span class="bold"><strong>explicit</strong></span> <a href="thread.html#id2365210-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#id2608313-bb">~thread</a>();
46
47  <span class="emphasis"><em>// <a href="thread.html#id2615391-bb">comparison</a></em></span>
48  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="thread.html#id2554514-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#id2533742-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#id2624303-bb">modifier</a></em></span>
52  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id2598034-bb">join</a>();
53
54  <span class="emphasis"><em>// <a href="thread.html#id2547308-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#id2449425-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#id2605693-bb">yield</a>();
57};</pre></div>
58<div class="refsect1" lang="en">
59<a name="id2784013"></a><h2>Description</h2>
60<p>A <a href="threads.html#threads.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.Threads</strong></span> to schedule transitions between thread states is
75                        unspecified.</p>
76<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
77<h3 class="title">Note</h3>Just as the lifetime of a file may be different from the
78                        lifetime of an <code class="computeroutput">iostream</code> object which represents the file, the lifetime
79                        of a thread of execution may be different from the
80                        <a href="thread.html" title="Class thread">thread</a> object which represents the thread of
81                        execution. In particular, after a call to <code class="computeroutput">join()</code>,
82                        the thread of execution will no longer exist even though the
83                        <a href="thread.html" title="Class thread">thread</a> object continues to exist until the
84                        end of its normal lifetime. The converse is also possible; if
85                        a <a href="thread.html" title="Class thread">thread</a> object is destroyed without
86                        <code class="computeroutput">join()</code> first having been called, the thread of execution
87                        continues until its initial function completes.</div>
88<div class="refsect2" lang="en">
89<a name="id2784121"></a><h3>
90<a name="threadconstruct-copy-destruct"></a><code class="computeroutput">thread</code> construct/copy/destruct</h3>
91<div class="orderedlist"><ol type="1">
92<li>
93<pre class="literallayout"><a name="id2622566-bb"></a>thread();</pre>
94<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
95
96    Constructs a <a href="thread.html" title="Class thread">thread</a> object
97                        representing the current thread of execution.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
98
99    <code class="computeroutput">*this</code> is non-joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
100
101    <span class="bold"><strong>Danger:</strong></span><code class="computeroutput">*this</code> is valid only within the current thread.</p>
102</li>
103<li>
104<pre class="literallayout"><span class="bold"><strong>explicit</strong></span> <a name="id2365210-bb"></a>thread(<span class="bold"><strong>const</strong></span> boost::function0&lt;<span class="bold"><strong>void</strong></span>&gt;&amp; threadfunc);</pre>
105<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
106
107   
108                                Starts a new thread of execution and constructs a
109                                <a href="thread.html" title="Class thread">thread</a> object representing it.
110                                Copies <code class="computeroutput">threadfunc</code> (which in turn copies
111                                the function object wrapped by <code class="computeroutput">threadfunc</code>)
112                                to an internal location which persists for the lifetime
113                                of the new thread of execution. Calls <code class="computeroutput">operator()</code>
114                                on the copy of the <code class="computeroutput">threadfunc</code> function object
115                                in the new thread of execution.
116                        <br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Postconditions</span></b>:
117
118    <code class="computeroutput">*this</code> is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>:
119
120    <code class="computeroutput">boost::thread_resource_error</code> if a new thread
121                        of execution cannot be started.</p>
122</li>
123<li>
124<pre class="literallayout"><a name="id2608313-bb"></a>~thread();</pre>
125<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
126
127    Destroys <code class="computeroutput">*this</code>. The actual thread of
128                        execution may continue to execute after the
129                        <a href="thread.html" title="Class thread">thread</a> object has been destroyed.
130                        <br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
131
132    If <code class="computeroutput">*this</code> is joinable the actual thread
133                        of execution becomes "detached". Any resources used
134                        by the thread will be reclaimed when the thread of execution
135                        completes. To ensure such a thread of execution runs to completion
136                        before the <a href="thread.html" title="Class thread">thread</a> object is destroyed, call
137                        <code class="computeroutput">join()</code>.</p>
138</li>
139</ol></div>
140</div>
141<div class="refsect2" lang="en">
142<a name="id2784364"></a><h3>
143<a name="id2615391-bb"></a><code class="computeroutput">thread</code> comparison</h3>
144<div class="orderedlist"><ol type="1">
145<li>
146<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id2554514-bb"></a><span class="bold"><strong>operator</strong></span>==( rhs) <span class="bold"><strong>const</strong></span>;</pre>
147<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
148
149    The thread is non-terminated or <code class="computeroutput">*this</code>
150                                is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
151
152    <code class="computeroutput">true</code> if <code class="computeroutput">*this</code> and
153                                <code class="computeroutput">rhs</code> represent the same thread of
154                                execution.</p>
155</li>
156<li>
157<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id2533742-bb"></a><span class="bold"><strong>operator</strong></span>!=( rhs) <span class="bold"><strong>const</strong></span>;</pre>
158<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
159
160    The thread is non-terminated or <code class="computeroutput">*this</code>
161                                is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>:
162
163    <code class="computeroutput">!(*this==rhs)</code>.</p>
164</li>
165</ol></div>
166</div>
167<div class="refsect2" lang="en">
168<a name="id2784510"></a><h3>
169<a name="id2624303-bb"></a><code class="computeroutput">thread</code> modifier</h3>
170<div class="orderedlist"><ol type="1"><li>
171<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2598034-bb"></a>join();</pre>
172<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Requires</span></b>:
173
174    <code class="computeroutput">*this</code> is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
175
176    The current thread of execution blocks until the
177                                initial function of the thread of execution represented by
178                                <code class="computeroutput">*this</code> finishes and all resources are
179                                reclaimed.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
180
181    If <code class="computeroutput">*this == thread()</code> the result is
182                                implementation-defined. If the implementation doesn't
183                                detect this the result will be
184                                <a href="threads.html#threads.glossary.deadlock">deadlock</a>.
185                                </p>
186</li></ol></div>
187</div>
188<div class="refsect2" lang="en">
189<a name="id2784599"></a><h3>
190<a name="id2547308-bb"></a><code class="computeroutput">thread</code> static</h3>
191<div class="orderedlist"><ol type="1">
192<li>
193<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2449425-bb"></a>sleep(<span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">xtime</a>&amp; xt);</pre>
194<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
195
196    The current thread of execution blocks until
197                                <code class="computeroutput">xt</code> is reached.</p>
198</li>
199<li>
200<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id2605693-bb"></a>yield();</pre>
201<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>:
202
203    The current thread of execution is placed in the
204                                <a href="threads.html#threads.glossary.thread-state">ready</a> 
205                                state.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>:
206
207    Allow the current thread to give up the rest of its
208                                        time slice (or other scheduling quota) to another thread.
209                                        Particularly useful in non-preemptive implementations.</p>
210</li>
211</ol></div>
212</div>
213</div>
214</div>
215<table width="100%"><tr>
216<td align="left"></td>
217<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
218</tr></table>
219<hr>
220<div class="spirit-nav">
221<a accesskey="p" href="recursive_timed_mutex.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id2617127"><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>
222</div>
223</body>
224</html>
Note: See TracBrowser for help on using the repository browser.