org.threadly.concurrent.future

Class ListenableFutureTask<T>

java.lang.Object

java.util.concurrent.FutureTask<T>

org.threadly.concurrent.future.ListenableFutureTask<T>

Type Parameters:

T - The result object type returned by this future

All Implemented Interfaces:

java.lang.Runnable, java.util.concurrent.Future<T>, java.util.concurrent.RunnableFuture<T>, CallableContainer<T>, ListenableFuture<T>, ListenableRunnableFuture<T>

Direct Known Subclasses:

ExecuteOnGetFutureTask, ListenableFutureAdapterTask

public class ListenableFutureTask<T>
extends java.util.concurrent.FutureTask<T>
implements ListenableRunnableFuture<T>, CallableContainer<T>

This is a future which can be executed. Allowing you to construct the future with the interior work, submit it to an Executor, and then return this future.

Since:

1.0.0

Nested Class Summary

Nested classes/interfaces inherited from interface org.threadly.concurrent.future.ListenableFuture

ListenableFuture.ListenerOptimizationStrategy

Constructor Summary

Constructors

Constructor and Description
ListenableFutureTask(boolean recurring, java.util.concurrent.Callable<T> task) Constructs a runnable future with a callable work unit.
ListenableFutureTask(boolean recurring, java.util.concurrent.Callable<T> task, java.util.concurrent.Executor executingExecutor) Constructs a runnable future with a callable work unit.
ListenableFutureTask(boolean recurring, java.lang.Runnable task) Constructs a runnable future with a runnable work unit.
ListenableFutureTask(boolean recurring, java.lang.Runnable task, T result) Constructs a runnable future with a runnable work unit.
ListenableFutureTask(boolean recurring, java.lang.Runnable task, T result, java.util.concurrent.Executor executingExecutor) Constructs a runnable future with a runnable work unit.

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.Callable<T>	getContainedCallable() Call to get the contained callable held within the wrapper.
java.lang.Throwable	getFailure() Similar to Future.get() except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true.
java.lang.Throwable	getFailure(long timeout, java.util.concurrent.TimeUnit unit) Similar to Future.get(long, TimeUnit) except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true.
java.lang.StackTraceElement[]	getRunningStackTrace() A best effort to return the stack trace for for the executing thread of either this future, or a future which this depends on through the use of ListenableFuture.map(Function) or similar functions.
boolean	isCompletedExceptionally() Returns true if the future is both done and has completed with an error or was canceled.
ListenableFuture<T>	listener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimize) Add a listener to be called once the future has completed.
void	run()

Methods inherited from class java.util.concurrent.FutureTask

cancel, get, get, isCancelled, isDone

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.threadly.concurrent.future.ListenableFuture

callback, callback, callback, failureCallback, failureCallback, failureCallback, flatMap, flatMap, flatMap, flatMap, flatMapFailure, flatMapFailure, flatMapFailure, listener, listener, map, map, map, mapFailure, mapFailure, mapFailure, resultCallback, resultCallback, resultCallback, throwMap, throwMap, throwMap

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Constructor Detail

ListenableFutureTask

public ListenableFutureTask(boolean recurring,
                            java.lang.Runnable task)

Constructs a runnable future with a runnable work unit.

Parameters:

recurring - boolean to indicate if this task can run multiple times, and thus must be reset after each run

task - runnable to be run

ListenableFutureTask

public ListenableFutureTask(boolean recurring,
                            java.lang.Runnable task,
                            T result)

Constructs a runnable future with a runnable work unit.

Parameters:

recurring - boolean to indicate if this task can run multiple times, and thus must be reset after each run

task - runnable to be run

result - result to be provide after run has completed

ListenableFutureTask

public ListenableFutureTask(boolean recurring,
                            java.util.concurrent.Callable<T> task)

Constructs a runnable future with a callable work unit.

Parameters:

recurring - boolean to indicate if this task can run multiple times, and thus must be reset after each run

task - callable to be run

ListenableFutureTask

public ListenableFutureTask(boolean recurring,
                            java.lang.Runnable task,
                            T result,
                            java.util.concurrent.Executor executingExecutor)

Constructs a runnable future with a runnable work unit.

Parameters:

recurring - boolean to indicate if this task can run multiple times, and thus must be reset after each run

task - runnable to be run

result - result to be provide after run has completed

executingExecutor - Executor task will be run on for possible listener optimization, or null

ListenableFutureTask

