IlsBarrier

Category

Thread utility class - API FOR ADVANCED USERS

Inheritance Path

IlsMTBase
➥ IlsBarrier

Description

This class lets you define a barrier. 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.

Libraries

Header File

#include <ilserver/ilthread.h>

Synopsis

class IlsBarrier : public IlsMTBase

{

public:

IlsBarrier(long=0L,

IlsBarrierFunc=0,

IlsAny=0,

IlsUnsafeMutex*=0)

virtual ~IlsBarrier();

IlsBoolean newCount(long);

const long count() const;

const long waiting() const;

IlsWaitResult wait(long timeout_millisecs = -1L);

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

};

Constructor

IlsBarrier(long=0L,

IlsBarrierFunc=0,

IlsAny=0,

IlsUnsafeMutex*=0);

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.

Destructor

virtual ~IlsBarrier();

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 Functions

IlsBoolean 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.

const long 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.

const long waiting() const;

This member function determines the number of threads currently waiting at the barrier.

IlsWaitResult 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.

Operators

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

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