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 classprivate static final classA special value to represent cancellation and the 'wasInterrupted' bit.private static final classA special value to represent failure, whensetException(java.lang.Throwable)is called successfully.private static final classListeners also form a stack through thelistenersfield.private static final classprivate static final classA special value that encodes the 'setFuture' state.private static final classAbstractFuture.AtomicHelperbased onsynchronizedand volatile writes.(package private) static interfaceTag interface marking trusted subclasses.(package private) static classA less abstract subclass of AbstractFuture.private static final classAbstractFuture.AtomicHelperbased onUnsafe.private static final classWaiter links form a Treiber stack, in thewaitersfield.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 booleanprivate AbstractFuture.ListenerAll listeners.(package private) static final LazyLoggerprivate static final ObjectA special value to representnull.private static final longprivate ObjectThis field encodes the current state of the future.private AbstractFuture.WaiterAll waiting threads. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate voidaddDoneString(StringBuilder builder) voidaddListener(Runnable listener, Executor executor) Registers a listener to be run on the given executor.private voidaddPendingString(StringBuilder builder) protected voidCallback method that is called exactly once after the future is completed.private voidappendResultObject(StringBuilder builder, Object o) Any object can be the result of a Future, and not every object has a reasonable toString() implementation.private voidappendUserObject(StringBuilder builder, Object o) Helper for printing user supplied objects into our toString method.booleancancel(boolean mayInterruptIfRunning) private static CancellationExceptioncancellationExceptionWithCause(String message, Throwable cause) private AbstractFuture.ListenerClears thelistenerslist and prepends its contents toonto, least recently added first.private static voidcomplete(AbstractFuture<?> param, boolean callInterruptTask) Unblocks all threads and runs all listeners.private static voidexecuteListener(Runnable runnable, Executor executor) Submits the given runnable to the givenExecutorcatching and logging all runtime exceptions thrown by the executor.get()private VgetDoneValue(Object obj) Unboxesobj.private static ObjectgetFutureValue(ListenableFuture<?> future) Returns a value that satisfies the contract of thevaluefield based on the state of given future.private static <V> VgetUninterruptibly(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 voidSubclasses can override this method to implement interruption of the future's computation.booleanbooleanisDone()(package private) final voidmaybePropagateCancellationTo(Future<?> related) If this future has been cancelled (and possibly interrupted), cancels (and possibly interrupts) the given future (if available).protected StringProvide a human-readable explanation of why this future has not yet completed.private voidReleases all threads in thewaiterslist, and clears the list.private voidMarks the given node as 'deleted' (null waiter) and then scans the list to unlink all deleted nodes.protected booleanSets the result of thisFutureunless thisFuturehas already been cancelled or set (including set asynchronously).protected booleansetException(Throwable throwable) Sets the failed result of thisFutureunless thisFuturehas already been cancelled or set (including set asynchronously).protected booleansetFuture(ListenableFuture<? extends V> future) Sets the result of thisFutureto match the supplied inputFutureonce the suppliedFutureis done, unless thisFuturehas already been cancelled or set (including "set asynchronously," defined below).toString()protected final ThrowableUsually returnsnullbut, if thisFuturehas failed, may optionally return the cause of the failure.protected final booleanReturns true if this future was cancelled withmayInterruptIfRunningset totrue.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods 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:
nullinitial state, nothing has happened.AbstractFuture.Cancellationterminal state,cancelwas called.AbstractFuture.Failureterminal state,setExceptionwas called.AbstractFuture.SetFutureintermediate state,setFuturewas called.NULLterminal state,set(null)was called.- Any other non-null value, terminal state,
setwas 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
AbstractFutureimplementation throwsInterruptedExceptionif the current thread is interrupted during the call, even if the value is already available. -
get
The default
AbstractFutureimplementation throwsInterruptedExceptionif 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:
isCancelledin interfaceFuture<V>
-
cancel
public boolean cancel(boolean mayInterruptIfRunning) If a cancellation attempt succeeds on a
Futurethat had previously been set asynchronously, then the cancellation will also be propagated to the delegateFuturethat was supplied in thesetFuturecall.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 withmayInterruptIfRunningset 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., aRejectedExecutionExceptionor 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
ListenableFuturepromptly release references to listeners after executing them.- Specified by:
addListenerin 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 thisFutureunless thisFuturehas already been cancelled or set (including set asynchronously). When a call to this method returns, theFutureis guaranteed to be done only if the call was accepted (in which case it returnstrue). If it returnsfalse, theFuturemay 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 thisFutureunless thisFuturehas already been cancelled or set (including set asynchronously). When a call to this method returns, theFutureis guaranteed to be done only if the call was accepted (in which case it returnstrue). If it returnsfalse, theFuturemay 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 thisFutureto match the supplied inputFutureonce the suppliedFutureis done, unless thisFuturehas 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 thisFutureis later cancelled, cancellation will be propagated todelegate. Additionally, any call tosetFutureafter 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
Futurewas not previously cancelled or set. - Since:
- 19.0
-
getFutureValue
Returns a value that satisfies the contract of thevaluefield 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
AbstractFuturedoes 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 returnsnullbut, if thisFuturehas 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 returntrueisCancelled()must returnfalseget()must not block, and it must throw anExecutionExceptionwith the return value of this method as its cause
This method is
protectedso that classes likecom.google.common.util.concurrent.SettableFuturedo 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:
tryInternalFastPathGetFailurein 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 thewaiterslist, and clears the list. -
clearListeners
@CheckForNull private AbstractFuture.Listener clearListeners(@CheckForNull AbstractFuture.Listener onto) Clears thelistenerslist 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 givenExecutorcatching and logging all runtime exceptions thrown by the executor. -
cancellationExceptionWithCause
private static CancellationException cancellationExceptionWithCause(String message, @CheckForNull Throwable cause)
-