Main Page   Namespace List   Class Hierarchy   Compound List   Namespace Members   Compound Members  

Waitable Class Reference

#include <Waitable.h>

Inheritance diagram for Waitable:

Barrier Condition Executor Future PriorityCondition ConcurrentExecutor PoolExecutor SynchronousExecutor ThreadedExecutor List of all members.

Public Methods

virtual ~Waitable () throw ()
 Destroy a Waitable object.

void wait ()
bool wait (unsigned long)

Detailed Description

Author:
Eric Crahen <crahen@cse.buffalo.edu>
Date:
<2002-06-04T07:40:39-0400>
Version:
2.2.1
The Waitable interface defines a common method of adding general wait semantics to an object. This is simply defined as waiting for some condition to occur, however the definition of that conditon is fluid in that it is left to specialization of this class to define.

The following text describes the specific meaning of wait semantics in more detail.

Waiting

An object implementng the Waitable interface externalizes a mechanism for testing some internal condition. Another object may wait()s for a Waitable object; in doing so, it wait()s for that condition to become true by blocking the caller while the condition is false.

Waitable objects may never wait for themselves. For example, an Waitable object that calls its own wait() method in its constructor or destructor would be considered to be waiting for itself. This may or may not lead to deadlock (depending on how an object extends wait semantics), but it should never be neccessary. A Waitable object is already privy to the condition it is exposing a waiting mechanism for; in other words, the information is already available within the object so it does not need to wait.

Other than the previous rule, Waiting semantics do not neccessarily provide any garuntees regarding nor does it place any restrictions on thread safety, preconditions, postconditions or even what constitutes the condition being wait()ed for or how a wait() is accomplised. It merly establishes the base for framework of more specialized meanings for wait.

The details of these semantics are refined further by specializaions of this class, but the general conotation remains intact.

For example, a Condition is Waitable object that extends wait semantics so that wait()ing means a thread is blocked until some external stimulus specifically performs an operation on the Condition to make its internal condition true. (serialization aside)

A Future extends wait semantics so that wait()ing means that a task completed somewhere and that some action be taken prior to the wait.

A Barrier extends wait semantics so that wait()ing mean waiting for other waiters, and may include automatically resetting the condition once a wait is complete.

Combining the Cancelable interface with the Waitable interface creates a method wait for an Excutor to complete its responisiblities, executing, which really means waiting for a number of things all at once.


Member Function Documentation

bool wait unsigned    long
 

Wait()ing on this object with a timeout will cause the calling thread to be blocked for, at most, some definite period of time. The thread executing will not proceed any further until the Waitable object releases it unless and exception is thrown.

The semantics for how and when a Waitable object decides to release a blocked thread are particular to each specialization of this class. The Waitable interface itself does not imply any garuntees about the state of the environment (serial or otherwise); however specializations of this interface may do so.

Parameters:
timeout  - maximum amount of time (milliseconds) this method could block
Returns :
bool, true if the wait() completed before the timeout expired. false otherwise.
Exceptions:
Interrupted_Exception  This exception may be thrown if the wait is aborted prematurely do to the thread being interrupt()ed before it begins or during the wait.
Synchronization_Exception  Thrown if the wait cannot be accomplished because of some other error.

Reimplemented in Barrier, ConcurrentExecutor, Condition, Executor, Future, PoolExecutor, PriorityCondition, SynchronousExecutor, and ThreadedExecutor.

void wait  
 

Wait()ing on this object will cause the calling thread to be blocked for some indefinite period of time. The thread executing will not proceed any further until the Waitable object releases it unless and exception is thrown.

The semantics for how and when a Waitable object decides to release a blocked thread are particular to each specialization of this class. The Waitable interface itself does not imply any garuntees about the state of the environment (serial or otherwise); however specializations of this interface may do so.

Exceptions:
Interrupted_Exception  This exception may be thrown if the wait is aborted prematurely do to the thread being interrupt()ed before it begins or during the wait.
Synchronization_Exception  Thrown if the wait cannot be accomplished because of some other error.

Reimplemented in Barrier, ConcurrentExecutor, Condition, Executor, Future, PoolExecutor, PriorityCondition, SynchronousExecutor, and ThreadedExecutor.


The documentation for this class was generated from the following file:
Generated on Tue Aug 27 07:43:16 2002 for ZThread by doxygen1.2.17