Boost.Threads

Contents

Introduction

Classes

Class barrier

Class barrier synopsis

Class barrier constructors and destructor

Class barrier modifier functions

Example(s)

Introduction

Include the header <boost/thread/barrier.hpp> to define the class boost::barrier.

Classes

Class barrier

An object of class barrier 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.

See Formal Definitions for definitions of thread states blocked and ready. Note that "waiting" is a synonym for blocked.

Class barrier synopsis

namespace boost
{
    class barrier : private boost::noncopyable // Exposition only.
        // Class barrier meets the NonCopyable requirement.
    {
    public:
        barrier(size_t count);
        ~barrier();

        bool wait();
    };
};

Class barrier constructors and destructor

barrier(size_t count);

Effects: Constructs a barrier object that will cause count threads to block on a call to wait().

~barrier();

Effects: Destroys *this. If threads are still executing their wait() operations, the behavior for these threads is undefined.

Class barrier modifier functions

bool wait();

Effects: Wait until N threads call wait(), where N equals the count provided to the constructor for the barrier object.

Returns: Exactly one of the N threads will receive a return value of true, the others will receive a value of false. Precisely which thread receives the return value of true 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.

Danger: If the barrier is destroyed before wait() can return, the behavior is undefined.

Example(s)

#include <boost/thread/barrier.hpp>
#include <boost/thread/thread.hpp>
#include <boost/thread/mutex.hpp>
#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();

}

The output is:

Global Parameter=5

Revised 05 November, 2001

© Copyright Dave Moore and William E. Kempf 2001-2002. All Rights Reserved.

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.