Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.util.concurrent
Class AbstractFuture<V>

    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
`protected` | `AbstractFuture()` Constructor for use by subclasses.

Method Summary
`void` | `addListener(Runnable listener, Executor exec)` Registers a listener to be run on the given executor.
`boolean` | `cancel(boolean mayInterruptIfRunning)`
`V` | `get()`
`V` | `get(long timeout, TimeUnit unit)`
`protected void` | `interruptTask()` Subclasses can override this method to implement interruption of the future's computation.
`boolean` | `isCancelled()`
`boolean` | `isDone()`
`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`.

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

  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>`
  Throws:
    `InterruptedException` - if the current thread was interrupted before or during the call (optional but recommended).
    `CancellationException`
    `TimeoutException`
    `ExecutionException`

### get

    public V get()
          throws InterruptedException,
                 ExecutionException

  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>`
  Throws:
    `InterruptedException` - if the current thread was interrupted before or during the call (optional but recommended).
    `CancellationException`
    `ExecutionException`

### isDone

    public boolean isDone()

  Specified by:
    `isDone` in interface `Future<V>`

### isCancelled

    public boolean isCancelled()

  Specified by:
    `isCancelled` in interface `Future<V>`

### cancel

    public boolean cancel(boolean mayInterruptIfRunning)

  Specified by:
    `cancel` in interface `Future<V>`

### 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

### 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 the input `Future` is done at the time `addListener` is called, `addListener` will execute the listener inline.
  - If the input `Future` is not yet done, `addListener` will schedule the listener to be run by the thread that completes the input `Future`, which may be an internal system thread such as an RPC network thread.
  Also note that, regardless of which thread executes the 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.
  Throws:
    `Error` - if the throwable was an `Error`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2012. All Rights Reserved.