io.atlassian.util.concurrent

Class AsyncCompleter

java.lang.Object

io.atlassian.util.concurrent.AsyncCompleter

@ThreadSafe
public final class AsyncCompleter
extends Object

Convenient encapsulation of CompletionService usage that allows a collection of jobs to be issued to an Executor and return an Iterable of the results that is in the order that the results return.

Unlike ExecutorService.invokeAll(java.util.Collection) invokeAll(Iterable) here does not itself block, rather the Iterator.next() calls to the returned Iterable will block the first time it is iterated. This allows the client to defer the reification of the result until it is ready to use it.

To create an instance of this class, please use the supplied AsyncCompleter.Builder.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AsyncCompleter.Builder For creating instances of AsyncCompleter.
static interface	AsyncCompleter.ExecutorCompletionServiceFactory Extension point if a custom CompletionService is required, for instance to implement a custom concellation policy.

Method Summary

Modifier and Type	Method and Description
<T> Iterable<T>	invokeAll(Iterable<? extends Callable<T>> callables) Queue the jobs on the contained Executor and return a lazily evaluated Iterable of the results in the order they return in (fastest first).
<T> Iterable<T>	invokeAll(Iterable<? extends Callable<T>> callables, long time, TimeUnit unit) Version of invokeAll(Iterable) that supports a timeout.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

invokeAll

public <T> Iterable<T> invokeAll(Iterable<? extends Callable<T>> callables)

Queue the jobs on the contained Executor and return a lazily evaluated Iterable of the results in the order they return in (fastest first).

Note that if any of the jobs return null then nulls WILL BE included in the results. Similarly if an exception is thrown and exceptions are being ignored then there will be a NULL result returned. If you want to filter nulls this is trivial, but be aware that filtering of the results forces Iterator.next() to be called while calling Iterator.hasNext() (which may block).

Type Parameters:

T - the result type

Parameters:

callables - the jobs to run

Returns:

an Iterable that returns the results in the order in which they return, excluding any null values.

invokeAll

public <T> Iterable<T> invokeAll(Iterable<? extends Callable<T>> callables,
                                 long time,
                                 TimeUnit unit)

Version of invokeAll(Iterable) that supports a timeout. Any jobs that are not complete by the timeout are interrupted and discarded.

Type Parameters:

T - the result type

Parameters:

callables - the jobs to run

time - the max time spent per job specified by:

unit - the TimeUnit time is specified in

Returns:

an Iterable that returns the results in the order in which they return, excluding any null values.

Since:

2.1

See Also:

invokeAll(Iterable)