java.util.concurrent
Class ExecutorCompletionService<V>

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.util.concurrent.ExecutorCompletionService<V>
All Implemented Interfaces:
CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>

public class ExecutorCompletionService<V>
extends Object sample code for java.lang.Object definition code for java.lang.Object
implements CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>

A CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService that uses a supplied Executor sample code for java.util.concurrent.Executor definition code for java.util.concurrent.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 sample code for java.util.concurrent.ExecutorCompletionService.ExecutorCompletionService(java.util.concurrent.Executor) definition code for java.util.concurrent.ExecutorCompletionService.ExecutorCompletionService(java.util.concurrent.Executor) (Executor sample code for java.util.concurrent.Executor definition code for java.util.concurrent.Executor  executor)
          Creates an ExecutorCompletionService using the supplied executor for base task execution and a LinkedBlockingQueue sample code for java.util.concurrent.LinkedBlockingQueue definition code for java.util.concurrent.LinkedBlockingQueue as a completion queue.
ExecutorCompletionService sample code for java.util.concurrent.ExecutorCompletionService.ExecutorCompletionService(java.util.concurrent.Executor, java.util.concurrent.BlockingQueue) definition code for java.util.concurrent.ExecutorCompletionService.ExecutorCompletionService(java.util.concurrent.Executor, java.util.concurrent.BlockingQueue) (Executor sample code for java.util.concurrent.Executor definition code for java.util.concurrent.Executor  executor, BlockingQueue sample code for java.util.concurrent.BlockingQueue definition code for java.util.concurrent.BlockingQueue <Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.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 sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> poll sample code for java.util.concurrent.ExecutorCompletionService.poll() definition code for java.util.concurrent.ExecutorCompletionService.poll() ()
          Retrieves and removes the Future representing the next completed task or null if none are present.
 Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> poll sample code for java.util.concurrent.ExecutorCompletionService.poll(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.ExecutorCompletionService.poll(long, java.util.concurrent.TimeUnit) (long timeout, TimeUnit sample code for java.util.concurrent.TimeUnit definition code for java.util.concurrent.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 sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> submit sample code for java.util.concurrent.ExecutorCompletionService.submit(java.util.concurrent.Callable) definition code for java.util.concurrent.ExecutorCompletionService.submit(java.util.concurrent.Callable) (Callable sample code for java.util.concurrent.Callable definition code for java.util.concurrent.Callable <V> task)
          Submits a value-returning task for execution and returns a Future representing the pending results of the task.
 Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> submit sample code for java.util.concurrent.ExecutorCompletionService.submit(java.lang.Runnable, V) definition code for java.util.concurrent.ExecutorCompletionService.submit(java.lang.Runnable, V) (Runnable sample code for java.lang.Runnable definition code for java.lang.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 sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> take sample code for java.util.concurrent.ExecutorCompletionService.take() definition code for java.util.concurrent.ExecutorCompletionService.take() ()
          Retrieves and removes the Future representing the next completed task, waiting if none are yet present.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Constructor Detail

ExecutorCompletionService sample code for java.util.concurrent.ExecutorCompletionService(java.util.concurrent.Executor) definition code for java.util.concurrent.ExecutorCompletionService(java.util.concurrent.Executor)

public ExecutorCompletionService(Executor sample code for java.util.concurrent.Executor definition code for java.util.concurrent.Executor  executor)
Creates an ExecutorCompletionService using the supplied executor for base task execution and a LinkedBlockingQueue sample code for java.util.concurrent.LinkedBlockingQueue definition code for java.util.concurrent.LinkedBlockingQueue as a completion queue.

Parameters:
executor - the executor to use
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if executor is null

ExecutorCompletionService sample code for java.util.concurrent.ExecutorCompletionService(java.util.concurrent.Executor, java.util.concurrent.BlockingQueue<java.util.concurrent.Future<V>>) definition code for java.util.concurrent.ExecutorCompletionService(java.util.concurrent.Executor, java.util.concurrent.BlockingQueue<java.util.concurrent.Future<V>>)

public ExecutorCompletionService(Executor sample code for java.util.concurrent.Executor definition code for java.util.concurrent.Executor  executor,
                                 BlockingQueue sample code for java.util.concurrent.BlockingQueue definition code for java.util.concurrent.BlockingQueue <Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.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 sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if executor or completionQueue are null
Method Detail

submit sample code for java.util.concurrent.ExecutorCompletionService.submit(java.util.concurrent.Callable<V>) definition code for java.util.concurrent.ExecutorCompletionService.submit(java.util.concurrent.Callable<V>)

public Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> submit(Callable sample code for java.util.concurrent.Callable definition code for java.util.concurrent.Callable <V> task)
Description copied from interface: CompletionService sample code for java.util.concurrent.CompletionService.submit(java.util.concurrent.Callable) definition code for java.util.concurrent.CompletionService.submit(java.util.concurrent.Callable)
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 sample code for java.util.concurrent.CompletionService.submit(java.util.concurrent.Callable) definition code for java.util.concurrent.CompletionService.submit(java.util.concurrent.Callable) in interface CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>
Parameters:
task - the task to submit
Returns:
a Future representing pending completion of the task

submit sample code for java.util.concurrent.ExecutorCompletionService.submit(java.lang.Runnable, V) definition code for java.util.concurrent.ExecutorCompletionService.submit(java.lang.Runnable, V)

public Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> submit(Runnable sample code for java.lang.Runnable definition code for java.lang.Runnable  task,
                        V result)
Description copied from interface: CompletionService sample code for java.util.concurrent.CompletionService.submit(java.lang.Runnable, V) definition code for java.util.concurrent.CompletionService.submit(java.lang.Runnable, V)
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 sample code for java.util.concurrent.CompletionService.submit(java.lang.Runnable, V) definition code for java.util.concurrent.CompletionService.submit(java.lang.Runnable, V) in interface CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>
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 sample code for java.util.concurrent.ExecutorCompletionService.take() definition code for java.util.concurrent.ExecutorCompletionService.take()

public Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> take()
               throws InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException 
Description copied from interface: CompletionService sample code for java.util.concurrent.CompletionService.take() definition code for java.util.concurrent.CompletionService.take()
Retrieves and removes the Future representing the next completed task, waiting if none are yet present.

Specified by:
take sample code for java.util.concurrent.CompletionService.take() definition code for java.util.concurrent.CompletionService.take() in interface CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>
Returns:
the Future representing the next completed task
Throws:
InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException - if interrupted while waiting.

poll sample code for java.util.concurrent.ExecutorCompletionService.poll() definition code for java.util.concurrent.ExecutorCompletionService.poll()

public Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> poll()
Description copied from interface: CompletionService sample code for java.util.concurrent.CompletionService.poll() definition code for java.util.concurrent.CompletionService.poll()
Retrieves and removes the Future representing the next completed task or null if none are present.

Specified by:
poll sample code for java.util.concurrent.CompletionService.poll() definition code for java.util.concurrent.CompletionService.poll() in interface CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>
Returns:
the Future representing the next completed task, or null if none are present.

poll sample code for java.util.concurrent.ExecutorCompletionService.poll(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.ExecutorCompletionService.poll(long, java.util.concurrent.TimeUnit)

public Future sample code for java.util.concurrent.Future definition code for java.util.concurrent.Future <V> poll(long timeout,
                      TimeUnit sample code for java.util.concurrent.TimeUnit definition code for java.util.concurrent.TimeUnit  unit)
               throws InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException 
Description copied from interface: CompletionService sample code for java.util.concurrent.CompletionService.poll(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.CompletionService.poll(long, java.util.concurrent.TimeUnit)
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 sample code for java.util.concurrent.CompletionService.poll(long, java.util.concurrent.TimeUnit) definition code for java.util.concurrent.CompletionService.poll(long, java.util.concurrent.TimeUnit) in interface CompletionService sample code for java.util.concurrent.CompletionService definition code for java.util.concurrent.CompletionService <V>
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:
InterruptedException sample code for java.lang.InterruptedException definition code for java.lang.InterruptedException - if interrupted while waiting.