Android APIs
public class

ExecutorCompletionService

extends Object
implements CompletionService<V>
java.lang.Object
   ↳ java.util.concurrent.ExecutorCompletionService<V>

Class Overview

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> solvers)
     throws InterruptedException, ExecutionException {
     CompletionService ecs
         = new ExecutorCompletionService(e);
     for (Callable 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> solvers)
     throws InterruptedException {
     CompletionService ecs
         = new ExecutorCompletionService(e);
     int n = solvers.size();
     List> futures
         = new ArrayList>(n);
     Result result = null;
     try {
         for (Callable 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 f : futures)
             f.cancel(true);
     }

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

Summary

Public Constructors
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.
Public Methods
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.
Future<V> take()
Retrieves and removes the Future representing the next completed task, waiting if none are yet present.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.concurrent.CompletionService

Public Constructors

public ExecutorCompletionService (Executor executor)

Added in API level 1

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

Parameters
executor Executor: the executor to use
Throws
NullPointerException if executor is null

public ExecutorCompletionService (Executor executor, BlockingQueue<Future<V>> completionQueue)

Added in API level 1

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

Parameters
executor Executor: the executor to use
completionQueue BlockingQueue: the queue to use as the completion queue normally one dedicated for use by this service. This queue is treated as unbounded -- failed attempted Queue.add operations for completed tasks cause them not to be retrievable.
Throws
NullPointerException if executor or completionQueue are null

Public Methods

public Future<V> poll ()

Added in API level 1

Retrieves and removes the Future representing the next completed task, or null if none are present.

Returns
Future<V> the Future representing the next completed task, or null if none are present

public Future<V> poll (long timeout, TimeUnit unit)

Added in API level 1

Retrieves and removes the Future representing the next completed task, waiting if necessary up to the specified wait time if none are yet present.

Parameters
timeout long: how long to wait before giving up, in units of unit
unit TimeUnit: a TimeUnit determining how to interpret the timeout parameter
Returns
Future<V> the Future representing the next completed task or null if the specified waiting time elapses before one is present
Throws
InterruptedException

public Future<V> submit (Callable<V> task)

Added in API level 1

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.

Parameters
task Callable: the task to submit
Returns
Future<V> a Future representing pending completion of the task

public Future<V> submit (Runnable task, V result)

Added in API level 1

Submits a Runnable task for execution and returns a Future representing that task. Upon completion, this task may be taken or polled.

Parameters
task Runnable: the task to submit
result V: the result to return upon successful completion
Returns
Future<V> a Future representing pending completion of the task, and whose get() method will return the given result value upon completion

public Future<V> take ()

Added in API level 1

Retrieves and removes the Future representing the next completed task, waiting if none are yet present.

Returns
Future<V> the Future representing the next completed task
Throws
InterruptedException