CompletableFuture

[Doug Lea]

On 11/28/12 15:34, Doug Lea wrote:

> Here's how to make trees/dags:
>
>    t1 = new CompletableFuture();
>    t2 = t1.then(fun1);
>    t3 = t1.then(fun2);
>    t4 = t2.then(fun3);
>    t5 = new CompletableFuture();
>    t6 = t1.and(t3, fun4);

(typo; should be t6 = t5.and(t3, fun4);
>
> This gives you (hoping the ascii-arg makes it through):
>
>
>     / -> t2 -> t4
> t1
>     \ -> t3
>           \
> t5 -----> & t6
>
> Does that help?
>

Also, here's an update that contains a start on fleshing out some
of the mechanics and intent, and adds a few things based on
my own mangling of some suggestions by Chris Poviik (Google).


/*
  * Written by Doug Lea with assistance from members of JCP JSR-166
  * Expert Group and released to the public domain, as explained at
  * http://creativecommons.org/publicdomain/zero/1.0/
  */

import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

/**
  * A {@link Future} that may be explicitly completed (thus setting its
  * value and status), and may support dependent CompletableFutures
  * that trigger upon its completion.
  *
  * <p>Functions and actions supplied for dependent completions using
  * {@code then}, {@code and}, {@code or}, and {@code exceptionally}
  * are performed by the thread that completes the current
  * CompletableFuture, or by the caller of the method, if already
  * complete.
  *
  * <p> When two or more threads attempt to {@link #complete} or {@link
  * #completeExceptionally} a CompletableFuture, only one of them will
  * succeed. When completion entails computation of a function (or void
  * action), the function is executed <em>after</em> establishing
  * precedence. If this function terminates abruptly with an exception,
  * then method {@code complete} acts as {@code completeExceptionally}
  * with that exception. Method {@link #isCompleting} can be used to
  * determine if a completion function gets "stuck", and method {@link
  * #force} can be used in attempts to recover.
  *
  * <p>This class itself does not provide explicit support for
  * asynchronous execution, but can be used in conjunction with several
  * forms of concurrency. For examples, a new CompletableFuture may be
  * constructed with (a function of) the results of an asynchronous
  * task. Also, a supplied dependent action may itself fork a new task.
  *
  */
public class CompletableFuture<T> implements Future<T> {

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

     /**
      * Creates a new CompletableFuture that is completed with the
      * result of the given Future, if/when it completes.
      */
     public CompletableFuture(Future<T> f);

     /**
      * Creates a new CompletableFuture that is completed with the
      * result of applying the given function to the result of the
      * given Future, if/when it completes.
      */
     public <U> CompletableFuture(Future<U> f, Function<? super U, T> fn);

     /**
      * If not already completed, sets the value returned by get() and
      * related methods to the given value.
      *
      * @return true if this invocation of {@code complete} caused
      * this CompletableFuture to transition to a completed state,
      * else false.
      */
     public boolean complete(T value);

     /**
      * If not already completed, causes invocations of get() to
      * throw the given exception.
      *
      * @return true if this invocation of {@code
      * completeExceptionally} caused this CompletableFuture to
      * transition to a completed state, else false.
      */
     public boolean completeExceptionally(Throwable ex);

     // Cascading functional 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
      */
     public <U> CompletableFuture<U> then(Function<? super T,? extends 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
      */
     public <U,V> CompletableFuture<V> and(CompletableFuture<? extends U> x,
                                           BiFunction<? super T,? super U,? 
extends 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
      */
     public <U> CompletableFuture<U> or(CompletableFuture<? extends T> x,
                                        BiFunction<? super T,? super T, ? 
extends U> fn);

     // Action (vs function) forms

     /**
      * Creates and returns a CompletableFuture that is completed
      * after performing the given action with the result of this
      * CompletableFuture if/when it completes normally.
      *
      * @return the new CompletableFuture
      */
     public CompletableFuture<Void> then(Block<? super T> action);

     /**
      * Creates and returns a CompletableFuture that is completed
      * after performing 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 the new CompletableFuture
      */
     public <U> CompletableFuture<Void> and(CompletableFuture<? extends U> x,
                                            BiBlock<? super T, ? super U> action);
     /**
      * Creates and returns a CompletableFuture that is completed
      * after performing the given action with the result of either
      * this or the other given CompletableFuture's results if/when
      * either complete normally.
      *
      * @return the new CompletableFuture
      */
     public CompletableFuture<Void> or(CompletableFuture<? extends T> x,
                                       BiBlock<? super T, ? super T> action);

     /**
      * Creates and returns a CompletableFuture that is completed after
      * performing the given action with the exception triggering this
      * CompletableFuture's completion if/when it completes
      * exceptionally.
      *
      * @return the new CompletableFuture
      */
     public CompletableFuture<Void> 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.)
      */
     public T get();

     /**
      * Returns the value if completed, else the given valueIfAbsent.
      */
     public T getNow(T valueIfAbsent);

     /**
      * Waits if necessary for at most the given time for the computation
      * to complete, and then retrieves its result, if available.
      *
      * @param timeout the maximum time to wait
      * @param unit the time unit of the timeout argument
      * @return the computed result
      * @throws CancellationException if the computation was cancelled
      * @throws ExecutionException if the computation threw an
      * exception
      * @throws InterruptedException if the current thread was interrupted
      * while waiting
      * @throws TimeoutException if the wait timed out
      */
     T get(long timeout, TimeUnit unit)
         throws InterruptedException, ExecutionException, TimeoutException;

     // misc

     /**
      * Whether or not already completed, sets the value subsequently
      * returned by method get() and related methods to the given
      * value. This method is designed primarily for use in recovery
      * actions.
      *
      * @param value the completion value
      */
     public void force(T value);

     /**
      * Returns true if this CompletableFuture is in the process of
      * completing but has not yet completed. This method is designed
      * to help diagnose cases in which supplied completion functions
      * become "stuck" in the process of completion.
      */
     public boolean isCompleting();

     /**
      * Attempts to cancel further processing of this task. This
      * attempt will fail if already completed. If successful,
      * subsequent calls to {@link #isCancelled}, {@link #isDone}, and
      * {@code cancel} will return {@code true} and calls to {@link
      * #get} and related methods will result in {@code
      * CancellationException}.
      *
      * @param mayInterruptIfRunning this value has no effect in the
      * default implementation because interrupts are not used to
      * control processing.
      *
      * @return {@code true} if this task is now cancelled
      */
     public boolean cancel(boolean mayInterruptIfRunning);

     /**
      * Returns {@code true} if this CompletableFuture was cancelled
      * before it completed normally.
      *
      * @return {@code true} if this CompletableFuture was cancelled
      * before it completed normally
      */
     public boolean isCancelled();

     /**
      * Returns {@code true} if completed in any fashion: normally,
      * exceptionally, or cancellation.
      *
      * @return {@code true} if completed
      */
     public boolean isDone();
}