Package edu.rit.pj

Class WorkerRegion

java.lang.Object

edu.rit.pj.WorkerConstruct

edu.rit.pj.WorkerRegion

Direct Known Subclasses:

FourBodyEnergyRegion, SelfEnergyRegion, ThreeBodyEnergyRegion, TwoBodyEnergyRegion

public abstract class WorkerRegion
extends WorkerConstruct

Class WorkerRegion is the abstract base class for a worker region that is executed by a WorkerTeam of threads distributed across the processes of a cluster parallel program.

To execute a worker region, create a WorkerTeam object; create an instance of a concrete subclass of class WorkerRegion; and pass this instance to the worker team's execute() method. You can do all this using an anonymous inner class; for example:

     new WorkerTeam().execute (new WorkerRegion()
         {
         public void start()
             {
             // Initialization code
             . . .
             }
         public void run()
             {
             // Parallel code
             . . .
             }
         public void finish()
             {
             // Finalization code
             . . .
             }
         });
 

The worker team's execute() method does the following. In each process, the worker team has a certain number of worker threads K, where K was specified when the worker team was constructed. In the highest-ranked process of the communicator, there is a master thread in addition to the worker threads. The main thread is the thread calling the worker team's execute() method. The main thread calls the worker region's start() method. When the start() method returns, all the worker threads, plus the master thread if any, call the worker region's run() method concurrently. When all the team threads have returned from the run() method, the main thread calls the worker region's finish() method. When the finish() method returns, the main thread returns from the worker team's execute() method.

The chief purpose of a worker team is to execute a work-sharing parallel loop in a cluster parallel program, partitioning the loop iterations among the worker threads in all the processes. The worker team uses the master-worker pattern to partition the iterations. The master thread partitions the loop iterations and sends tasks to the worker threads; the worker threads send results back to the master thread. The worker team uses a certain communicator to do this message passing. The communicator was specified when the worker team was constructed. For further information, see class WorkerIntegerForLoop and WorkerLongForLoop.

Within each process, variables to be shared by all threads in the team may be declared as fields of the WorkerRegion subclass. (Variables cannot be shared between processes.) The start() method is intended for performing initialization in a single thread before parallel execution begins. If no such initialization is needed, omit the start() method. The run() method contains code to be executed in parallel by all threads in the team. Variables that are private to each thread may be declared inside the run() method. The finish() method is intended for performing finalization in a single thread after parallel execution ends. If no such finalization is needed, omit the finish() method.

If the worker region's start() method throws an exception, the worker team's execute() method throws that same exception, and the run() method is not called.

If the worker region's run() method throws an exception in one of the team threads, the exception's stack trace is printed on the standard error, the worker team waits until all the other team threads have returned from the run() method, then the worker team's execute() method throws that same exception, and the worker region's finish() method is not called. If the worker region's run() method throws an exception in more than one of the team threads, each exception's stack trace is printed on the standard error, the worker team waits until all the other team threads have returned from the run() method, then the worker team's execute() method throws a MultipleParallelException wrapping all the thrown exceptions, and the worker region's finish() method is not called.

If the worker region's finish() method throws an exception, the worker team's execute() method throws that same exception.

Version:

07-Oct-2010

Author:

Alan Kaminsky

Constructor Summary

Constructors

Constructor	Description
WorkerRegion()	Construct a new worker region.

Method Summary

Modifier and Type	Method	Description
final void	execute(int first, int last, int stride, WorkerIntegerStrideForLoop theLoop)	Execute a worker for loop within this worker region.
final void	execute(int first, int last, WorkerIntegerForLoop theLoop)	Execute a worker for loop within this worker region.
final void	execute(long first, long last, long stride, WorkerLongStrideForLoop theLoop)	Execute a worker for loop within this worker region.
final void	execute(long first, long last, WorkerLongForLoop theLoop)	Execute a worker for loop within this worker region.
final <T> void	execute(Iterable<T> theIterable, WorkerIteration<T> theIteration)	Execute a worker iteration within this worker region.
final <T> void	execute(Iterator<T> theIterator, WorkerIteration<T> theIteration)	Execute a worker iteration within this worker region.
final <T> void	execute(T[] theArray, WorkerIteration<T> theIteration)	Execute a worker iteration within this worker region.
void	finish()	Perform finalization actions after parallel execution ends.
abstract void	run()	Execute parallel code.
void	start()	Perform initialization actions before parallel execution begins.

Methods inherited from class edu.rit.pj.WorkerConstruct

getThreadCount, getThreadIndex, getTotalThreadCount, isExecutingInParallel, isMasterThread, region, team

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

WorkerRegion

public WorkerRegion()

Construct a new worker region.

Method Details

start

public void start()
           throws Exception

Perform initialization actions before parallel execution begins. Only one thread in each process calls the start() method.

The start() method may be overridden in a subclass. If not overridden, the start() method does nothing.

Throws:

Exception - The start() method may throw any exception.

Exception - if any.

run

public abstract void run()
                  throws Exception

