ExecutorCompletionService (Java 2 Platform SE 5.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java^TM 2 Platform
Standard Ed. 5.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

java.util.concurrent
Class ExecutorCompletionService<V>

java.lang.Object
  java.util.concurrent.ExecutorCompletionService<V>

All Implemented Interfaces:: CompletionService<V>

public class ExecutorCompletionService<V>
extends Object
implements CompletionService<V>
extends Object
implements CompletionService<V>

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<Future<V>> completionQueue)` Creates an ExecutorCompletionService using the supplied executor for base task execution and the supplied queue as its completion queue.

Method Summary
`Future<V>`	`poll()` Retrieves and removes the Future representing the next completed task or `null` if none are present.
`Future<V>`	`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<V>`	`submit(Callable<V> task)` Submits a value-returning task for execution and returns a Future representing the pending results of the task.
`Future<V>`	`submit(Runnable task, V result)` Submits a Runnable task for execution and returns a Future representing that task.Upon completion, this task may be taken or polled.
`Future<V>`	`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:: NullPointerException - if executor is null

ExecutorCompletionService

public ExecutorCompletionService(Executor executor,
                                 BlockingQueue<Future<V>> 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:: NullPointerException - if executor or completionQueue are null

Method Detail