CompletableFuture (original) (raw)

Doug Lea dl at cs.oswego.edu
Tue Nov 27 09:20:23 PST 2012

• Previous message: Request for Review : CR#8004015 : Add interface extends and defaults for basic functional interfaces
• Next message: CompletableFuture
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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 implements Future { // 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 */ CompletableFuture 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 and(CompletableFuture 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 */ CompletableFuture or(CompletableFuture 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 then(Block 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 */ CompletableFuture and(CompletableFuture 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 or(CompletableFuture 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 exceptionally(Block 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?

}

• Previous message: Request for Review : CR#8004015 : Add interface extends and defaults for basic functional interfaces
• Next message: CompletableFuture
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

More information about the lambda-libs-spec-observers mailing list