Wefts::Condition Class Reference
[Conditions]

#include <wefts_cond.h>

Inheritance diagram for Wefts::Condition:

Inheritance graph
[legend]
Collaboration diagram for Wefts::Condition:

Collaboration graph
[legend]
List of all members.

Detailed Description

Class implementing a condition variable.

This condition class is meant to be overloaded by classes using specific mutex types. To use it, you have to create your own class using a combination of this class plus a fast or a reentrant mutex. This is implemented in the wtFastCondition and wtRCondition classes.

Subclassess must set m_my_mutex to a valid Wefts::Mutex pointer (or any subclass of that).

All condition classes are implemented via inline calls to maximize execution speed; also, their metods are extremely small.


Public Member Functions

 Condition (Mutex *mtx=0)
 Initializes the internal data of the condition.

 ~Condition ()
virtual bool wait (CleanupHandler *cup=0, int pos=0)
 Waits for the condition to be active.

void setMutex (Mutex *mtx)
 Set the mutex used by this condition.

MutexgetMutex ()
virtual bool wait (long seconds, long nanoseconds, CleanupHandler *cup=0, int pos=0)
 Waits for the condition to be active up to a certain time.

bool wait (double seconds, CleanupHandler *cup=0, int pos=0)
 Waits for the condition to be active for a certain time.

virtual void signal ()
 Signals the condition, waking all waiting threads.

virtual void signalOne ()
 Signals the condition, waking one thread.


Protected Attributes

OSCondition m_cond
 Internal condition variable.

Mutexm_my_mutex
 Internal mutex.


Constructor & Destructor Documentation

Wefts::Condition::Condition Mutex mtx = 0  )  [inline]
 

Initializes the internal data of the condition.

Initialization of m_my_mutex member is left to subclasses.

Wefts::Condition::~Condition  )  [inline]
 


Member Function Documentation

Mutex* Wefts::Condition::getMutex  )  [inline]
 

void Wefts::Condition::setMutex Mutex mtx  )  [inline]
 

Set the mutex used by this condition.

Usually, this is used by subclasses, dervied both by conditionts and mutexes to set themselves as mutexes. It may also be used in 1:N mutexing schemes, where a single mutex (protecting a wide dataset) must be used by more than one condition (each willing to test part of that dataset).

virtual void Wefts::Condition::signal  )  [inline, virtual]
 

Signals the condition, waking all waiting threads.

When a condition is signaled all the waiting threads are given a chance to go.

virtual void Wefts::Condition::signalOne  )  [inline, virtual]
 

Signals the condition, waking one thread.

When a condition is signaled with this method, only one of the wating threads are awaken. This is only useful in situation where it can be prooved that

  1. a random thread among the waiting ones will surely find its condition test changed and
  2. only one thread would be able to proceed, blocking all the others. In this situation, waking all the threads just to have one able to proceed is clearly a waste. Applications will rarely need to use this method, as this pre-requisites can rarely be guaranteed. One example is Wefts++ implementation of semaphores, where, by design, only one thread can proceed when a former semaphore owning thread releases the semaphore just once.

bool Wefts::Condition::wait double  seconds,
CleanupHandler cup = 0,
int  pos = 0
[inline]
 

Waits for the condition to be active for a certain time.

Works as wait( long seconds, long nanoseconds), but the wait time can be expressed as a real number, 1.0 meaning a second.

Be sure to 1) don't stop a thread while waiting on a condition, 2) disable cancellation around a wait() or 3) set up a cancellation sequence (Condition cleanup).

Parameters:
cup the cleanup handler that superintends cancellation cleanup sequence.
pos an extra parameter for the cleanup handler, by which the handler may know what to do (if its gets called by multiple "positions" in the source code).
seconds time to wait for (seconds and fraction of seconds expressed as decimal part)
Returns:
true if condition is signaled, false otherwise.

virtual bool Wefts::Condition::wait long  seconds,
long  nanoseconds,
CleanupHandler cup = 0,
int  pos = 0
[inline, virtual]
 

Waits for the condition to be active up to a certain time.

This method works as wait() but returns (with nonzero value) if a certain time has elapsed.

If you call this function, you have to specify the amount of seconds and second fractions (expressed in nanoseconds) you want to wait for a single event to be risen. Granularity of the system greatly depends on underlying OS and process priviledges.

Be sure to 1) don't stop a thread while waiting on a condition, 2) disable cancellation around a wait() or 3) set up a cancellation sequence (Condition cleanup).

Parameters:
seconds integer count of seconds to wait for.
nanoseconds integer count of nanoseconds to wait for (maximum is 999,999,999).
cup the cleanup handler that superintends cancellation cleanup sequence.
pos an extra parameter for the cleanup handler, by which the handler may know what to do (if its gets called by multiple "positions" in the source code).
Returns:
true if condition is signaled, false on error.

virtual bool Wefts::Condition::wait CleanupHandler cup = 0,
int  pos = 0
[inline, virtual]
 

Waits for the condition to be active.

This method waits forever or until stopped by an external event (signal).

Be sure to 1) don't stop a thread while waiting on a condition, 2) disable cancellation around a wait() or 3) set up a cancellation sequence (Condition cleanup).

Returns:
true if condition is signaled, false on error.


Member Data Documentation

OSCondition Wefts::Condition::m_cond [protected]
 

Internal condition variable.

Mutex* Wefts::Condition::m_my_mutex [protected]
 

Internal mutex.

Subclasses are invited to set this mutex to an initialized specific kind of mutex at creation.


The documentation for this class was generated from the following file:
Generated on Tue Oct 5 14:57:02 2004 for Wefts by doxygen 1.3.7