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

java.lang.Object
  extended by com.google.common.util.concurrent.AbstractFuture<V>
All Implemented Interfaces:
ListenableFuture<V>, Future<V>
Direct Known Subclasses:
AbstractListenableFuture, 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
AbstractFuture()
           
 
Method Summary
 void addListener(Runnable listener, Executor exec)
          Registers a listener to be run on the given executor.
protected  boolean cancel()
          Deprecated. Most implementations will be satisfied with the default implementation of cancel(boolean) and not need to call this method at all. Those that are not can delegate to super.cancel(mayInterruptIfRunning) or, to get behavior exactly equivalent to this method, super.cancel(false). This method will be removed from Guava in Guava release 11.0.
 boolean cancel(boolean mayInterruptIfRunning)
           
protected  void done()
          Deprecated. 
 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

public AbstractFuture()
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: First, the thread that the listener runs in depends on whether the Future is done at the time it is added. In particular, if added late, listeners will run in the thread that called addListener. Second, listeners may run in an internal thread of the system responsible for the input Future, such as an RPC network thread. Finally, during the execution of a sameThreadExecutor listener, all other registered but unexecuted listeners are prevented from running, 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

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 call done() 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 call done() 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.

cancel

@Beta
@Deprecated
protected final boolean cancel()
Deprecated. Most implementations will be satisfied with the default implementation of cancel(boolean) and not need to call this method at all. Those that are not can delegate to super.cancel(mayInterruptIfRunning) or, to get behavior exactly equivalent to this method, super.cancel(false). This method will be removed from Guava in Guava release 11.0.

Subclasses can invoke this method to mark the future as cancelled. This will set the state of the future to AbstractFuture.Sync.CANCELLED and call done() if the state was successfully changed.

Returns:
true if the state was successfully changed.

done

@Beta
@Deprecated
protected void done()
Deprecated. 

Deprecated. Add listeners (possible executed in MoreExecutors.sameThreadExecutor()) to perform the work currently performed by your done implementation. This method will be removed from Guava in Guava release 11.0. Called by the success, failed, or cancelled methods to indicate that the value is now available and the latch can be released.



Copyright © 2010-2011. All Rights Reserved.