Package edu.rit.pj

Class 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 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.