Main Page   Namespace List   Class Hierarchy   Compound List   Compound Members  

ZThread::Barrier Class Template Reference

#include <Barrier.h>

Inheritance diagram for ZThread::Barrier::

ZThread::Lockable 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:
Generated at Fri Aug 31 09:07:59 2001 for ZThread by doxygen1.2.8 written by Dimitri van Heesch, © 1997-2001