Class AbstractFuture<V>
- All Implemented Interfaces:
ListenableFuture<V>
,Future<V>
- Direct Known Subclasses:
AbstractFuture.TrustedFuture
,Futures.InCompletionOrderFuture
,GwtFluentFutureCatchingSpecialization
,TestingExecutors.NoOpScheduledExecutorService.NeverScheduledFuture
ListenableFuture
, intended for advanced users only. More
common ways to create a ListenableFuture
include instantiating a SettableFuture
,
submitting a task to a ListeningExecutorService
, and deriving a Future
from an
existing one, typically using methods like Futures.transform
and Futures.catching
.
This class implements all methods in ListenableFuture
. Subclasses should provide a way
to set the result of the computation through the protected methods set(Object)
, setFuture(ListenableFuture)
and setException(Throwable)
. Subclasses may also override
afterDone()
, which will be invoked automatically when the future completes. Subclasses
should rarely override other methods.
- Since:
- 1.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
private static final class
A special value to represent cancellation and the 'wasInterrupted' bit.private static final class
A special value to represent failure, whensetException(java.lang.Throwable)
is called successfully.private static final class
Listeners also form a stack through thelisteners
field.private static final class
private static final class
A special value that encodes the 'setFuture' state.private static final class
AbstractFuture.AtomicHelper
based onsynchronized
and volatile writes.(package private) static interface
Tag interface marking trusted subclasses.(package private) static class
A less abstract subclass of AbstractFuture.private static final class
AbstractFuture.AtomicHelper
based onUnsafe
.private static final class
Waiter links form a Treiber stack, in thewaiters
field.Nested classes/interfaces inherited from interface java.util.concurrent.Future
Future.State
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final AbstractFuture.AtomicHelper
(package private) static final boolean
private AbstractFuture.Listener
All listeners.(package private) static final LazyLogger
private static final Object
A special value to representnull
.private static final long
private Object
This field encodes the current state of the future.private AbstractFuture.Waiter
All waiting threads. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate void
addDoneString
(StringBuilder builder) void
addListener
(Runnable listener, Executor executor) Registers a listener to be run on the given executor.private void
addPendingString
(StringBuilder builder) protected void
Callback method that is called exactly once after the future is completed.private void
appendResultObject
(StringBuilder builder, Object o) Any object can be the result of a Future, and not every object has a reasonable toString() implementation.private void
appendUserObject
(StringBuilder builder, Object o) Helper for printing user supplied objects into our toString method.boolean
cancel
(boolean mayInterruptIfRunning) private static CancellationException
cancellationExceptionWithCause
(String message, Throwable cause) private AbstractFuture.Listener
Clears thelisteners
list and prepends its contents toonto
, least recently added first.private static void
complete
(AbstractFuture<?> param, boolean callInterruptTask) Unblocks all threads and runs all listeners.private static void
executeListener
(Runnable runnable, Executor executor) Submits the given runnable to the givenExecutor
catching and logging all runtime exceptions thrown by the executor.get()
private V
getDoneValue
(Object obj) Unboxesobj
.private static Object
getFutureValue
(ListenableFuture<?> future) Returns a value that satisfies the contract of thevalue
field based on the state of given future.private static <V> V
getUninterruptibly
(Future<V> future) An inlined private copy ofUninterruptibles.getUninterruptibly(java.util.concurrent.Future<V>)
used to break an internal dependency on other /util/concurrent classes.protected void
Subclasses can override this method to implement interruption of the future's computation.boolean
boolean
isDone()
(package private) final void
maybePropagateCancellationTo
(Future<?> related) If this future has been cancelled (and possibly interrupted), cancels (and possibly interrupts) the given future (if available).protected String
Provide a human-readable explanation of why this future has not yet completed.private void
Releases all threads in thewaiters
list, and clears the list.private void
Marks the given node as 'deleted' (null waiter) and then scans the list to unlink all deleted nodes.protected boolean
Sets the result of thisFuture
unless thisFuture
has already been cancelled or set (including set asynchronously).protected boolean
setException
(Throwable throwable) Sets the failed result of thisFuture
unless thisFuture
has already been cancelled or set (including set asynchronously).protected boolean
setFuture
(ListenableFuture<? extends V> future) Sets the result of thisFuture
to match the supplied inputFuture
once the suppliedFuture
is done, unless thisFuture
has already been cancelled or set (including "set asynchronously," defined below).toString()
protected final Throwable
Usually returnsnull
but, if thisFuture
has failed, may optionally return the cause of the failure.protected final boolean
Returns true if this future was cancelled withmayInterruptIfRunning
set totrue
.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.concurrent.Future
exceptionNow, resultNow, state
-
Field Details
-
GENERATE_CANCELLATION_CAUSES
static final boolean GENERATE_CANCELLATION_CAUSES -
log
-
SPIN_THRESHOLD_NANOS
private static final long SPIN_THRESHOLD_NANOS- See Also:
-
ATOMIC_HELPER
-
NULL
A special value to representnull
. -
value
This field encodes the current state of the future.The valid values are:
null
initial state, nothing has happened.AbstractFuture.Cancellation
terminal state,cancel
was called.AbstractFuture.Failure
terminal state,setException
was called.AbstractFuture.SetFuture
intermediate state,setFuture
was called.NULL
terminal state,set(null)
was called.- Any other non-null value, terminal state,
set
was called with a non-null argument.
-
listeners
All listeners. -
waiters
All waiting threads.
-
-
Constructor Details
-
AbstractFuture
protected AbstractFuture()Constructor for use by subclasses.
-
-
Method Details
-
removeWaiter
Marks the given node as 'deleted' (null waiter) and then scans the list to unlink all deleted nodes. This is an O(n) operation in the common case (and O(n^2) in the worst), but we are saved by two things.- This is only called when a waiting thread times out or is interrupted. Both of which should be rare.
- The waiters list should be very short.
-
get
public V get(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException, ExecutionException The default
AbstractFuture
implementation throwsInterruptedException
if the current thread is interrupted during the call, even if the value is already available. -
get
The default
AbstractFuture
implementation throwsInterruptedException
if the current thread is interrupted during the call, even if the value is already available. -
getDoneValue
- Throws:
ExecutionException
-
isDone
public boolean isDone() -
isCancelled
public boolean isCancelled()- Specified by:
isCancelled
in interfaceFuture<V>
-
cancel
public boolean cancel(boolean mayInterruptIfRunning) If a cancellation attempt succeeds on a
Future
that had previously been set asynchronously, then the cancellation will also be propagated to the delegateFuture
that was supplied in thesetFuture
call.Rather than override this method to perform additional cancellation work or cleanup, subclasses should override
afterDone()
, consultingisCancelled()
andwasInterrupted()
as necessary. This ensures that the work is done even if the future is cancelled without a call tocancel
, such as by callingsetFuture(cancelledFuture)
.Beware of completing a future while holding a lock. Its listeners may do slow work or acquire other locks, risking deadlocks.
-
interruptTask
protected void interruptTask()Subclasses can override this method to implement interruption of the future's computation. The method is invoked automatically by a successful call tocancel(true)
.The default implementation does nothing.
This method is likely to be deprecated. Prefer to override
afterDone()
, checkingwasInterrupted()
to decide whether to interrupt your task.- Since:
- 10.0
-
wasInterrupted
protected final boolean wasInterrupted()Returns true if this future was cancelled withmayInterruptIfRunning
set totrue
.- Since:
- 14.0
-
addListener
Registers a listener to be run on the given executor. The listener will run when theFuture
's computation is complete or, if the computation is already complete, immediately.There is no guaranteed ordering of execution of listeners, but any listener added through this method is guaranteed to be called once the computation is complete.
Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown during
Executor.execute
(e.g., aRejectedExecutionException
or an exception thrown by direct execution) will be caught and logged.Note: If your listener is lightweight -- and will not cause stack overflow by completing more futures or adding more
directExecutor()
listeners inline -- considerMoreExecutors.directExecutor()
. Otherwise, avoid it: See the warnings on the docs fordirectExecutor
.This is the most general listener interface. For common operations performed using listeners, see
Futures
. For a simplified but general listener interface, seeaddCallback()
.Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.
Guava implementations of
ListenableFuture
promptly release references to listeners after executing them.- Specified by:
addListener
in interfaceListenableFuture<V>
- Parameters:
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener in- Since:
- 10.0
-
set
Sets the result of thisFuture
unless thisFuture
has already been cancelled or set (including set asynchronously). When a call to this method returns, theFuture
is guaranteed to be done only if the call was accepted (in which case it returnstrue
). If it returnsfalse
, theFuture
may have previously been set asynchronously, in which case its result may not be known yet. That result, though not yet known, cannot be overridden by a call to aset*
method, only by a call tocancel(boolean)
.Beware of completing a future while holding a lock. Its listeners may do slow work or acquire other locks, risking deadlocks.
- Parameters:
value
- the value to be used as the result- Returns:
- true if the attempt was accepted, completing the
Future
-
setException
Sets the failed result of thisFuture
unless thisFuture
has already been cancelled or set (including set asynchronously). When a call to this method returns, theFuture
is guaranteed to be done only if the call was accepted (in which case it returnstrue
). If it returnsfalse
, theFuture
may have previously been set asynchronously, in which case its result may not be known yet. That result, though not yet known, cannot be overridden by a call to aset*
method, only by a call tocancel(boolean)
.Beware of completing a future while holding a lock. Its listeners may do slow work or acquire other locks, risking deadlocks.
- Parameters:
throwable
- the exception to be used as the failed result- Returns:
- true if the attempt was accepted, completing the
Future
-
setFuture
Sets the result of thisFuture
to match the supplied inputFuture
once the suppliedFuture
is done, unless thisFuture
has already been cancelled or set (including "set asynchronously," defined below).If the supplied future is done when this method is called and the call is accepted, then this future is guaranteed to have been completed with the supplied future by the time this method returns. If the supplied future is not done and the call is accepted, then the future will be set asynchronously. Note that such a result, though not yet known, cannot be overridden by a call to a
set*
method, only by a call tocancel(boolean)
.If the call
setFuture(delegate)
is accepted and thisFuture
is later cancelled, cancellation will be propagated todelegate
. Additionally, any call tosetFuture
after any cancellation will propagate cancellation to the suppliedFuture
.Note that, even if the supplied future is cancelled and it causes this future to complete, it will never trigger interruption behavior. In particular, it will not cause this future to invoke the
interruptTask()
method, and thewasInterrupted()
method will not returntrue
.Beware of completing a future while holding a lock. Its listeners may do slow work or acquire other locks, risking deadlocks.
- Parameters:
future
- the future to delegate to- Returns:
- true if the attempt was accepted, indicating that the
Future
was not previously cancelled or set. - Since:
- 19.0
-
getFutureValue
Returns a value that satisfies the contract of thevalue
field based on the state of given future.This is approximately the inverse of
getDoneValue(Object)
-
getUninterruptibly
An inlined private copy ofUninterruptibles.getUninterruptibly(java.util.concurrent.Future<V>)
used to break an internal dependency on other /util/concurrent classes.- Throws:
ExecutionException
-
complete
Unblocks all threads and runs all listeners. -
afterDone
protected void afterDone()Callback method that is called exactly once after the future is completed.If
interruptTask()
is also run during completion,afterDone()
runs after it.The default implementation of this method in
AbstractFuture
does nothing. This is intended for very lightweight cleanup work, for example, timing statistics or clearing fields. If your task does anything heavier consider, just using a listener with an executor.- Since:
- 20.0
-
tryInternalFastPathGetFailure
Usually returnsnull
but, if thisFuture
has failed, may optionally return the cause of the failure. "Failure" means specifically "completed with an exception"; it does not include "was cancelled." To be explicit: If this method returns a non-null value, then:isDone()
must returntrue
isCancelled()
must returnfalse
get()
must not block, and it must throw anExecutionException
with the return value of this method as its cause
This method is
protected
so that classes likecom.google.common.util.concurrent.SettableFuture
do not expose it to their users as an instance method. In the unlikely event that you need to call this method, callInternalFutures.tryInternalFastPathGetFailure(InternalFutureFailureAccess)
.- Specified by:
tryInternalFastPathGetFailure
in classInternalFutureFailureAccess
- Since:
- 27.0
-
maybePropagateCancellationTo
If this future has been cancelled (and possibly interrupted), cancels (and possibly interrupts) the given future (if available). -
releaseWaiters
private void releaseWaiters()Releases all threads in thewaiters
list, and clears the list. -
clearListeners
@CheckForNull private AbstractFuture.Listener clearListeners(@CheckForNull AbstractFuture.Listener onto) Clears thelisteners
list and prepends its contents toonto
, least recently added first. -
toString
-
pendingToString
Provide a human-readable explanation of why this future has not yet completed.- Returns:
- null if an explanation cannot be provided (e.g. because the future is done).
- Since:
- 23.0
-
addPendingString
-
addDoneString
-
appendResultObject
Any object can be the result of a Future, and not every object has a reasonable toString() implementation. Using a reconstruction of the default Object.toString() prevents OOMs and stack overflows, and helps avoid sensitive data inadvertently ending up in exception messages. -
appendUserObject
Helper for printing user supplied objects into our toString method. -
executeListener
Submits the given runnable to the givenExecutor
catching and logging all runtime exceptions thrown by the executor. -
cancellationExceptionWithCause
private static CancellationException cancellationExceptionWithCause(String message, @CheckForNull Throwable cause)
-