Main Page   Namespace List   Class Hierarchy   Compound List   Compound Members  

ZThread::PoolExecutor Class Template Reference

#include <PoolExecutor.h>

Inheritance diagram for ZThread::PoolExecutor::

ZThread::AbstractExecutor ZThread::Executor ZThread::Cancelable List of all members.

Public Methods

 PoolExecutor (unsigned int min) throw ()
 PoolExecutor (unsigned int min, unsigned int max) throw ()
virtual ~PoolExecutor () throw ()
void setMax (unsigned int max) throw (Synchronization_Exception)
void setMin (unsigned int) throw (Synchronization_Exception)
unsigned int getMax () throw (Synchronization_Exception)
unsigned int getMin () throw (Synchronization_Exception)
virtual void execute (Runnable *task) throw (Synchronization_Exception)
virtual void join () throw (Synchronization_Exception)
virtual bool available () throw (Synchronization_Exception)
virtual unsigned int threadCount () throw (Synchronization_Exception)

Protected Types

typedef std::deque<Thread*> WorkerList
 Typedef.


Protected Methods

virtual ThreadcreateWorker ()
void addWorker () throw (Synchronization_Exception)
void removeWorker () throw (Synchronization_Exception)

Protected Attributes

WorkerList _activeWorkers
 Active worker threads.

WorkerList _unactiveWorkers
 Idle worker threads.

unsigned int _maxThreads
 Minimum.

unsigned int _minThreads
 Maximum.


Detailed Description

template<bool DAEMON> class ZThread::PoolExecutor

Date:
04-12-2001
Author:
Eric Crahen
Version:
1.3.4

This interface defines the basic outline needed to implement a LWP (light-weigh-process) execution mechanism.

An executor allows the efficient execution of a number of small unrelated 'Runnable' tasks, or LWP's without the over head of a large number of synchronization controls needed in a thread per task solution.

The executor itself contains heavy weight synchronization controls to do this, but it will not need new ones for each additional task. This overcomes resource problems thread-per-task designs must face

In general, executors queue tasks for execution by another thread or by a pool of threads. The queuing of task allows for a good deal of control over the order of execution.

STATIC/NON-STATIC EXECUTORS:

All static executors should be marked as Daemon's using the template parameter. If the executor is non-static then it should not be marked as a daemon.

Static executors will use the new daemon thread feature, and so static executors do not need to be join()ed - however, they still need to be cancel()ed. This allows static executors to complete thier tasks after main exits, and solves static deadlock & deconstruction problems.

 // Proper use of a static PoolExecutor
 
 static Executor *executor = new PoolExecutor<true>(THREAD_COUNT); 
 
 int main() {

   // Add tasks

   executor->cancel();

 }

Static executors can not be cancled from within thier destructors. The system will not execute the destructors for static objects until the threads have all been joined. Worker threads will not exit until the executor has been cancled. This will lead to a deadlock situation.

 // Proper use of a non-static PoolExecutor
 
 int main() {
 
   Executor *executor = new PoolExecutor<false>(THREAD_COUNT);

   // Add tasks

   executor->cancel();
   executor->join();
 }

A template parameter was chosen because it allows only the code needed to implement that type of executor to be used, and eliminates the need for a daemon flag within the executor and a series of constant checks to take the approriate action.

The template also better reflects the nature of the choice of executor type. A static executor will not change and suddenly not act static, and vice-versa.


Constructor & Destructor Documentation

PoolExecutor ( unsigned int min ) throw () [inline]
 

Create a new Executor that uses a pool of 'n' threads to execute submitted tasks.

Parameters:
unsigned   int - number of worker threads (n)
Parameters:
min  

PoolExecutor ( unsigned int min,
unsigned int max ) throw () [inline]
 

Create a new Executor that uses a pool of threads to execute submitted tasks.

Parameters:
unsigned   int - minimum number of worker threads
unsigned   int - maximum number of worker threads
bool   - daemon flag for static executors
Parameters:
min  
max  

~PoolExecutor ( ) throw () [virtual]
 

Destroy this Executor


Member Function Documentation

void addWorker ( ) throw (Synchronization_Exception) [inline, protected]
 

Internally used to manipulate the worker thread pool

Exceptions:
InterruptedException  

bool available ( ) throw (Synchronization_Exception) [inline, virtual]
 

Block until the executor becomes ready

Reimplemented from ZThread::AbstractExecutor.

Thread * createWorker ( ) [protected, virtual]
 

Create a new worker for the Executor, allows extedned classes to more easily special Worker objects w/o reimplementing the entire executor.

Reimplemented from ZThread::AbstractExecutor.

void execute ( Runnable * task ) throw (Synchronization_Exception) [inline, virtual]
 

Submit a new task

See also:
Executor::execute(Runnable*)
Parameters:
task  

Reimplemented from ZThread::Executor.

unsigned int getMax ( ) throw (Synchronization_Exception) [inline]
 

Get the current maximum number of threads

Returns:
unsigned int - current maximum
Exceptions:
Interrupted_Exception  

unsigned int getMin ( ) throw (Synchronization_Exception) [inline]
 

Get the current minimum number of threads

Returns:
unsigned int - current minimum
Exceptions:
Interrupted_Exception  

void join ( ) throw (Synchronization_Exception) [virtual]
 

Wait for this Executor to complete. The calling thread is blocked until the last task has been completed by this executor or until the calling thread has been interrupted.

Exceptions:
InterruptedException  

Reimplemented from ZThread::Executor.

void removeWorker ( ) throw (Synchronization_Exception) [inline, protected]
 

Internally used to manipulate the worker thread pool

Exceptions:
InterruptedException  

void setMax ( unsigned int max ) throw (Synchronization_Exception) [inline]
 

Change the maximum number of threads in the pool. As tasks are added to the Executor, more threads will be added as needed - up to the maximum number of worker threads set.

Parameters:
unsigned   int - new maximum number of worker threads.
Exceptions:
Interrupted_Exception  
Parameters:
max  

void setMin ( unsigned int ) throw (Synchronization_Exception) [inline]
 

Change the minimum number of threads in the pool. When currently running tasks complete, and the Thread executing the task completes it can be removed. A Thread will never be instantly killed because the minimum number of threads has changed. It is a gradual decline in the number of worker threads.

Parameters:
unsigned   int - new minimum number of worker threads.
Exceptions:
Interrupted_Exception  
Parameters:
int  

unsigned int threadCount ( ) throw (Synchronization_Exception) [inline, virtual]
 

Count of active threads operation on behalf of this executor

This does not guarantee that another thread won't have submitted a task that changes the number of executing threads before some action is taken in response to this. However, it is useful as a general heuristic

Returns:
unsigned int - current thread count of the internal worker pool
Exceptions:
InterruptedException  

Reimplemented from ZThread::Executor.


The documentation for this class was generated from the following file:
Generated at Fri Aug 31 09:08:01 2001 for ZThread by doxygen1.2.8 written by Dimitri van Heesch, © 1997-2001