Execute parallel code. All threads of the worker team in each process call the run() method concurrently.

The run() method must be implemented in a subclass.

Throws:

Exception - The run() method may throw any exception.

Exception - if any.

finish

public void finish()
            throws Exception

Perform finalization actions after parallel execution ends. Only one thread in each process calls the finish() method.

The finish() method may be overridden in a subclass. If not overridden, the finish() method does nothing.

Throws:

Exception - The finish() method may throw any exception.

Exception - if any.

execute

public final void execute(int first,
 int last,
 WorkerIntegerForLoop theLoop)
                   throws Exception

Execute a worker for loop within this worker region. For further information, see class WorkerIntegerForLoop. The loop index goes from first (inclusive) to last (inclusive) in steps of +1. If first is greater than last, then no loop iterations are performed.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Parameters:

first - First loop index.

last - Last loop index.

theLoop - Worker for loop.

Throws:

NullPointerException - (unchecked exception) Thrown if theLoop is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theLoop's methods throws an exception.

Exception - if any.

execute

public final void execute(int first,
 int last,
 int stride,
 WorkerIntegerStrideForLoop theLoop)
                   throws Exception

Execute a worker for loop within this worker region. For further information, see class WorkerIntegerStrideForLoop. The loop index goes from first (inclusive) to last (inclusive) in steps of stride. The stride must be positive. If first is greater than last, then no loop iterations are performed.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Parameters:

first - First loop index.

last - Last loop index.

stride - Loop index stride, >= 1.

theLoop - Worker for loop.

Throws:

IllegalArgumentException - (unchecked exception) Thrown if stride < 1.

NullPointerException - (unchecked exception) Thrown if theLoop is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theLoop's methods throws an exception.

Exception - if any.

execute

public final void execute(long first,
 long last,
 WorkerLongForLoop theLoop)
                   throws Exception

Execute a worker for loop within this worker region. For further information, see class WorkerLongForLoop. The loop index goes from first (inclusive) to last (inclusive) in steps of +1. If first is greater than last, then no loop iterations are performed.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Parameters:

first - First loop index.

last - Last loop index.

theLoop - Worker for loop.

Throws:

NullPointerException - (unchecked exception) Thrown if theLoop is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theLoop's methods throws an exception.

Exception - if any.

execute

public final void execute(long first,
 long last,
 long stride,
 WorkerLongStrideForLoop theLoop)
                   throws Exception

Execute a worker for loop within this worker region. For further information, see class WorkerLongStrideForLoop. The loop index goes from first (inclusive) to last (inclusive) in steps of stride. The stride must be positive. If first is greater than last, then no loop iterations are performed.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Parameters:

first - First loop index.

last - Last loop index.

stride - Loop index stride, >= 1.

theLoop - Worker for loop.

Throws:

IllegalArgumentException - (unchecked exception) Thrown if stride < 1.

NullPointerException - (unchecked exception) Thrown if theLoop is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theLoop's methods throws an exception.

Exception - if any.

execute

public final <T> void execute(T[] theArray,
 WorkerIteration<T> theIteration)
                       throws Exception

Execute a worker iteration within this worker region. For further information, see class WorkerIteration. The items processed by the iteration are the elements of the given array. The iteration order is from index 0 upwards.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Type Parameters:

T - Data type of the items iterated over.

Parameters:

theArray - Array containing the items.

theIteration - Worker iteration.

Throws:

NullPointerException - (unchecked exception) Thrown if this is the master process and theArray is null. Thrown if theIteration is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theIteration's methods throws an exception.

Exception - if any.

execute

public final <T> void execute(Iterator<T> theIterator,
 WorkerIteration<T> theIteration)
                       throws Exception

Execute a worker iteration within this worker region. For further information, see class WorkerIteration. The items processed by the iteration are the items returned by the given iterator. The iteration order is that of the given iterator.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Type Parameters:

T - Data type of the items iterated over.

Parameters:

theIterator - Iterator over the items.

theIteration - Worker iteration.

Throws:

NullPointerException - (unchecked exception) Thrown if this is the master process and theIterator is null. Thrown if theIteration is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theIteration's methods throws an exception.

Exception - if any.

execute

public final <T> void execute(Iterable<T> theIterable,
 WorkerIteration<T> theIteration)
                       throws Exception

Execute a worker iteration within this worker region. For further information, see class WorkerIteration. The items processed by the iteration are the items contained in the given iterable collection. The iteration order is that of the given iterable collection's iterator.

Note: Either all threads in the worker team must call the execute() method with identical arguments, or none of the threads must call the execute() method.

Type Parameters:

T - Data type of the items iterated over.

Parameters:

theIterable - Iterable collection containing the items.

theIteration - Worker iteration.

Throws:

NullPointerException - (unchecked exception) Thrown if this is the master process and theIterable is null. Thrown if theIteration is null.

IllegalStateException - (unchecked exception) Thrown if no worker team is executing this worker region.

Exception - Thrown if one of theIteration's methods throws an exception.

Exception - if any.