SettableFuture
Date: 2016-05-24

com.google.common.util.concurrent

## Class SettableFuture<V>

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

- All Implemented Interfaces:
    ListenableFuture<V>, java.util.concurrent.Future<V>

      @GwtCompatible
      public final class SettableFuture<V>
      extends AbstractFuture<V>

  A `ListenableFuture` whose result may be set by a `set(Object)`, `setException(Throwable)` or `setFuture(ListenableFuture)` call. It may also be cancelled.
  Since:
    9.0 (in 1.0 as `ValueFuture`)

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)` Registers a listener to be run on the given executor.
    `static <V> SettableFuture<V>` | `create()` Creates a new `SettableFuture` in the default state.
    `V` | `get()`
    `V` | `get(long timeout, java.util.concurrent.TimeUnit unit)`
    `boolean` | `isCancelled()`
    `boolean` | `isDone()`
    `boolean` | `set(V value)` Sets the result of this `Future` unless this `Future` has already been cancelled or set (including set asynchronously).
    `boolean` | `setException(java.lang.Throwable throwable)` Sets the failed result of this `Future` unless this `Future` has already been cancelled or set (including set asynchronously).
    `boolean` | `setFuture(ListenableFuture<? extends V> future)` Sets the result of this `Future` to match the supplied input `Future` once the supplied `Future` is done, unless this `Future` has already been cancelled or set (including "set asynchronously," defined below).

    - ### Methods inherited from class com.google.common.util.concurrent.AbstractFuture

      `cancel, interruptTask, wasInterrupted`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### create

          public static <V> SettableFuture<V> create()

      Creates a new `SettableFuture` in the default state.

    - #### set

          public boolean set(@Nullable
                    V value)

      Description copied from class: `AbstractFuture`
      Sets the result of this `Future` unless this `Future` has already been cancelled or set (including set asynchronously). When a call to this method returns, the `Future` is guaranteed to be done only if the call was accepted (in which case it returns `true`). If it returns `false`, the `Future` may have previously been set asynchronously, in which case its result may not be known yet. That result, though not yet known, cannot by overridden by a call to a `set*` method, only by a call to `AbstractFuture.cancel(boolean)`.
      Overrides:
        `set` in class `AbstractFuture<V>`
      Parameters:
        `value` - the value to be used as the result
      Returns:
        true if the attempt was accepted, completing the `Future`

    - #### setException

          public boolean setException(java.lang.Throwable throwable)

      Description copied from class: `AbstractFuture`
      Sets the failed result of this `Future` unless this `Future` has already been cancelled or set (including set asynchronously). When a call to this method returns, the `Future` is guaranteed to be done only if the call was accepted (in which case it returns `true`). If it returns `false`, the `Future` may have previously been set asynchronously, in which case its result may not be known yet. That result, though not yet known, cannot by overridden by a call to a `set*` method, only by a call to `AbstractFuture.cancel(boolean)`.
      Overrides:
        `setException` in class `AbstractFuture<V>`
      Parameters:
        `throwable` - the exception to be used as the failed result
      Returns:
        true if the attempt was accepted, completing the `Future`

    - #### setFuture

          @Beta
          public boolean setFuture(ListenableFuture<? extends V> future)

      Description copied from class: `AbstractFuture`
      Sets the result of this `Future` to match the supplied input `Future` once the supplied `Future` is done, unless this `Future` 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 by overridden by a call to a `set*` method, only by a call to `AbstractFuture.cancel(boolean)`.

      If the call `setFuture(delegate)` is accepted and this `Future` is later cancelled, cancellation will be propagated to `delegate`. Additionally, any call to `setFuture` after any cancellation will propagate cancellation to the supplied `Future`.

      Overrides:
        `setFuture` in class `AbstractFuture<V>`
      Parameters:
        `future` - the future to delegate to
      Returns:
        true if the attempt was accepted, indicating that the `Future` was not previously cancelled or set.

    - #### get

          public final V get()
                      throws java.lang.InterruptedException,
                             java.util.concurrent.ExecutionException

      Description copied from class: `AbstractFuture`

      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 `java.util.concurrent.Future<V>`
      Overrides:
        `get` in class `AbstractFuture<V>`
      Throws:
        `java.lang.InterruptedException` - if the current thread was interrupted before or during the call (optional but recommended).
        `java.util.concurrent.ExecutionException`

    - #### get

          public final V get(long timeout,
              java.util.concurrent.TimeUnit unit)
                      throws java.lang.InterruptedException,
                             java.util.concurrent.ExecutionException,
                             java.util.concurrent.TimeoutException

      Description copied from class: `AbstractFuture`

      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 `java.util.concurrent.Future<V>`
      Overrides:
        `get` in class `AbstractFuture<V>`
      Throws:
        `java.lang.InterruptedException` - if the current thread was interrupted before or during the call (optional but recommended).
        `java.util.concurrent.ExecutionException`
        `java.util.concurrent.TimeoutException`

    - #### isDone

          public final boolean isDone()

      Specified by:
        `isDone` in interface `java.util.concurrent.Future<V>`
      Overrides:
        `isDone` in class `AbstractFuture<V>`

    - #### isCancelled

          public final boolean isCancelled()

      Specified by:
        `isCancelled` in interface `java.util.concurrent.Future<V>`
      Overrides:
        `isCancelled` in class `AbstractFuture<V>`

    - #### addListener

          public final void addListener(java.lang.Runnable listener,
                         java.util.concurrent.Executor executor)

      Description copied from class: `AbstractFuture`
      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 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. Heavyweight `directExecutor` 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, see `addCallback()`.

      Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.

      Specified by:
        `addListener` in interface `ListenableFuture<V>`
      Overrides:
        `addListener` in class `AbstractFuture<V>`
      Parameters:
        `listener` - the listener to run when the computation is complete
        `executor` - the executor to run the listener in