Skip to content

Latest commit

 

History

History
91 lines (65 loc) · 3.85 KB

CompletableFuture.adoc

File metadata and controls

91 lines (65 loc) · 3.85 KB

CompletableFuture

Table of Contents

What is a CompletableFuture

Introduced in Java 8 (2014).

A java.util.concurrent.CompletableFuture is a complete implementation of both Future and CompletionStage.

CompletableFuture provides static methods as means to execute the tasks.

CompletableFuture allows for chaining and combining outcomes from multiple other CompletableFutures.

Classifications

Table 1. Operations return type
Pattern in method name Description

run/Run

Perform a task without a return value, using a Runnable.

supply/Supply

Perform a task that returns a value, using a Supplier.

Synchronicity

Synchronicity is either Sync or Async

Table 2. Synchronicity
Pattern in method name Description

<nothing>

synchronous, performed by the thread running the CompletableFuture.

Async

asynchronous, performed by default by the ForkJoinPool.commonPool unless an executor is provided.

Results

There are two methods to retrieve the results.

Both wait for the CompletableFuture to complete, then return the result if successful.

Unsuccessful outcomes are due to cancellation, exceptional outcomes and interruptions.

Table 3. Results
Method name Description

get

Return the result. Throws checked exceptions when unsuccessful.

join

Return the result. Throws unchecked runtime exceptions when unsuccessful.

Multiple CompletableFutures

Table 4. Chaining and Combining
Pattern in method name Description

Chaining

thenCompose*

Chain two CompletableFuture, the second executed after the first using the result of the first as a value in a Function, returning a CompletableFuture.

thenCombine*

Chain two CompletableFuture, when both are completed using the result of both as values in a BiFunction, returning a CompletableFuture.

Combining All

thenAcceptBoth*

Chain two CompletableFuture, when both are completed using the result of both as values in a BiConsumer, returning a value.

runAfterBoth*

Chain two CompletableFuture, when both are completed run a Runnable, returning a CompletableFuture<Void>.

allOf

Await the completion of all of a list of CompletableFuture instances, returning a CompletableFuture<Void>.

Combining Either

applyToEither*

Accept the completion of the current or other CompletableFuture using the value in a Function, returning a CompletableFuture.

acceptEither*

Accept the completion of the current or other CompletableFuture using the value in a Consumer, returning a CompletableFuture.

runAfterEither*

Accept the completion of the current or other CompletableFuture, then run a Runnable, returning a CompletableFuture<Void>.

anyOf

Await the completion of any one of a list of CompletableFuture instances, returning a CompletableFuture<Object>.

Understanding Pipelines in CompletableFuture

CompletionFuture has Stages.

Each Stage may produce an output or signal when completed successfully. Any stage can fail, leading to an exception. The exception can be handled. A handling of an exception may cause the pipeline to be repaired or may be fatal enough to fail.

                   /----S--o--S--o--S--------------S--o--S--o----SUCCESS
                  /                 \              /
CompletableFuture                    |            |
                  \                   \          /
                   \-------------------E--h--E--h--E--h----------FAILURE