IlsBarrier Class Reference

API FOR ADVANCED USERS – This class lets you define a barrier. More...

#include <ilserver/ilthread.h>

Inheritance diagram for IlsBarrier:

Public Member Functions
	IlsBarrier (long=0L, IlsBarrierFunc=0, IlsAny=0, IlsUnsafeMutex *=0)
	Constructor. More...
virtual	~IlsBarrier ()
	Destructor. More...
long	count () const
	This member function is used to get the number of threads to wait for at the barrier. More...
IlsBoolean	newCount (long)
	This member function is used to change the number of threads to wait for at any given time. More...
IlsWaitResult	wait (long timeout_millisecs=-1L)
	This member function must be called for each thread to be blocked until the last thread arrives. More...
long	waiting () const
	This member function determines the number of threads currently waiting at the barrier.
Public Member Functions inherited from IlsMTBase
virtual	~IlsMTBase ()
	This is the public virtual destructor for this class.
virtual IlsThreadObjectName	getName () const
	This member function returns the name of an object. More...

Friends
ostream &	operator<< (ostream &, const IlsBarrier &)
	This operator prints the name of the object to the output stream. More...

Detailed Description

API FOR ADVANCED USERS – This class lets you define a barrier.

Library: server
and mvcomp

A barrier is an object which allows synchronization by waiting until all specified threads have arrived at the barrier. As soon as the last thread arrives, the barrier is released and all the threads can continue. The use of a barrier implies that the number of threads waiting at the barrier is known. To use a barrier, you have to create an instance of the class, set the number of threads to wait for, and call the member function wait() for each thread. When the threads have been released, the barrier is automatically reset, and, as new threads arrive, the waiting count is incremented until the barrier reopens.

See also

IlsCond, IlsSafeMutex, IlsThread, IlsUnsafeMutex.

Constructor & Destructor Documentation

IlsBarrier()

IlsBarrier::IlsBarrier	(	long	= 0L,
		IlsBarrierFunc	= 0,
		IlsAny	= 0,
		IlsUnsafeMutex *	= 0
	)

Constructor.

The callback function IlsBarrierFunc can be used to perform an action when all the threads are waiting at the barrier and before the barrier is released. It is possible to provide the mutex to protect the barrier class as the last argument passed to the constructor.

The callback function is called under the control of the mutex so that the call is MT-safe. If other threads want to access the same data, it is necessary to provide a mutex to the barrier and have the other threads lock the mutex before accessing the data. For details, see IlsCond.

~IlsBarrier()

virtual IlsBarrier::~IlsBarrier ( )

virtual

Destructor.

It is an error to destroy a barrier while there are threads waiting. When a barrier is destroyed, it will not release any waiting threads as they use the barrier that has been destroyed.

Member Function Documentation

count()

long IlsBarrier::count

(

)

const

This member function is used to get the number of threads to wait for at the barrier.

It just returns the value passed to the constructor or changed by newcount().

newCount()

IlsBoolean IlsBarrier::newCount

(

long

)

This member function is used to change the number of threads to wait for at any given time.

If this member function is called with a value that is less than, or equal to, the number of threads already waiting, the barrier is released.

wait()

IlsWaitResult IlsBarrier::wait

(

long

timeout_millisecs = -1L

)

This member function must be called for each thread to be blocked until the last thread arrives.

When the last thread arrives (that is, when the number of waiting threads is equal to the count), it wakes up all the waiting threads and continues.

This member function can be called with a timeout. If the timeout is positive, then the function will wait the number of milliseconds requested before returning ILS_WAIT_TIMEOUT, unless the other threads called wait in the meantime. A return value of ILS_WAIT_OK means that the barrier was opened normally for all waiting threads.

Friends And Related Function Documentation

operator<<

ostream& operator<< ( ostream &  , const IlsBarrier &    )

friend

This operator prints the name of the object to the output stream.

This uses the method getName() to get the name of the condition variable. If the method getName() returns 0 then it uses a platform dependent value.