AbstractFuture (Guava: Google Core Libraries for Java 15.0 API)

java.lang.Object
- com.google.common.util.concurrent.AbstractFuture<V>

All Implemented Interfaces:

ListenableFuture<V>, Future<V>

Direct Known Subclasses:

SettableFuture
```
public abstract class AbstractFuture<V>
extends Object
implements ListenableFuture<V>
```
An abstract implementation of the ListenableFuture interface. This class is preferable to FutureTask for two reasons: It implements ListenableFuture, and it does not implement Runnable. (If you want a Runnable implementation of ListenableFuture, create a ListenableFutureTask, or submit your tasks to a ListeningExecutorService.)
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) and setException(Throwable). Subclasses may also override interruptTask(), which will be invoked automatically if a call to cancel(true) succeeds in canceling the future.
AbstractFuture uses an AbstractQueuedSynchronizer to deal with concurrency issues and guarantee thread safety.
The state changing methods all return a boolean indicating success or failure in changing the future's state. Valid states are running, completed, failed, or cancelled.
This class uses an ExecutionList to guarantee that all registered listeners will be executed, either when the future finishes or, for listeners that are added after the future completes, immediately. Runnable-Executor pairs are stored in the execution list but are not necessarily executed in the order in which they were added. (If a listener is added after the Future is complete, it will be executed immediately, even if earlier listeners have not been executed. Additionally, executors need not guarantee FIFO execution, or different listeners may run in different executors.)

Since:

1.0

Author:

Sven Mawson

Constructor Summary

Constructors
Modifier Constructor and Description

protected AbstractFuture()
Constructor for use by subclasses.

Constructors
Modifier	Constructor and Description
`protected`	`AbstractFuture()` Constructor for use by subclasses.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addListener(Runnable listener, Executor exec)` Registers a listener to be run on the given executor.
`boolean`	`cancel(boolean mayInterruptIfRunning)` Attempts to cancel execution of this task.
`V`	`get()` Waits if necessary for the computation to complete, and then retrieves its result.
`V`	`get(long timeout, TimeUnit unit)` Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
`protected void`	`interruptTask()` Subclasses can override this method to implement interruption of the future's computation.
`boolean`	`isCancelled()` Returns `true` if this task was cancelled before it completed normally.
`boolean`	`isDone()` Returns `true` if this task completed.
`protected boolean`	`set(V value)` Subclasses should invoke this method to set the result of the computation to `value`.
`protected boolean`	`setException(Throwable throwable)` Subclasses should invoke this method to set the result of the computation to an error, `throwable`.
`protected boolean`	`wasInterrupted()` Returns true if this future was cancelled with `mayInterruptIfRunning` set to `true`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AbstractFuture
```
protected AbstractFuture()
```
    Constructor for use by subclasses.
- Method Detail
  - get
```
public V get(long timeout,
    TimeUnit unit)
      throws InterruptedException,
             TimeoutException,
             ExecutionException
```
    Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
    The default AbstractFuture implementation throws InterruptedException if the current thread is interrupted before or during the call, even if the value is already available.
    
    Specified by:
    
    get in interface Future<V>
    
    Parameters:
    timeout - the maximum time to wait
    unit - the time unit of the timeout argument
    
    Returns:
    the computed result
    
    Throws:
    
    InterruptedException - if the current thread was interrupted before or during the call (optional but recommended).
    
    CancellationException - if the computation was cancelled
    
    TimeoutException - if the wait timed out
    
    ExecutionException - if the computation threw an exception
  - get
```
public V get()
      throws InterruptedException,
             ExecutionException
```
    Waits if necessary for the computation to complete, and then retrieves its result.
    The default AbstractFuture implementation throws InterruptedException if the current thread is interrupted before or during the call, even if the value is already available.
    
    Specified by:
    
    get in interface Future<V>
    
    Returns:
    the computed result
    
    Throws:
    
    InterruptedException - if the current thread was interrupted before or during the call (optional but recommended).
    
    CancellationException - if the computation was cancelled
    
    ExecutionException - if the computation threw an exception
  - isDone
```
public boolean isDone()
```
    Description copied from interface: java.util.concurrent.Future
    
    Returns true if this task completed. Completion may be due to normal termination, an exception, or cancellation -- in all of these cases, this method will return true.
    
    Specified by:
    
    isDone in interface Future<V>
    
    Returns:
    true if this task completed
  - isCancelled
```
public boolean isCancelled()
```
    Description copied from interface: java.util.concurrent.Future
    
    Returns true if this task was cancelled before it completed normally.
    
    Specified by:
    
    isCancelled in interface Future<V>
    
    Returns:
    true if this task was cancelled before it completed
  - cancel
```
public boolean cancel(boolean mayInterruptIfRunning)
```
    Description copied from interface: java.util.concurrent.Future
    
    Attempts to cancel execution of this task. This attempt will fail if the task has already completed, has already been cancelled, or could not be cancelled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.
    After this method returns, subsequent calls to Future.isDone() will always return true. Subsequent calls to Future.isCancelled() will always return true if this method returned true.
    
    Specified by:
    
    cancel in interface Future<V>
    
    Parameters:
    mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete
    
    Returns:
    false if the task could not be cancelled, typically because it has already completed normally; true otherwise
  - 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 to cancel(true).
    The default implementation does nothing.
    
    Since:
    
    10.0
  - wasInterrupted
```
protected final boolean wasInterrupted()
```
    Returns true if this future was cancelled with mayInterruptIfRunning set to true.
    
    Since:
    
    14.0
  - addListener
```
public void addListener(Runnable listener,
               Executor exec)
```
    Registers a listener to be run on the given executor. The listener will run when the Future'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., a RejectedExecutionException or an exception thrown by inline execution) will be caught and logged.
    Note: For fast, lightweight listeners that would be safe to execute in any thread, consider MoreExecutors.sameThreadExecutor(). For heavier listeners, sameThreadExecutor() carries some caveats. For example, the listener may run on an unpredictable or undesirable thread:
    - If this Future is done at the time addListener is called, addListener will execute the listener inline.
    - If this Future is not yet done, addListener will schedule the listener to be run by the thread that completes this Future, which may be an internal system thread such as an RPC network thread.
    Also note that, regardless of which thread executes the sameThreadExecutor() listener, all other registered but unexecuted listeners are prevented from running during its execution, even if those listeners are to run in other executors.
    This is the most general listener interface. For common operations performed using listeners, see Futures. For a simplified but general listener interface, see addCallback().
    Specified by:
    
    addListener in interface ListenableFuture<V>
    
    Parameters:
    listener - the listener to run when the computation is complete
    exec - the executor to run the listener in
    Since:
    
    10.0
  - set
```
protected boolean set(@Nullable
          V value)
```
    Subclasses should invoke this method to set the result of the computation to value. This will set the state of the future to AbstractFuture.Sync.COMPLETED and invoke the listeners if the state was successfully changed.
    
    Parameters:
    value - the value that was the result of the task.
    
    Returns:
    true if the state was successfully changed.
  - setException
```
protected boolean setException(Throwable throwable)
```
    Subclasses should invoke this method to set the result of the computation to an error, throwable. This will set the state of the future to AbstractFuture.Sync.COMPLETED and invoke the listeners if the state was successfully changed.
    
    Parameters:
    throwable - the exception that the task failed with.
    
    Returns:
    true if the state was successfully changed.

Class AbstractFuture<V>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AbstractFuture

Method Detail

get

get

isDone

isCancelled

cancel

interruptTask

wasInterrupted

addListener

set

setException