CompletableFuture

[Doug Lea]

This is not part of lambda-libs proper, but is a lambda-dependent
j.u.c class -- the last item of our jsr166 JDK8 todo list (see JEP155
http://openjdk.java.net/jeps/155), so it would be great to get
some preliminary feedback on this here.

Thanks especially to Sam for bugging me to get this going.

This is the class that has variously been called FutureValue,
SettableFuture, Promise, and other names. Since the focus is
on possibly-async completions/callbacks, unifying the
terminology around "complete" gives a big hint about usage.
In some senses it is the less geeky, more limited, non-FJ variant
of CountedCompleter (that I confess to loving much more
but is vastly less obvious to use effectively.)



/**
  * A {@link Future} that may be explicitly completed (thus setting its
  * value and status), and may support dependent CompletableFutures
  * that trigger upon its completion.
  */
public class CompletableFuture<T> implements Future<T> {
     // yes, a single, concrete class.
     // todo: wildcards

     /**
      * Creates a new incomplete CompletableFuture.
      */
     CompletableFuture();

     /**
      * If not already completed, sets the value returned by get() and
      * related methods to the given value.
      *
      * @return false if already done.
      */
     boolean complete(T value);

     /**
      * If not already completed, causes invocations of get() to
      * throw the given exception.
      *
      * @return false if already done.
      */
     boolean completeExceptionally(Throwable ex);

     // cascading completions

     /**
      * Creates and returns a CompletableFuture that is completed with
      * the result of the given function of this CompletableFuture's
      * result if/when this completes normally.
      *
      * @return the new CompletableFuture
      */
     <U> CompletableFuture<U> then(Function<T,U> fn);

     /**
      * Creates and Returns a CompletableFuture that is completed with
      * the result of the given function of this and the other given
      * CompletableFuture's results if/when both complete normally.
      *
      * @return the new CompletableFuture
      */
     <U,V> CompletableFuture<V> and(CompletableFuture<U> x, BiFunction<T,U,V> fn);

     /**
      * Creates and returns a CompletableFuture that is completed with
      * the result of the given function of either this or the other
      * given CompletableFuture's results if/when either complete
      * normally.
      *
      * @return the new CompletableFuture
      */
     <U> CompletableFuture<U> or(CompletableFuture<T> x, BiFunction<T,T,U> fn);

     // terminal completions

     /**
      * Performs the given action with the result of this
      * CompletableFuture if/when it completes normally.
      *
      * @return this CompletableFuture, for convenience
      */
     CompletableFuture<T> then(Block<T> action);

     /**
      * Performs the given action with the result of the given function
      * of this and the other given CompletableFuture's results if/when
      * both complete normally.
      *
      * @return this CompletableFuture, for convenience
      */
     <U> CompletableFuture<T> and(CompletableFuture<U> x, BiBlock<T,U> action);

     /**
      * Performs the given action with the result of the given function
      * of either this or the other given CompletableFuture's results
      * if/when either complete normally.
      *
      * @return this CompletableFuture, for convenience
      */
     CompletableFuture<T> or(CompletableFuture<T> x, BiBlock<T,T> action);

     /**
      * Performs the given action with the exception triggering this
      * CompletableFuture's completion if/when it completes exceptionally.
      *
      * @return this CompletableFuture, for convenience
      */
     CompletableFuture<T> exceptionally(Block<Throwable> action);

     // extracting results

     /**
      * Returns the value when complete, or throws an (unchecked)
      * exception if completed exceptionally. (The checked exception
      * variant is available using the timed form of get.)
      */
     T get(); // overrides Future.get to tunnel exceptions

     /**
      * Returns the value if it is ready, else the given valueIfAbsent.
      */
     T getNow(T valueIfAbsent);

     // from Future
     T get(long timeout, TimeUnit unit)
         throws InterruptedException, ExecutionException, TimeoutException;

     // misc

     /**
      * Whether or not already completed, sets the value returned by
      * subsequent invocations of get() and related methods to the
      * given value.
      */
     void force(T value);

     boolean cancel(boolean mayInterruptIfRunning);

     boolean isCancelled();

     boolean isDone(); // also alias isComplete?
}