public ListenableFutureTask(boolean recurring,
                            java.util.concurrent.Callable<T> task,
                            java.util.concurrent.Executor executingExecutor)

Constructs a runnable future with a callable work unit.

Parameters:

recurring - boolean to indicate if this task can run multiple times, and thus must be reset after each run

task - callable to be run

executingExecutor - Executor task will be run on for possible listener optimization, or null

Method Detail

run

public void run()

Specified by:

run in interface java.lang.Runnable

Specified by:

run in interface java.util.concurrent.RunnableFuture<T>

Overrides:

run in class java.util.concurrent.FutureTask<T>

listener

public ListenableFuture<T> listener(java.lang.Runnable listener,
                                    java.util.concurrent.Executor executor,
                                    ListenableFuture.ListenerOptimizationStrategy optimize)

Description copied from interface: ListenableFuture

Add a listener to be called once the future has completed. If the future has already finished, this will be called immediately.

If the provided Executor is null, the listener will execute on the thread which computed the original future (once it is done). If the future has already completed, the listener will execute immediately on the thread which is adding the listener.

Caution should be used when choosing to optimize the listener execution. If the listener is complex, or wanting to be run concurrent, this optimization could prevent that. In addition it will prevent other listeners from potentially being invoked until it completes. However if the listener is small / fast, this can provide significant performance gains. It should also be known that not all ListenableFuture implementations may be able to do such an optimization. Please see ListenableFuture.ListenerOptimizationStrategy javadocs for more specific details of what optimizations are available.

Specified by:

listener in interface ListenableFuture<T>

Parameters:

listener - the listener to run when the computation is complete

executor - Executor the listener should be ran on, or null

optimize - true to avoid listener queuing for execution if already on the desired pool

Returns:

Exactly this instance to add more listeners or other functional operations

getContainedCallable

public java.util.concurrent.Callable<T> getContainedCallable()

Description copied from interface: CallableContainer

Call to get the contained callable held within the wrapper.

Specified by:

getContainedCallable in interface CallableContainer<T>

Returns:

callable contained within wrapper, or null if none is contained

getRunningStackTrace

public java.lang.StackTraceElement[] getRunningStackTrace()

Description copied from interface: ListenableFuture

A best effort to return the stack trace for for the executing thread of either this future, or a future which this depends on through the use of ListenableFuture.map(Function) or similar functions. If there is no thread executing the future yet, or the future has already completed, then this will return null.

This is done without locking (though generating a stack trace still requires a JVM safe point), so the resulting stack trace is NOT guaranteed to be accurate. In most cases (particularly when blocking) this should be accurate though.

Specified by:

getRunningStackTrace in interface ListenableFuture<T>

Returns:

The stack trace currently executing the future, or null if unavailable

isCompletedExceptionally

public boolean isCompletedExceptionally()

Description copied from interface: ListenableFuture

Returns true if the future is both done and has completed with an error or was canceled. If this returns true the Throwable responsible for the error can be retrieved using ListenableFuture.getFailure();

Specified by:

isCompletedExceptionally in interface ListenableFuture<T>

Returns:

true if this ListenableFuture completed by a thrown Exception or was canceled

getFailure

public java.lang.Throwable getFailure()
                               throws java.lang.InterruptedException

Description copied from interface: ListenableFuture

Similar to Future.get() except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true. If the future has not completed yet this function will block until completion. If the future completed normally, this will return null.

Specified by:

getFailure in interface ListenableFuture<T>

Returns:

Throwable thrown in computing the future or null if completed normally

Throws:

java.lang.InterruptedException - If the current thread was interrupted while blocking

getFailure

public java.lang.Throwable getFailure(long timeout,
                                      java.util.concurrent.TimeUnit unit)
                               throws java.lang.InterruptedException,
                                      java.util.concurrent.TimeoutException

Description copied from interface: ListenableFuture

Similar to Future.get(long, TimeUnit) except instead of providing a result, this will provide a thrown exception if ListenableFuture.isCompletedExceptionally() returns true. If the future has not completed yet this function will block until completion. If the future completed normally, this will return null.

Specified by:

getFailure in interface ListenableFuture<T>

Parameters:

timeout - The maximum time to wait

unit - The time unit of the timeout argument

Returns:

Throwable thrown in computing the future or null if completed normally

Throws:

java.lang.InterruptedException - If the current thread was interrupted while blocking

java.util.concurrent.TimeoutException - If the timeout was reached before the future completed