# ExecutorCompletionService

public class **ExecutorCompletionService** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
implements [CompletionService](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html)\<V\> A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html` that uses a supplied `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html`
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<>(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);
     }

<br />

### Public Constructor Summary

|---|---|
|   | [ExecutorCompletionService](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#ExecutorCompletionService(java.util.concurrent.Executor))([Executor](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html) executor) Creates an ExecutorCompletionService using the supplied executor for base task execution and a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingQueue.html` as a completion queue. |
|   | [ExecutorCompletionService](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#ExecutorCompletionService(java.util.concurrent.Executor,%20java.util.concurrent.BlockingQueue<java.util.concurrent.Future<V>>))([Executor](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html) executor, [BlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html)\<[Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>\> completionQueue) Creates an ExecutorCompletionService using the supplied executor for base task execution and the supplied queue as its completion queue. |

### Public Method Summary

|---|---|
| [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [poll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#poll(long,%20java.util.concurrent.TimeUnit))(long timeout, [TimeUnit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeUnit.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [poll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#poll())() Retrieves and removes the Future representing the next completed task, or `null` if none are present. |
| [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [submit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#submit(java.lang.Runnable,%20V))([Runnable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Runnable.html) task, V result) Submits a Runnable task for execution and returns a Future representing that task. |
| [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [submit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#submit(java.util.concurrent.Callable<V>))([Callable](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Callable.html)\<V\> task) Submits a value-returning task for execution and returns a Future representing the pending results of the task. |
| [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [take](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ExecutorCompletionService.html#take())() Retrieves and removes the Future representing the next completed task, waiting if none are yet present. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

From interface [java.util.concurrent.CompletionService](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html)

|---|---|
| abstract [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [poll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html#poll(long,%20java.util.concurrent.TimeUnit))(long timeout, [TimeUnit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeUnit.html) 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. |
| abstract [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [poll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html#poll())() Retrieves and removes the Future representing the next completed task, or `null` if none are present. |
| abstract [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [submit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html#submit(java.lang.Runnable,%20V))([Runnable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Runnable.html) task, V result) Submits a Runnable task for execution and returns a Future representing that task. |
| abstract [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [submit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html#submit(java.util.concurrent.Callable<V>))([Callable](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Callable.html)\<V\> task) Submits a value-returning task for execution and returns a Future representing the pending results of the task. |
| abstract [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\> | [take](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CompletionService.html#take())() Retrieves and removes the Future representing the next completed task, waiting if none are yet present. |

## Public Constructors

#### public
**ExecutorCompletionService**
([Executor](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html) executor)

Creates an ExecutorCompletionService using the supplied
executor for base task execution and a
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingQueue.html` as a completion queue.

##### Parameters

| executor | the executor to use |
|---|---|

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if executor is `null` |
|---|---|

#### public
**ExecutorCompletionService**
([Executor](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Executor.html) executor, [BlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html)\<[Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<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. This queue is treated as unbounded -- failed attempted `Queue.add` operations for completed tasks cause them not to be retrievable. |
|---|---|

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if executor or completionQueue are `null` |
|---|---|

## Public Methods

#### public [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>
**poll**
(long timeout, [TimeUnit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeUnit.html) 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.

##### 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/InterruptedException.html) |   |
|---|---|

#### public [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>
**poll**
()

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

##### Returns

- the Future representing the next completed task, or `null` if none are present

#### public [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>
**submit**
([Runnable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Runnable.html) 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.

##### 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

#### public [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>
**submit**
([Callable](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Callable.html)\<V\> task)

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 | the task to submit |
|---|---|

##### Returns

- a Future representing pending completion of the task

#### public [Future](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Future.html)\<V\>
**take**
()

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

##### Returns

- the Future representing the next completed task

##### Throws

| [InterruptedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/InterruptedException.html) |   |
|---|---|