Condition Class Reference

#include <Condition.h>

Inheritance diagram for Condition:


Public Member Functions
	Condition (Lockable &l)
virtual	~Condition ()
	Destroy Condition object.
void	signal ()
void	broadcast ()
virtual void	wait ()
virtual bool	wait (unsigned long timeout)

Detailed Description

Author:: Eric Crahen <http://www.code-foo.com>

Date:: <2003-07-16T14:38:59-0400>

Version:: 2.2.1

A Condition is a Waitable object used to block a thread until a particular condition is met. A Condition object is always used in conjunction with Lockable object. This object should be a FastMutex, Mutex, PriorityMutex or PriorityInheritanceMutex.

Condition objects are reminiscent of POSIX condition variables in several ways but are slightly different.

A Condition is not subject to spurious wakeup.

Like all Waitable objects, Conditions are sensitive to Thread::interupt() which can be used to prematurely end a wait().

See also:: Thread::interupt()

Before a wait() is performed on a Condition, the associated Lockable object should have been acquire()ed. When the wait() begins, that Lockable object is release()d (wait() will atomically begin the wait and unlock the Lockable).

A thread blocked by wait() will remain so until an exception occurs, or until the thread awakened by a signal() or broadcast(). When the thread resumes execution, the associated Lockable is acquire()d before wait() returns.

Scheduling

Threads blocked on a Condition are resumed in FIFO order.

Constructor & Destructor Documentation

Condition

(

Lockable &

)

Create a Condition associated with the given Lockable object.

Parameters:

Lockable object to associate with this Condition object.

Member Function Documentation

void broadcast

(

)

Wake all threads wait()ing on this Condition.

The associated Lockable need not have been acquire when this function is invoked.

Postcondition:: all wait()ing threads, if any exist, will be awakened.

void signal

(

)

Wake one thread waiting on this Condition.

The associated Lockable need not have been acquire when this function is invoked.

Postcondition:: a waiting thread, if any exists, will be awakened.

virtual bool wait ( unsigned long timeout ) [virtual]

Wait for this Condition, blocking the calling thread until a signal or broadcast is received.

This operation atomically releases the associated Lockable and blocks the calling thread.

Parameters:

timeout

maximum amount of time (milliseconds) this method could block

Returns:

true if the Condition receives a signal or broadcast before timeout milliseconds elapse.
false otherwise.

Exceptions:

Interrupted_Exception

thrown when the calling thread is interrupted. A thread may be interrupted at any time, prematurely ending any wait.

Precondition:: The thread calling this method must have first acquired the associated Lockable object.

Postcondition:: A thread that has resumed execution without exception (because of a signal(), broadcast() or exception) will have acquire()d the associated Lockable object before returning from a wait().

See also:: Waitable::wait(unsigned long timeout)

Implements Waitable.

virtual void wait ( ) [virtual]