diff options
Diffstat (limited to 'doc/html/thread.html')
| -rw-r--r-- | doc/html/thread.html | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/doc/html/thread.html b/doc/html/thread.html new file mode 100644 index 0000000000..1b92c6c080 --- /dev/null +++ b/doc/html/thread.html @@ -0,0 +1,224 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Class thread</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#id1248802" title="Header <boost/thread/thread.hpp>"> +<link rel="prev" href="timed_read_write_mutex.html" title="Class timed_read_write_mutex"> +<link rel="next" href="thread_group.html" title="Class thread_group"> +</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="timed_read_write_mutex.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id1248802"><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> +</div> +<div class="refentry" lang="en"> +<a name="thread"></a><div class="titlepage"></div> +<div class="refnamediv"> +<h2><span class="refentrytitle">Class thread</span></h2> +<p>boost::thread — <p>The <a href="thread.html" title="Class thread">thread</a> class represents threads of + execution, and provides the functionality to create and manage + threads within the library. See + <a href="threads.html#threads.glossary" title="Glossary">Glossary</a> for a precise description of + <a href="threads.html#threads.glossary.thread">thread of execution</a>, + and for definitions of threading-related terms and of thread states such as + <a href="threads.html#threads.glossary.thread-state">blocked</a>.</p></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 : <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.html#threadconstruct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="thread.html#id698281-bb">thread</a>(); + <span class="bold"><strong>explicit</strong></span> <a href="thread.html#id1291929-bb">thread</a>(<span class="bold"><strong>const</strong></span> boost::function0<<span class="bold"><strong>void</strong></span>>&); + <a href="thread.html#id732677-bb">~thread</a>(); + + <span class="emphasis"><em>// <a href="thread.html#id1145095-bb">comparison</a></em></span> + <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="thread.html#id1138943-bb"><span class="bold"><strong>operator</strong></span>==</a>() <span class="bold"><strong>const</strong></span>; + <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="thread.html#id1288634-bb"><span class="bold"><strong>operator</strong></span>!=</a>() <span class="bold"><strong>const</strong></span>; + + <span class="emphasis"><em>// <a href="thread.html#id1007431-bb">modifier</a></em></span> + <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id1253588-bb">join</a>(); + + <span class="emphasis"><em>// <a href="thread.html#id1178459-bb">static</a></em></span> + <span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id974656-bb">sleep</a>(<span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">xtime</a>&); + <span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="thread.html#id1245828-bb">yield</a>(); +};</pre></div> +<div class="refsect1" lang="en"> +<a name="id1563475"></a><h2>Description</h2> +<p>A <a href="threads.html#threads.glossary.thread">thread of execution</a> + has an initial function. For the program's initial thread, the initial + function is <code class="computeroutput">main()</code>. For other threads, the initial + function is <code class="computeroutput">operator()</code> of the function object passed to + the <a href="thread.html" title="Class thread">thread</a> object's constructor.</p> +<p>A thread of execution is said to be "finished" + or to have "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 to schedule transitions between thread states is + unspecified.</p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Just as the lifetime of a file may be different from the + lifetime of an <code class="computeroutput">iostream</code> object which represents the file, the lifetime + of a thread of execution may be different from the + <a href="thread.html" title="Class thread">thread</a> object which represents the thread of + execution. In particular, after a call to <code class="computeroutput">join()</code>, + the thread of execution will no longer exist even though the + <a href="thread.html" title="Class thread">thread</a> object continues to exist until the + end of its normal lifetime. The converse is also possible; if + a <a href="thread.html" title="Class thread">thread</a> object is destroyed without + <code class="computeroutput">join()</code> first having been called, the thread of execution + continues until its initial function completes.</div> +<div class="refsect2" lang="en"> +<a name="id1563577"></a><h3> +<a name="threadconstruct-copy-destruct"></a><code class="computeroutput">thread</code> construct/copy/destruct</h3> +<div class="orderedlist"><ol type="1"> +<li> +<pre class="literallayout"><a name="id698281-bb"></a>thread();</pre> +<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + Constructs a <a href="thread.html" title="Class thread">thread</a> object + 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>: + + <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>: + + <span class="bold"><strong>Danger:</strong></span><code class="computeroutput">*this</code> is valid only within the current thread.</p> +</li> +<li> +<pre class="literallayout"><span class="bold"><strong>explicit</strong></span> <a name="id1291929-bb"></a>thread(<span class="bold"><strong>const</strong></span> boost::function0<<span class="bold"><strong>void</strong></span>>& threadfunc);</pre> +<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + + Starts a new thread of execution and constructs a + <a href="thread.html" title="Class thread">thread</a> object representing it. + Copies <code class="computeroutput">threadfunc</code> (which in turn copies + the function object wrapped by <code class="computeroutput">threadfunc</code>) + to an internal location which persists for the lifetime + of the new thread of execution. Calls <code class="computeroutput">operator()</code> + on the copy of the <code class="computeroutput">threadfunc</code> function object + in the new thread of execution. + <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> is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Throws</span></b>: + + <code class="computeroutput">boost::thread_resource_error</code> if a new thread + of execution cannot be started.</p> +</li> +<li> +<pre class="literallayout"><a name="id732677-bb"></a>~thread();</pre> +<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + Destroys <code class="computeroutput">*this</code>. The actual thread of + execution may continue to execute after the + <a href="thread.html" title="Class thread">thread</a> object has been destroyed. + <br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>: + + If <code class="computeroutput">*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 <a href="thread.html" title="Class thread">thread</a> object is destroyed, call + <code class="computeroutput">join()</code>.</p> +</li> +</ol></div> +</div> +<div class="refsect2" lang="en"> +<a name="id1563816"></a><h3> +<a name="id1145095-bb"></a><code class="computeroutput">thread</code> comparison</h3> +<div class="orderedlist"><ol type="1"> +<li> +<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1138943-bb"></a><span class="bold"><strong>operator</strong></span>==( rhs) <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>: + + The thread is non-terminated or <code class="computeroutput">*this</code> + is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>: + + <code class="computeroutput">true</code> if <code class="computeroutput">*this</code> and + <code class="computeroutput">rhs</code> represent the same thread of + execution.</p> +</li> +<li> +<pre class="literallayout"><span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1288634-bb"></a><span class="bold"><strong>operator</strong></span>!=( rhs) <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>: + + The thread is non-terminated or <code class="computeroutput">*this</code> + is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Returns</span></b>: + + <code class="computeroutput">!(*this==rhs)</code>.</p> +</li> +</ol></div> +</div> +<div class="refsect2" lang="en"> +<a name="id1563958"></a><h3> +<a name="id1007431-bb"></a><code class="computeroutput">thread</code> modifier</h3> +<div class="orderedlist"><ol type="1"><li> +<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1253588-bb"></a>join();</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</code> is joinable.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + The current thread of execution blocks until the + initial function of the thread of execution represented by + <code class="computeroutput">*this</code> finishes and all resources are + reclaimed.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></b>: + + If <code class="computeroutput">*this == thread()</code> the result is + implementation-defined. If the implementation doesn't + detect this the result will be + <a href="threads.html#threads.glossary.deadlock">deadlock</a>. + </p> +</li></ol></div> +</div> +<div class="refsect2" lang="en"> +<a name="id1564044"></a><h3> +<a name="id1178459-bb"></a><code class="computeroutput">thread</code> static</h3> +<div class="orderedlist"><ol type="1"> +<li> +<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id974656-bb"></a>sleep(<span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">xtime</a>& xt);</pre> +<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + The current thread of execution blocks until + <code class="computeroutput">xt</code> is reached.</p> +</li> +<li> +<pre class="literallayout"><span class="bold"><strong>static</strong></span> <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id1245828-bb"></a>yield();</pre> +<p><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Effects</span></b>: + + The current thread of execution is placed in the + <a href="threads.html#threads.glossary.thread-state">ready</a> + state.<br><b xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"><span class="term">Notes</span></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> +</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="timed_read_write_mutex.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="threads/reference.html#id1248802"><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> +</div> +</body> +</html> |