Class AbstractFuture<V>
- java.lang.Object
-
- com.google.common.util.concurrent.GwtFluentFutureCatchingSpecialization<V>
-
- com.google.common.util.concurrent.FluentFuture<V>
-
- com.google.common.util.concurrent.AbstractFuture<V>
-
- All Implemented Interfaces:
ListenableFuture<V>
,java.util.concurrent.Future<V>
- Direct Known Subclasses:
AbstractFuture.TrustedFuture
,Futures.InCompletionOrderFuture
,MoreExecutors.ScheduledListeningDecorator.NeverSuccessfulListenableFutureTask
,TestingExecutors.NoOpScheduledExecutorService.NeverScheduledFuture
@GwtCompatible(emulated=true) public abstract class AbstractFuture<V> extends FluentFuture<V>
An abstract implementation ofListenableFuture
, intended for advanced users only. More common ways to create aListenableFuture
include instantiating aSettableFuture
, submitting a task to aListeningExecutorService
, and deriving aFuture
from an existing one, typically using methods likeFutures.transform
andFutures.catching
.This class implements all methods in
ListenableFuture
. Subclasses should provide a way to set the result of the computation through the protected methodsset(Object)
,setFuture(ListenableFuture)
andsetException(Throwable)
. Subclasses may also overrideafterDone()
, which will be invoked automatically when the future completes. Subclasses should rarely override other methods.- Since:
- 1.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
AbstractFuture.AtomicHelper
private static class
AbstractFuture.Cancellation
A special value to represent cancellation and the 'wasInterrupted' bit.private static class
AbstractFuture.Failure
A special value to represent failure, whensetException(java.lang.Throwable)
is called successfully.private static class
AbstractFuture.Listener
Listeners also form a stack through thelisteners
field.private static class
AbstractFuture.SafeAtomicHelper
AbstractFuture.AtomicHelper
based onAtomicReferenceFieldUpdater
.private static class
AbstractFuture.SetFuture<V>
A special value that encodes the 'setFuture' state.private static class
AbstractFuture.SynchronizedHelper
AbstractFuture.AtomicHelper
based onsynchronized
and volatile writes.(package private) static class
AbstractFuture.TrustedFuture<V>
A less abstract subclass of AbstractFuture.private static class
AbstractFuture.UnsafeAtomicHelper
AbstractFuture.AtomicHelper
based onUnsafe
.private static class
AbstractFuture.Waiter
Waiter links form a Treiber stack, in thewaiters
field.
-
Field Summary
Fields Modifier and Type Field Description private static AbstractFuture.AtomicHelper
ATOMIC_HELPER
private static boolean
GENERATE_CANCELLATION_CAUSES
private AbstractFuture.Listener
listeners
All listeners.private static java.util.logging.Logger
log
private static java.lang.Object
NULL
A special value to representnull
.private static long
SPIN_THRESHOLD_NANOS
private java.lang.Object
value
This field encodes the current state of the future.private AbstractFuture.Waiter
waiters
All waiting threads.
-
Constructor Summary
Constructors Modifier Constructor Description protected
AbstractFuture()
Constructor for use by subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
addDoneString(java.lang.StringBuilder builder)
void
addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
Registers a listener to be run on the given executor.protected void
afterDone()
Callback method that is called exactly once after the future is completed.boolean
cancel(boolean mayInterruptIfRunning)
private static java.util.concurrent.CancellationException
cancellationExceptionWithCause(java.lang.String message, java.lang.Throwable cause)
private AbstractFuture.Listener
clearListeners(AbstractFuture.Listener onto)
Clears thelisteners
list and prepends its contents toonto
, least recently added first.private static void
complete(AbstractFuture<?> future)
Unblocks all threads and runs all listeners.private static void
executeListener(java.lang.Runnable runnable, java.util.concurrent.Executor executor)
Submits the given runnable to the givenExecutor
catching and logging all runtime exceptions thrown by the executor.V
get()
V
get(long timeout, java.util.concurrent.TimeUnit unit)
private V
getDoneValue(java.lang.Object obj)
Unboxesobj
.private static java.lang.Object
getFutureValue(ListenableFuture<?> future)
Returns a value that satisfies the contract of thevalue
field based on the state of given future.protected void
interruptTask()
Subclasses can override this method to implement interruption of the future's computation.boolean
isCancelled()
boolean
isDone()
(package private) void
maybePropagateCancellationTo(java.util.concurrent.Future<?> related)
If this future has been cancelled (and possibly interrupted), cancels (and possibly interrupts) the given future (if available).protected java.lang.String
pendingToString()
Provide a human-readable explanation of why this future has not yet completed.private void
releaseWaiters()
Releases all threads in thewaiters
list, and clears the list.private void
removeWaiter(AbstractFuture.Waiter node)
Marks the given node as 'deleted' (null waiter) and then scans the list to unlink all deleted nodes.protected boolean
set(V value)
Sets the result of thisFuture
unless thisFuture
has already been cancelled or set (including set asynchronously).protected boolean
setException(java.lang.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).java.lang.String
toString()
(package private) java.lang.Throwable
trustedGetException()
Returns the exception that thisFuture
completed with.private java.lang.String
userObjectToString(java.lang.Object o)
Helper for printing user supplied objects into our toString method.protected boolean
wasInterrupted()
Returns true if this future was cancelled withmayInterruptIfRunning
set totrue
.-
Methods inherited from class com.google.common.util.concurrent.FluentFuture
addCallback, catching, catchingAsync, from, transform, transformAsync, withTimeout
-
-
-
-
Field Detail
-
GENERATE_CANCELLATION_CAUSES
private static final boolean GENERATE_CANCELLATION_CAUSES
-
log
private static final java.util.logging.Logger log
-
SPIN_THRESHOLD_NANOS
private static final long SPIN_THRESHOLD_NANOS
- See Also:
- Constant Field Values
-
ATOMIC_HELPER
private static final AbstractFuture.AtomicHelper ATOMIC_HELPER
-
NULL
private static final java.lang.Object NULL
A special value to representnull
.
-
value
private volatile java.lang.Object 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
private volatile AbstractFuture.Listener listeners
All listeners.
-
waiters
private volatile AbstractFuture.Waiter waiters
All waiting threads.
-
-
Method Detail
-
removeWaiter
private void removeWaiter(AbstractFuture.Waiter node)
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, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException, java.util.concurrent.ExecutionException
The default
AbstractFuture
implementation throwsInterruptedException
if the current thread is interrupted during the call, even if the value is already available.- Throws:
java.util.concurrent.CancellationException
java.lang.InterruptedException
java.util.concurrent.TimeoutException
java.util.concurrent.ExecutionException
-
get
public V get() throws java.lang.InterruptedException, java.util.concurrent.ExecutionException
The default
AbstractFuture
implementation throwsInterruptedException
if the current thread is interrupted during the call, even if the value is already available.- Throws:
java.util.concurrent.CancellationException
java.lang.InterruptedException
java.util.concurrent.ExecutionException
-
getDoneValue
private V getDoneValue(java.lang.Object obj) throws java.util.concurrent.ExecutionException
- Throws:
java.util.concurrent.ExecutionException
-
isDone
public boolean isDone()
-
isCancelled
public boolean isCancelled()
-
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)
.
-
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
public void addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)
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: For fast, lightweight listeners that would be safe to execute in any thread, consider
MoreExecutors.directExecutor()
. Otherwise, avoid it. HeavyweightdirectExecutor
listeners can cause problems, and these problems can be difficult to reproduce because they depend on timing. For example:- The listener may be executed by the caller of
addListener
. That caller may be a UI thread or other latency-sensitive thread. This can harm UI responsiveness. - The listener may be executed by the thread that completes this
Future
. That thread may be an internal system thread such as an RPC network thread. Blocking that thread may stall progress of the whole system. It may even cause a deadlock. - The listener may delay other listeners, even listeners that are not themselves
directExecutor
listeners.
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.
- Parameters:
listener
- the listener to run when the computation is completeexecutor
- the executor to run the listener in- Since:
- 10.0
- The listener may be executed by the caller of
-
set
protected boolean set(V value)
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)
.- Parameters:
value
- the value to be used as the result- Returns:
- true if the attempt was accepted, completing the
Future
-
setException
protected boolean setException(java.lang.Throwable throwable)
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)
.- Parameters:
throwable
- the exception to be used as the failed result- Returns:
- true if the attempt was accepted, completing the
Future
-
setFuture
@Beta 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).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
.- 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
private static java.lang.Object getFutureValue(ListenableFuture<?> future)
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)
-
complete
private static void complete(AbstractFuture<?> future)
Unblocks all threads and runs all listeners.
-
afterDone
@Beta 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
-
trustedGetException
final java.lang.Throwable trustedGetException()
Returns the exception that thisFuture
completed with. This includes completion through a call tosetException(java.lang.Throwable)
orsetFuture
(failedFuture)
but not cancellation.- Throws:
java.lang.RuntimeException
- if theFuture
has not failed
-
maybePropagateCancellationTo
final void maybePropagateCancellationTo(java.util.concurrent.Future<?> related)
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
private AbstractFuture.Listener clearListeners(AbstractFuture.Listener onto)
Clears thelisteners
list and prepends its contents toonto
, least recently added first.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
pendingToString
protected java.lang.String pendingToString()
Provide a human-readable explanation of why this future has not yet completed.- Returns:
- null if an explanation cannot be provided because the future is done.
- Since:
- 23.0
-
addDoneString
private void addDoneString(java.lang.StringBuilder builder)
-
userObjectToString
private java.lang.String userObjectToString(java.lang.Object o)
Helper for printing user supplied objects into our toString method.
-
executeListener
private static void executeListener(java.lang.Runnable runnable, java.util.concurrent.Executor executor)
Submits the given runnable to the givenExecutor
catching and logging all runtime exceptions thrown by the executor.
-
cancellationExceptionWithCause
private static java.util.concurrent.CancellationException cancellationExceptionWithCause(java.lang.String message, java.lang.Throwable cause)
-
-