org.gridfour.util.concurrent

Class TaskGroupExecutor

java.lang.Object

java.util.concurrent.AbstractExecutorService

java.util.concurrent.ThreadPoolExecutor

org.gridfour.util.concurrent.TaskGroupExecutor

All Implemented Interfaces:

Executor, ExecutorService

public class TaskGroupExecutor
extends ThreadPoolExecutor

Extends the Java ThreadPoolExecutor class to add support for processing groups of tasks. The grouped tasks concept is useful when an expensive operation is parceled into separate tasks that can be run in parallel. In such cases, applications often require a mechanism for recognizing when all the subordinate tasks have completed.

This class is useful in special circumstances where a thread pool is an appropriate solution for an application. Developers who have requirements in this area may also consider the Java standard API classes CyclicBarrier and Phaser.

Using this class

You may use this class just as if it were a regular ThreadPoolExecutor. But if you wish to take advantage of the extended functionality, you may do so by applying the following steps:

1. CallgroupClear() to clear out any lingering elements from previous runs.
2. Rather than using the conventional execute() method to process Runnable instances, pass them to the groupExecute() method. This will register them for management as part of a task group.
3. Call the groupWaitUntilDone() method. This will monitor the executor until all runnables in the group have completed their work. Once the last runnable is finished, it will return control to the calling module.

The following code fragment gives an example use of the TaskGroupExecutor.

  static class Tester implements Runnable {
    String name;
    int delay;
    Tester(String name, int delay) {
      this.name = name;
      this.delay = delay;
    }

    @Override
    public void run() {
      System.out.println("  Start " + name + " " + Thread.currentThread().getName());
      try {
        Thread.sleep(delay * 1000);
      } catch (InterruptedException ex) {
      }
      System.out.println("  End   " + name);
    }
  }

  public static void main(String[] args) {
    System.out.println("Begin Test 1");
    TaskGroupExecutor exec = new TaskGroupExecutor(4);
    exec.groupExecute(new Tester("alpha  ", 13));
    exec.groupExecute(new Tester("beta   ", 5));
    exec.groupExecute(new Tester("gamma  ", 3));
    exec.groupExecute(new Tester("delta  ", 2));
    exec.groupWaitUntilDone();
    System.out.println("Completion of Test 1");

    System.out.println("\nBegin Test 2");
    exec.groupClearData();
    exec.groupExecute(new Tester("epsilon", 2));
    exec.groupExecute(new Tester("zeta   ", 2));
    exec.groupExecute(new Tester("eta    ", 2));
    exec.groupExecute(new Tester("theta  ", 2));
    exec.groupWaitUntilDone();
    System.out.println("Completion of Test 2");

    exec.shutdown();
 }
 

The output will appear as follows.

   Begin Test 1
   Start alpha   pool-1-thread-1
   Start delta   pool-1-thread-4
   Start gamma   pool-1-thread-3
   Start beta    pool-1-thread-2
   End   delta
   End   gamma
   End   beta
   End   alpha
 Completion of Test 1

 Begin Test 2
   Start epsilon pool-1-thread-4
   Start zeta    pool-1-thread-3
   Start eta     pool-1-thread-2
   Start theta   pool-1-thread-1
   End   theta
   End   eta
   End   zeta
   End   epsilon
 Completion of Test 2
 

Special treatment for afterExecute() This class depends on the afterExecute method associated with the base ThreadPoolExecutor class. If you wish to override that method in your own implementation, be sure to call super.afterExecute() are part of your code.

Nested Class Summary

Nested classes/interfaces inherited from class java.util.concurrent.ThreadPoolExecutor

ThreadPoolExecutor.AbortPolicy, ThreadPoolExecutor.CallerRunsPolicy, ThreadPoolExecutor.DiscardOldestPolicy, ThreadPoolExecutor.DiscardPolicy

Constructor Summary

Constructors

Constructor and Description
TaskGroupExecutor(int corePoolSize) Provides a simplified constructor which is customized for processing task groups.

Method Summary

Modifier and Type	Method and Description
protected void	afterExecute(Runnable r, Throwable t)
void	groupClear() Clears any lingering elements from previous groups.
void	groupExecute(Runnable runnable) Executes a given task sometime in the future.
boolean	groupWaitUntilDone() Waits until all tasks in the group have finished processing, then returns control to the calling module.

Methods inherited from class java.util.concurrent.ThreadPoolExecutor

allowCoreThreadTimeOut, allowsCoreThreadTimeOut, awaitTermination, beforeExecute, execute, finalize, getActiveCount, getCompletedTaskCount, getCorePoolSize, getKeepAliveTime, getLargestPoolSize, getMaximumPoolSize, getPoolSize, getQueue, getRejectedExecutionHandler, getTaskCount, getThreadFactory, isShutdown, isTerminated, isTerminating, prestartAllCoreThreads, prestartCoreThread, purge, remove, setCorePoolSize, setKeepAliveTime, setMaximumPoolSize, setRejectedExecutionHandler, setThreadFactory, shutdown, shutdownNow, terminated, toString

Methods inherited from class java.util.concurrent.AbstractExecutorService

invokeAll, invokeAll, invokeAny, invokeAny, newTaskFor, newTaskFor, submit, submit, submit

Methods inherited from class java.lang.Object

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

Constructor Detail

TaskGroupExecutor

public TaskGroupExecutor(int corePoolSize)

Provides a simplified constructor which is customized for processing task groups. In this constructor, a core pool of threads is allocated and made available for processing.

In practice, it is a good idea to call shutdown() on a ThreadPoolExecutor when it is no longer required. This constructor implements a 15-second timeout period after which idle threads will be terminated. If you would prefer to not use that functionality, feel free to create TaskGroupExecutor instances using any of the constructors from the parent ThreadPoolExecutor class which is part of the Java standard API.

Parameters:

corePoolSize - the number of threads to keep in the pool, even if they are idle, unless allowCoreThreadTimeOut is set.

Method Detail

afterExecute

protected void afterExecute(Runnable r,
                            Throwable t)

Overrides:

afterExecute in class ThreadPoolExecutor

groupExecute

public void groupExecute(Runnable runnable)

Executes a given task sometime in the future. Note that Java does not guarantee that jobs are executed in the order in which they are submitted.

Parameters:

runnable - the task to execute.

groupClear

public void groupClear()

Clears any lingering elements from previous groups. If the group execution completed successfully, no such lingering elements should exist. But it is good practice to call this method whenever beginning to execute a group of tasks.

groupWaitUntilDone

public boolean groupWaitUntilDone()

Waits until all tasks in the group have finished processing, then returns control to the calling module. When this method returns, an application can be certain that all tasks are finished. However, it does not carry information about the success of failure of those tasks. Mechanisms for handling such information, if required, must be implemented by application code.

Returns:

true if all tasks completed successfully; false if any task failed on an unhandled exception.