mirror of
https://github.com/boostorg/thread.git
synced 2026-01-23 18:12:12 +00:00
169 lines
6.6 KiB
HTML
169 lines
6.6 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
|
<title>Boost.Threads - Header <boost/thread/barrier.hpp></title>
|
|
</head>
|
|
<body link="#0000ff" vlink="#800080">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Threads</h1>
|
|
<h2 align="center">Header <<a href="../../../boost/thread/barrier.hpp">boost/thread/barrier.hpp</a>></h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<h2>Contents</h2>
|
|
<dl class="page-index">
|
|
<dt><a href="#introduction">Introduction</a></dt>
|
|
<dt><a href="#classes">Classes</a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-barrier">Class <code>barrier</code></a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-barrier-synopsis">Class <code>barrier</code> synopsis</a></dt>
|
|
<dt><a href="#class-barrier-ctors">Class <code>barrier</code> constructors
|
|
and destructor</a></dt>
|
|
<dt><a href="#class-barrier-modifiers">Class <code>barrier</code> modifier
|
|
functions</a></dt>
|
|
</dl>
|
|
</dl>
|
|
<dt><a href="#examples">Example(s)</a></dt>
|
|
</dl>
|
|
<hr>
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
<p>Include the header <<a href="../../../boost/thread/barrier.hpp">boost/thread/barrier.hpp</a>>
|
|
to define the class <code>boost::barrier</code>.</p>
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
<h3><a name="class-barrier"></a>Class <code>barrier</code></h3>
|
|
<p>An object of class <code>barrier</code> is a synchronization primitive used
|
|
to cause a set of threads to wait until they each perform a certain function
|
|
or each reach a particular point in their execution. When a barrier is created,
|
|
it is initialized with a thread count "N". The first N-1 calls to wait() will
|
|
all cause their threads to be blocked. The Nth call to wait() will allow all
|
|
of the waiting threads, including the Nth thread, to be placed in a ready state.
|
|
Should an additional thread make an N+1th call to wait() on the barrier, it
|
|
will be as though this was the first call to wait(), and the process will be
|
|
repeated until another N threads call wait(). This functionality allows the
|
|
same set of N threads to re-use a barrier object to synchronize their execution
|
|
at multiple points during their execution.</p>
|
|
<p>See <A href="definitions.html">Formal Definitions</A> for definitions of thread
|
|
states <A href="definitions.html#state">blocked</A> and <A href="definitions.html#state">
|
|
ready</A>. Note that "waiting" is a synonym for blocked.</p>
|
|
<h4><a name="class-barrier-synopsis"></a>Class <code>barrier</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
class barrier : private <A href="../../utility/utility.htm#Class noncopyable">boost::noncopyable</A> // Exposition only.
|
|
// Class barrier meets the <A href="overview.html#NonCopyable" .. utility.htm#Class? utility>NonCopyable</A> requirement.
|
|
{
|
|
public:
|
|
barrier(size_t count);
|
|
~barrier();
|
|
|
|
bool wait();
|
|
};
|
|
};
|
|
</pre>
|
|
<h4><a name="class-barrier-ctors"></a>Class <code>barrier</code> constructors
|
|
and destructor</h4>
|
|
<pre>
|
|
barrier(size_t count);
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Constructs a <code>barrier</code> object that will cause
|
|
count threads to block on a call to <code>wait()</code>.</dt>
|
|
</dl>
|
|
<pre>
|
|
~barrier();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Destroys <code>*this</code>. If threads are still executing
|
|
their <code>wait()</code> operations, the behavior for these threads is undefined.</dt>
|
|
</dl>
|
|
<h4><a name="class-barrier-modifiers"></a>Class <code>barrier</code> modifier
|
|
functions</h4>
|
|
<pre>
|
|
bool wait();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Wait until N threads call wait(), where N equals the count
|
|
provided to the constructor for the barrier object.</dt>
|
|
<dt><b>Returns:</b> Exactly one of the N threads will receive a return value
|
|
of <code>true</code>, the others will receive a value of <code>false</code>.
|
|
Precisely which thread receives the return value of <code>true</code> will
|
|
be implementation defined. Applications can use this value to designate one
|
|
thread as a leader that will take a certain action, and the other threads
|
|
emerging from the barrier can wait for that action to take place.</dt>
|
|
<dt><b>Danger:</b> If the barrier is destroyed before <code>wait()</code> can
|
|
return, the behavior is undefined.</dt>
|
|
</dl>
|
|
<h2><a name="examples"></a>Example(s)</h2>
|
|
<pre>
|
|
#include <a href="../../../boost/thread/condition.hpp"><boost/thread/barrier.hpp></a>
|
|
#include <a href="../../../boost/thread/thread.hpp"><boost/thread/thread.hpp></a>
|
|
#include <a href="../../../boost/thread/mutex.hpp"><boost/thread/mutex.hpp></a>
|
|
#include <iostream>
|
|
|
|
const int N_THREADS = 10;
|
|
boost::barrier gen_barrier(N_THREADS);
|
|
int global_parameter = 0;
|
|
boost::mutex mutex;
|
|
|
|
static void worker()
|
|
{
|
|
for (int i = 0; i < 5; ++i)
|
|
{
|
|
// Simulate 5 cycles of computation...
|
|
if (gen_barrier.wait())
|
|
{
|
|
boost::mutex::scoped_lock lock(mutex);
|
|
global_parameter++;
|
|
}
|
|
}
|
|
|
|
// Let one worker "report" the results
|
|
if (gen_barrier.wait())
|
|
{
|
|
boost::mutex::scoped_lock lock(lock);
|
|
std::cout << "Global Parameter=" << global_parameter << "\n";
|
|
}
|
|
}
|
|
|
|
int main(int, char*[])
|
|
{
|
|
boost::thread_group g;
|
|
global_parameter = 0;
|
|
|
|
for (int i = 0; i < N_THREADS; ++i)
|
|
g.create_thread(&worker);
|
|
|
|
g.join_all();
|
|
|
|
}
|
|
</pre>
|
|
<p>The output is:</p>
|
|
<pre>
|
|
Global Parameter=5
|
|
</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:jdmoore99@comcast.net">Dave Moore</a> and <a href="mailto:wekempf@cox.net">William E. Kempf</a> 2001-2002.
|
|
All Rights Reserved.</i></p>
|
|
<p>Permission to use, copy, modify, distribute and sell this software and its
|
|
documentation for any purpose is hereby granted without fee, provided that the
|
|
above copyright notice appear in all copies and that both that copyright notice
|
|
and this permission notice appear in supporting documentation. William E. Kempf
|
|
makes no representations about the suitability of this software for any purpose.
|
|
It is provided "as is" without express or implied warranty.</p>
|
|
</body>
|
|
</html>
|