Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.emory.mathcs.backport.java.util.concurrent
Class ExecutorCompletionService

    java.lang.Object
      edu.emory.mathcs.backport.java.util.concurrent.ExecutorCompletionService

All Implemented Interfaces:
  CompletionService

public class ExecutorCompletionService
extends java.lang.Object
implements CompletionService

A `CompletionService` that uses a supplied `Executor` to execute tasks. This class arranges that submitted tasks are, upon completion, placed on a queue accessible using `take`. The class is lightweight enough to be suitable for transient use when processing groups of tasks.

Usage Examples. Suppose you have a set of solvers for a certain problem, each returning a value of some type `Result`, and would like to run them concurrently, processing the results of each of them that return a non-null value, in some method `use(Result r)`. You could write this as:

       void solve(Executor e,
                  Collection<Callable<Result>> solvers)
         throws InterruptedException, ExecutionException {
           CompletionService<Result> ecs
               = new ExecutorCompletionService<Result>(e);
           for (Callable<Result> s : solvers)
               ecs.submit(s);
           int n = solvers.size();
           for (int i = 0; i < n; ++i) {
               Result r = ecs.take().get();
               if (r != null)
                   use(r);
           }
       }

Suppose instead that you would like to use the first non-null result of the set of tasks, ignoring any that encounter exceptions, and cancelling all other tasks when the first one is ready:

       void solve(Executor e,
                  Collection<Callable<Result>> solvers)
         throws InterruptedException {
           CompletionService<Result> ecs
               = new ExecutorCompletionService<Result>(e);
           int n = solvers.size();
           List<Future<Result>> futures
               = new ArrayList<Future<Result>>(n);
           Result result = null;
           try {
               for (Callable<Result> s : solvers)
                   futures.add(ecs.submit(s));
               for (int i = 0; i < n; ++i) {
                   try {
                       Result r = ecs.take().get();
                       if (r != null) {
                           result = r;
                           break;
                       }
                   } catch (ExecutionException ignore) {}
               }
           }
           finally {
               for (Future<Result> f : futures)
                   f.cancel(true);
           }

           if (result != null)
               use(result);
       }

Constructor Summary
`ExecutorCompletionService(Executor executor)` Creates an ExecutorCompletionService using the supplied executor for base task execution and a `LinkedBlockingQueue` as a completion queue.
`ExecutorCompletionService(Executor executor, BlockingQueue completionQueue)` Creates an ExecutorCompletionService using the supplied executor for base task execution and the supplied queue as its completion queue.

Method Summary
`Future` | `poll()` Retrieves and removes the Future representing the next completed task or `null` if none are present.
`Future` | `poll(long timeout, TimeUnit unit)` Retrieves and removes the Future representing the next completed task, waiting if necessary up to the specified wait time if none are yet present.
`Future` | `submit(Callable task)` Submits a value-returning task for execution and returns a Future representing the pending results of the task.
`Future` | `submit(java.lang.Runnable task, java.lang.Object result)` Submits a Runnable task for execution and returns a Future representing that task.
`Future` | `take()` Retrieves and removes the Future representing the next completed task, waiting if none are yet present.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ExecutorCompletionService

    public ExecutorCompletionService(Executor executor)

  Creates an ExecutorCompletionService using the supplied executor for base task execution and a `LinkedBlockingQueue` as a completion queue.

Parameters:
  `executor` - the executor to use
Throws:
  `java.lang.NullPointerException` - if executor is `null`

### ExecutorCompletionService

    public ExecutorCompletionService(Executor executor,
                                     BlockingQueue completionQueue)

  Creates an ExecutorCompletionService using the supplied executor for base task execution and the supplied queue as its completion queue.

Parameters:
  `executor` - the executor to use
  `completionQueue` - the queue to use as the completion queue normally one dedicated for use by this service
Throws:
  `java.lang.NullPointerException` - if executor or completionQueue are `null`

Method Detail

### submit

    public Future submit(Callable task)

  Description copied from interface: `CompletionService`
  Submits a value-returning task for execution and returns a Future representing the pending results of the task. Upon completion, this task may be taken or polled.

  Specified by:
    `submit` in interface `CompletionService`
  Parameters:
    `task` - the task to submit
  Returns:
    a Future representing pending completion of the task

### submit

    public Future submit(java.lang.Runnable task,
                         java.lang.Object result)

  Description copied from interface: `CompletionService`
  Submits a Runnable task for execution and returns a Future representing that task. Upon completion, this task may be taken or polled.

  Specified by:
    `submit` in interface `CompletionService`
  Parameters:
    `task` - the task to submit
    `result` - the result to return upon successful completion
  Returns:
    a Future representing pending completion of the task, and whose `get()` method will return the given result value upon completion

### take

    public Future take()
                throws java.lang.InterruptedException

  Description copied from interface: `CompletionService`
  Retrieves and removes the Future representing the next completed task, waiting if none are yet present.

  Specified by:
    `take` in interface `CompletionService`
  Returns:
    the Future representing the next completed task
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### poll

    public Future poll()

  Description copied from interface: `CompletionService`
  Retrieves and removes the Future representing the next completed task or `null` if none are present.

  Specified by:
    `poll` in interface `CompletionService`
  Returns:
    the Future representing the next completed task, or `null` if none are present

### poll

    public Future poll(long timeout,
                       TimeUnit unit)
                throws java.lang.InterruptedException

  Description copied from interface: `CompletionService`
  Retrieves and removes the Future representing the next completed task, waiting if necessary up to the specified wait time if none are yet present.

  Specified by:
    `poll` in interface `CompletionService`
  Parameters:
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    the Future representing the next completed task or `null` if the specified waiting time elapses before one is present
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD