CompletionService<V>
public class ExecutorCompletionService<V> extends Object implements CompletionService<V>
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> cs
= new ExecutorCompletionService<>(e);
solvers.forEach(cs::submit);
for (int i = solvers.size(); i > 0; i--) {
Result r = cs.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> cs
= new ExecutorCompletionService<>(e);
int n = solvers.size();
List<Future<Result>> futures = new ArrayList<>(n);
Result result = null;
try {
solvers.forEach(solver -> futures.add(cs.submit(solver)));
for (int i = n; i > 0; i--) {
try {
Result r = cs.take().get();
if (r != null) {
result = r;
break;
}
} catch (ExecutionException ignore) {}
}
} finally {
futures.forEach(future -> future.cancel(true));
}
if (result != null)
use(result);
}
Constructor | Description |
---|---|
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.
|
Modifier and Type | Method | Description |
---|---|---|
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(Runnable task,
V result) |
Submits a Runnable task for execution and returns a Future
representing that task.
|
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> |
take() |
Retrieves and removes the Future representing the next
completed task, waiting if none are yet present.
|
public ExecutorCompletionService(Executor executor)
LinkedBlockingQueue
as a completion queue.executor
- the executor to useNullPointerException
- if executor is null
public ExecutorCompletionService(Executor executor, BlockingQueue<Future<V>> completionQueue)
executor
- the executor to usecompletionQueue
- 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.NullPointerException
- if executor or completionQueue are null
public Future<V> submit(Callable<V> task)
CompletionService
submit
in interface CompletionService<V>
task
- the task to submitpublic Future<V> submit(Runnable task, V result)
CompletionService
submit
in interface CompletionService<V>
task
- the task to submitresult
- the result to return upon successful completionget()
method will return the given
result value upon completionpublic Future<V> take() throws InterruptedException
CompletionService
take
in interface CompletionService<V>
InterruptedException
- if interrupted while waitingpublic Future<V> poll()
CompletionService
null
if none are present.poll
in interface CompletionService<V>
null
if none are presentpublic Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException
CompletionService
poll
in interface CompletionService<V>
timeout
- how long to wait before giving up, in units of
unit
unit
- a TimeUnit
determining how to interpret the
timeout
parameternull
if the specified waiting time elapses
before one is presentInterruptedException
- if interrupted while waiting Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps