Package org.threadly.concurrent.future

Class 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

    • 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