Main Page Namespace List Class Hierarchy Compound List Compound Members

# ZThread::Barrier Class Template Reference

`#include <Barrier.h>`

Inheritance diagram for ZThread::Barrier::

List of all members.

## Public Methods
| Barrier (int thr, bool resets=true) throw (Synchronization_Exception)
virtual | ~Barrier () throw ()
virtual void | acquire () throw (Synchronization_Exception)
virtual bool | tryAcquire (unsigned long timeout) throw (Synchronization_Exception)
virtual void | release () throw (Synchronization_Exception)

## Detailed Description

### template<class LOCK = Mutex> class ZThread::Barrier

Author:
  Eric Crahen

Version:
  1.3.2

Date:
  04-01-2001

A barrier keeps a group of threads synchronized with one another in a medium grained control. A Barrier is created with a specific threshold {n} As threads try to acquire a Barrier they are blocked until the n threads have made the attempt. As the nth thread makes its attempt the other blocked threads are released.

This provides a simple mechanism for making sure all threads working on some data have reached a specific point before the program continues.

After enough threads have reached a Barriers threshold, the Barrier will reset and can be used again.

An example:

This very brief example attempts to illustrate several threads working on a shared set of data. These tasks may reach some critical point at which they want to be certain that no other threads are still working on that data.

     Barrier ready(4), restart(4)

     class RED : public Runnable {
     public:

     virtual ~RED() {}

     virtual void run() {

       try {

         // Start doing something to some shared data

         cout << "RED is waiting..." << endl;
         Thread::sleep(2000);

         ready.acquire(); // critical point
         restart.acquire();

      } catch(...) {
         cerr << "RED Unexcpected Exception!" << endl;
       }

      }

     };

     // BLUE() & GREEN() have similar definitions

     int main() {

       Thread th[3];

       RED r, BLUE b, GREEN g;

       th.run(&r);
       th.run(&b);
       th.run(&g);

       ready.acquire(); // After all the workers reach the barrier execution
                       // will continue

       // switch the data set or someother operation you need to be
       // sure the working threads will not interrupt
       ...
       restart.acquire(); // Unblock the threads waiting on this barrier

     }

NOTE: Barriers are generally more useful in SMP architectures

## Constructor & Destructor Documentation

Barrier ( | int thr,
| bool resets = true ) throw (Synchronization_Exception)`[inline]`

  | Create a new Barrier that waits for n threads. This is the threshold of the Barrier. Parameters:
  int | - number of threads to wait for (threshold)
  bool | - reset flag, when the n'th thread releases all blocked threads, a Barrier with flag set at creation will reset the internal count of the Barrier so it can be reused. A false reset flag causes the Barrier to become a 'dead' object; after it's first used (After meeting its threashold once and releasing waiters) it can not be reused and it will not block any threads
  Postcondition: Barrier will block until 'n' acquire()s have been performed. The n'th acquire will release all blocked threads Parameters:
  thr |
  resets |

~Barrier ( | ) throw ()`[inline, virtual]`

| Destroy the Barrier

## Member Function Documentation

void acquire ( | ) throw (Synchronization_Exception)`[inline, virtual]`

  | A thread attempting to invoke the acquire method of a Barrier will be blocked until enough threads have invoked the method and the threshold is met. Exceptions:
  Synchronization_Exception |
Reimplemented from ZThread::Lockable.

void release ( | ) throw (Synchronization_Exception)`[inline, virtual]`

  | The release method has no effect for a Barrier. A thread is simply blocked by an acquire() attempt or not. Exceptions:
  Synchronization_Exception |
Reimplemented from ZThread::Lockable.

bool tryAcquire ( | unsigned long timeout ) throw (Synchronization_Exception)`[inline, virtual]`

  | This method can be used to quickly test weather or not the Barrier is at it's threshold. If you chose a lock, such as a FastMutex, that does not support the tryAcquire method then this will block until the Barrier has reached its threshold. Parameters:
  long | - time out
  Returns: bool - If true, this means that one more thread acquire()ing the Barrier will release all blocked threads. If false, then the test is indeterminate. Exceptions:
  Synchronization_Exception |
  Parameters:
  timeout |
Reimplemented from ZThread::Lockable.

The documentation for this class was generated from the following file:

- Barrier.h