[concurrency-interest] Candidate jdk9 CompletableFuture additions

Doug Lea dl at cs.oswego.edu
Wed Jan 14 12:09:34 EST 2015


First among planned jdk9 changes are tentative additions to
CompletableFuture aimed to address suggestions and complaints upon
discovering that it is being used a lot more than we anticipated.
Comments on these would be welcome. Three categories:

1. Delays and timeouts. People need these all the time, but they are a
nuisance to do yourself. Method orTimeout(time, unit) covers the most
common timeout idiom. Method delayedExecutor(delay, unit, executor)
provides a one-shot delegated executor that waits out delay before
submitting.

2. During (and after) jdk8 discussions, there was a lot of
disagreement about what methods to expose in class CompletableFuture
and interface CompletionStage. The result was to make
CompletableFuture "maximal" and CompletionStage "minimal".  But we
didn't provide any reasonable way to provide any in-between forms via
subclassing. Added methods (mainly, a "virtual constructor") make this
easy.

3. A few common utilities were missing and either painful or
non-obvious to implement. Including "defensive copy" methods
and a static method to return a failed (exceptionally completed)
future.

See javadoc at 
http://gee.cs.oswego.edu/dl/jsr166/dist/docs/java/util/concurrent/CompletableFuture.html
Including some new guidance in class-level docs. Here's a paste of
added method javadocs:



     public <U> CompletableFuture<U> newIncompleteFuture()
     Creates a new incomplete CompletableFuture of the type to be returned by a 
CompletionStage method. Subclasses should normally override this method to 
return an instance of the same class as this CompletableFuture. The default 
implementation returns an instance of class CompletableFuture.

     public Executor defaultExecutor()
     Returns the default Executor used for async methods that do not specify an 
Executor. This class uses the ForkJoinPool.commonPool(), but may be overridden 
in subclasses with an Executor that provides at least one independent thread.

     public CompletableFuture<T> copy()
     Returns a new CompletableFuture that is completed normally with the same 
value as this Completablefuture when it completes normally. If this 
CompletableFuture completes exceptionally, then the returned CompletableFuture 
completes exceptionally with a CompletionException with this exception as cause. 
The behavior equivalent is to thenApply(x -> x). This method may be useful as a 
form of "defensive copying", to prevent clients from completing, while still 
being able to arrange dependent actions.

     public CompletionStage<T> minimalCompletionStage()
     Returns a new CompletionStage that is completed normally with the same 
value as this Completablefuture when it completes normally, and cannot be 
independently completed or otherwise used in ways not defined by the methods of 
interface CompletionStage. If this CompletableFuture completes exceptionally, 
then the returned CompletionStage completes exceptionally with a 
CompletionException with this exception as cause.

     public CompletableFuture<T> completeAsync(Supplier<T> supplier,
                                               Executor executor)
     Completes this CompletableFuture with the result of the given Supplier 
function invoked from an asynchronous task using the given executor.

     public CompletableFuture<T> completeAsync(Supplier<T> supplier)
     Completes this CompletableFuture with the result of the given Supplier 
function invoked from an asynchronous task using the the default executor.

     public CompletableFuture<T> orTimeout(long timeout,
                                           TimeUnit unit)

     Exceptionally completes this CompletableFuture with a TimeoutException if 
not otherwise completed before the given timeout.
     public static Executor delayedExecutor(long delay,
                                            TimeUnit unit,
                                            Executor executor)

     Returns a new Executor that submits a task to the given base executor after 
the given delay.
     public static Executor delayedExecutor(long delay,
                                            TimeUnit unit)

     Returns a new Executor that submits a task to the default executor after 
the given delay.

     public static <U> CompletionStage<U> completedStage(U value)
     Returns a new CompletionStage that is already completed with the given 
value and supports only those methods in interface CompletionStage.

     public static <U> CompletableFuture<U> failedFuture(Throwable ex)
     Returns a new CompletableFuture that is already completed exceptionally 
with the given exception.


     public static <U> CompletableFuture<U> failedStage(Throwable ex)
     Returns a new CompletionStage that is already completed exceptionally with 
the given exception and supports only those methods in interface CompletionStage.



More information about the Concurrency-interest mailing list