org.threadly.concurrent.future

Class CancelDebuggingListenableFuture<T>

java.lang.Object

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

Type Parameters:

T - Type of result provided by this ListenableFuture

All Implemented Interfaces:

java.util.concurrent.Future<T>, ListenableFuture<T>

public class CancelDebuggingListenableFuture<T>
extends java.lang.Object
implements ListenableFuture<T>

Wrapper for a ListenableFuture to provide enhanced features for debugging the state at which at which it was canceled. When a cancel request comes in this class will attempt to record the stack trace of the delegateFuture. If it then cancels, and is able to get a stack trace from the processing thread at time of cancellation, then any requests to get() that result in a CancellationException, the exception will have a cause of CancelDebuggingListenableFuture.FutureProcessingStack with the previous stack trace included.

Since:

5.28

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CancelDebuggingListenableFuture.FutureProcessingStack Throwable that is not thrown, but instead added as a cause to indicate the processing stack trace at the time of cancellation.

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

ListenableFuture.ListenerOptimizationStrategy

Constructor Summary

Constructors

Constructor and Description
CancelDebuggingListenableFuture(ListenableFuture<T> delegateFuture) Construct a new CancelDebuggingListenableFuture by wrapping the provided future.

Method Summary

Modifier and Type	Method and Description
boolean	cancel(boolean interrupt)
T	get()
T	get(long arg0, java.util.concurrent.TimeUnit arg1)
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	isCancelled()
boolean	isCompletedExceptionally() Returns true if the future is both done and has completed with an error or was canceled.
boolean	isDone()
ListenableFuture<T>	listener(java.lang.Runnable listener, java.util.concurrent.Executor executor, ListenableFuture.ListenerOptimizationStrategy optimizeExecution) Add a listener to be called once the future has completed.

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

Constructor Detail

CancelDebuggingListenableFuture

public CancelDebuggingListenableFuture(ListenableFuture<T> delegateFuture)

Construct a new CancelDebuggingListenableFuture by wrapping the provided future.

Parameters:

delegateFuture - A non-null future to wrap

Method Detail

cancel

public boolean cancel(boolean interrupt)

Specified by:

cancel in interface java.util.concurrent.Future<T>

get

public T get()
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException

Specified by:

get in interface java.util.concurrent.Future<T>

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

get

public T get(long arg0,
             java.util.concurrent.TimeUnit arg1)
      throws java.lang.InterruptedException,
             java.util.concurrent.ExecutionException,
             java.util.concurrent.TimeoutException

Specified by:

get in interface java.util.concurrent.Future<T>

Throws:

java.lang.InterruptedException

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException

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

isCancelled

public boolean isCancelled()

Specified by:

isCancelled in interface java.util.concurrent.Future<T>

isDone

public boolean isDone()

Specified by:

isDone in interface java.util.concurrent.Future<T>

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

listener

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

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

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

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