org.apache.flink.runtime.concurrent

Class FutureUtils

java.lang.Object

org.apache.flink.runtime.concurrent.FutureUtils

public class FutureUtils
extends Object

A collection of utilities that expand the usage of CompletableFuture.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FutureUtils.ConjunctFuture<T> A future that is complete once multiple other futures completed.
static class	FutureUtils.RetryException Exception with which the returned future is completed if the retry(Supplier, int, Executor) operation fails.

Constructor Summary

Constructors

Constructor and Description
FutureUtils()

Method Summary

Modifier and Type	Method and Description
static void	assertNoException(CompletableFuture<?> completableFuture) Asserts that the given CompletableFuture is not completed exceptionally.
static <T> FutureUtils.ConjunctFuture<Collection<T>>	combineAll(Collection<? extends CompletableFuture<? extends T>> futures) Creates a future that is complete once multiple other futures completed.
static FutureUtils.ConjunctFuture<Void>	completeAll(Collection<? extends CompletableFuture<?>> futuresToComplete) Creates a FutureUtils.ConjunctFuture which is only completed after all given futures have completed.
static <T> CompletableFuture<T>	completedExceptionally(Throwable cause) Returns an exceptionally completed CompletableFuture.
static CompletableFuture<Void>	completedVoidFuture() Returns a completed future of type Void.
static CompletableFuture<Void>	composeAfterwards(CompletableFuture<?> future, java.util.function.Supplier<CompletableFuture<?>> composedAction) Run the given asynchronous action after the completion of the given future.
static <T> void	forward(CompletableFuture<T> source, CompletableFuture<T> target) Forwards the value from the source future to the target future.
static <IN,OUT> CompletableFuture<OUT>	handleAsyncIfNotDone(CompletableFuture<IN> completableFuture, Executor executor, java.util.function.BiFunction<? super IN,Throwable,? extends OUT> handler) This function takes a CompletableFuture and a handler function for the result of this future.
static void	handleUncaughtException(CompletableFuture<?> completableFuture, Thread.UncaughtExceptionHandler uncaughtExceptionHandler) Checks that the given CompletableFuture is not completed exceptionally.
static <T> CompletableFuture<T>	orTimeout(CompletableFuture<T> future, long timeout, TimeUnit timeUnit) Times the given future out after the timeout.
static <T> CompletableFuture<T>	orTimeout(CompletableFuture<T> future, long timeout, TimeUnit timeUnit, Executor timeoutFailExecutor) Times the given future out after the timeout.
static <T> CompletableFuture<T>	retry(java.util.function.Supplier<CompletableFuture<T>> operation, int retries, Executor executor) Retry the given operation the given number of times in case of a failure.
static <T> CompletableFuture<T>	retrySuccessfulWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation, org.apache.flink.api.common.time.Time retryDelay, org.apache.flink.api.common.time.Deadline deadline, java.util.function.Predicate<T> acceptancePredicate, ScheduledExecutor scheduledExecutor) Retry the given operation with the given delay in between successful completions where the result does not match a given predicate.
static <T> CompletableFuture<T>	retryWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation, int retries, org.apache.flink.api.common.time.Time retryDelay, java.util.function.Predicate<Throwable> retryPredicate, ScheduledExecutor scheduledExecutor) Retry the given operation with the given delay in between failures.
static <T> CompletableFuture<T>	retryWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation, int retries, org.apache.flink.api.common.time.Time retryDelay, ScheduledExecutor scheduledExecutor) Retry the given operation with the given delay in between failures.
static CompletableFuture<Void>	runAfterwards(CompletableFuture<?> future, org.apache.flink.util.function.RunnableWithException runnable) Run the given action after the completion of the given future.
static CompletableFuture<Void>	runAfterwardsAsync(CompletableFuture<?> future, org.apache.flink.util.function.RunnableWithException runnable) Run the given action after the completion of the given future.
static CompletableFuture<Void>	runAfterwardsAsync(CompletableFuture<?> future, org.apache.flink.util.function.RunnableWithException runnable, Executor executor) Run the given action after the completion of the given future.
static <T> T	runIfNotDoneAndGet(RunnableFuture<T> future) Run the given RunnableFuture if it is not done, and then retrieves its result.
static CompletableFuture<Void>	scheduleWithDelay(Runnable operation, org.apache.flink.api.common.time.Time delay, ScheduledExecutor scheduledExecutor) Schedule the operation with the given delay.
static <T> CompletableFuture<T>	scheduleWithDelay(java.util.function.Supplier<T> operation, org.apache.flink.api.common.time.Time delay, ScheduledExecutor scheduledExecutor) Schedule the operation with the given delay.
static <T> CompletableFuture<T>	supplyAsync(org.apache.flink.util.function.SupplierWithException<T,?> supplier, Executor executor) Returns a future which is completed with the result of the SupplierWithException.
static <IN> CompletableFuture<Void>	thenAcceptAsyncIfNotDone(CompletableFuture<IN> completableFuture, Executor executor, java.util.function.Consumer<? super IN> consumer) This function takes a CompletableFuture and a consumer to accept the result of this future.
static <IN,OUT> CompletableFuture<OUT>	thenApplyAsyncIfNotDone(CompletableFuture<IN> completableFuture, Executor executor, java.util.function.Function<? super IN,? extends OUT> applyFun) This function takes a CompletableFuture and a function to apply to this future.
static <IN,OUT> CompletableFuture<OUT>	thenComposeAsyncIfNotDone(CompletableFuture<IN> completableFuture, Executor executor, java.util.function.Function<? super IN,? extends CompletionStage<OUT>> composeFun) This function takes a CompletableFuture and a function to compose with this future.
static java.time.Duration	toDuration(org.apache.flink.api.common.time.Time time) Converts Flink time into a Duration.
static <T,U extends T> CompletableFuture<T>	toJava(scala.concurrent.Future<U> scalaFuture) Converts a Scala Future to a CompletableFuture.
static FutureUtils.ConjunctFuture<Void>	waitForAll(Collection<? extends CompletableFuture<?>> futures) Creates a future that is complete once all of the given futures have completed.
static <IN> CompletableFuture<IN>	whenCompleteAsyncIfNotDone(CompletableFuture<IN> completableFuture, Executor executor, java.util.function.BiConsumer<? super IN,? super Throwable> whenCompleteFun) This function takes a CompletableFuture and a bi-consumer to call on completion of this future.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FutureUtils

public FutureUtils()

Method Detail

completedVoidFuture

public static CompletableFuture<Void> completedVoidFuture()

Returns a completed future of type Void.

Returns:

a completed future of type Void

retry

public static <T> CompletableFuture<T> retry(java.util.function.Supplier<CompletableFuture<T>> operation,
                                             int retries,
                                             Executor executor)

Retry the given operation the given number of times in case of a failure.

Type Parameters:

T - type of the result

Parameters:

operation - to executed

retries - if the operation failed

executor - to use to run the futures

Returns:

Future containing either the result of the operation or a FutureUtils.RetryException

retryWithDelay

public static <T> CompletableFuture<T> retryWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation,
                                                      int retries,
                                                      org.apache.flink.api.common.time.Time retryDelay,
                                                      java.util.function.Predicate<Throwable> retryPredicate,
                                                      ScheduledExecutor scheduledExecutor)

Retry the given operation with the given delay in between failures.

Type Parameters:

T - type of the result

Parameters:

operation - to retry

retries - number of retries

retryDelay - delay between retries

retryPredicate - Predicate to test whether an exception is retryable

scheduledExecutor - executor to be used for the retry operation

Returns:

Future which retries the given operation a given amount of times and delays the retry in case of failures

retryWithDelay

public static <T> CompletableFuture<T> retryWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation,
                                                      int retries,
                                                      org.apache.flink.api.common.time.Time retryDelay,
                                                      ScheduledExecutor scheduledExecutor)

Retry the given operation with the given delay in between failures.

Type Parameters:

T - type of the result

Parameters:

operation - to retry

retries - number of retries

retryDelay - delay between retries

scheduledExecutor - executor to be used for the retry operation

Returns:

Future which retries the given operation a given amount of times and delays the retry in case of failures

scheduleWithDelay

public static CompletableFuture<Void> scheduleWithDelay(Runnable operation,
                                                        org.apache.flink.api.common.time.Time delay,
                                                        ScheduledExecutor scheduledExecutor)

Schedule the operation with the given delay.

Parameters:

operation - to schedule

delay - delay to schedule

scheduledExecutor - executor to be used for the operation

Returns:

Future which schedules the given operation with given delay.

scheduleWithDelay

public static <T> CompletableFuture<T> scheduleWithDelay(java.util.function.Supplier<T> operation,
                                                         org.apache.flink.api.common.time.Time delay,
                                                         ScheduledExecutor scheduledExecutor)

Schedule the operation with the given delay.

Type Parameters:

T - type of the result

Parameters:

operation - to schedule

delay - delay to schedule

scheduledExecutor - executor to be used for the operation

Returns:

Future which schedules the given operation with given delay.

retrySuccessfulWithDelay

public static <T> CompletableFuture<T> retrySuccessfulWithDelay(java.util.function.Supplier<CompletableFuture<T>> operation,
                                                                org.apache.flink.api.common.time.Time retryDelay,
                                                                org.apache.flink.api.common.time.Deadline deadline,
                                                                java.util.function.Predicate<T> acceptancePredicate,
                                                                ScheduledExecutor scheduledExecutor)

Retry the given operation with the given delay in between successful completions where the result does not match a given predicate.

Type Parameters:

T - type of the result

Parameters:

operation - to retry

retryDelay - delay between retries

deadline - A deadline that specifies at what point we should stop retrying

acceptancePredicate - Predicate to test whether the result is acceptable

scheduledExecutor - executor to be used for the retry operation

Returns:

Future which retries the given operation a given amount of times and delays the retry in case the predicate isn't matched

orTimeout

public static <T> CompletableFuture<T> orTimeout(CompletableFuture<T> future,
                                                 long timeout,
                                                 TimeUnit timeUnit)

Times the given future out after the timeout.

Type Parameters:

T - type of the given future

Parameters:

future - to time out

timeout - after which the given future is timed out

timeUnit - time unit of the timeout

Returns:

The timeout enriched future

orTimeout

public static <T> CompletableFuture<T> orTimeout(CompletableFuture<T> future,
                                                 long timeout,
                                                 TimeUnit timeUnit,
                                                 Executor timeoutFailExecutor)

Times the given future out after the timeout.

Type Parameters:

T - type of the given future

Parameters:

future - to time out

timeout - after which the given future is timed out

timeUnit - time unit of the timeout

timeoutFailExecutor - executor that will complete the future exceptionally after the timeout is reached

Returns:

The timeout enriched future

runIfNotDoneAndGet

public static <T> T runIfNotDoneAndGet(RunnableFuture<T> future)
                                throws ExecutionException,
                                       InterruptedException

Run the given RunnableFuture if it is not done, and then retrieves its result.

Type Parameters:

T - type of the result

Parameters:

future - to run if not done and get

Returns:

the result after running the future

Throws:

ExecutionException - if a problem occurred

InterruptedException - if the current thread has been interrupted

runAfterwards

public static CompletableFuture<Void> runAfterwards(CompletableFuture<?> future,
                                                    org.apache.flink.util.function.RunnableWithException runnable)

Run the given action after the completion of the given future. The given future can be completed normally or exceptionally. In case of an exceptional completion the, the action's exception will be added to the initial exception.

Parameters:

future - to wait for its completion

runnable - action which is triggered after the future's completion

Returns:

Future which is completed after the action has completed. This future can contain an exception, if an error occurred in the given future or action.

runAfterwardsAsync

public static CompletableFuture<Void> runAfterwardsAsync(CompletableFuture<?> future,
                                                         org.apache.flink.util.function.RunnableWithException runnable)

Run the given action after the completion of the given future. The given future can be completed normally or exceptionally. In case of an exceptional completion the, the action's exception will be added to the initial exception.

Parameters:

future - to wait for its completion

runnable - action which is triggered after the future's completion

Returns:

Future which is completed after the action has completed. This future can contain an exception, if an error occurred in the given future or action.

runAfterwardsAsync

public static CompletableFuture<Void> runAfterwardsAsync(CompletableFuture<?> future,
                                                         org.apache.flink.util.function.RunnableWithException runnable,
                                                         Executor executor)

Run the given action after the completion of the given future. The given future can be completed normally or exceptionally. In case of an exceptional completion the, the action's exception will be added to the initial exception.

Parameters:

future - to wait for its completion

runnable - action which is triggered after the future's completion

executor - to run the given action

Returns:

Future which is completed after the action has completed. This future can contain an exception, if an error occurred in the given future or action.

composeAfterwards

public static CompletableFuture<Void> composeAfterwards(CompletableFuture<?> future,
                                                        java.util.function.Supplier<CompletableFuture<?>> composedAction)

Run the given asynchronous action after the completion of the given future. The given future can be completed normally or exceptionally. In case of an exceptional completion, the asynchronous action's exception will be added to the initial exception.

Parameters:

future - to wait for its completion

composedAction - asynchronous action which is triggered after the future's completion

Returns:

Future which is completed after the asynchronous action has completed. This future can contain an exception if an error occurred in the given future or asynchronous action.

combineAll

public static <T> FutureUtils.ConjunctFuture<Collection<T>> combineAll(Collection<? extends CompletableFuture<? extends T>> futures)

Creates a future that is complete once multiple other futures completed. The future fails (completes exceptionally) once one of the futures in the conjunction fails. Upon successful completion, the future returns the collection of the futures' results.

The ConjunctFuture gives access to how many Futures in the conjunction have already completed successfully, via FutureUtils.ConjunctFuture.getNumFuturesCompleted().

Parameters:

futures - The futures that make up the conjunction. No null entries are allowed.

Returns:

The ConjunctFuture that completes once all given futures are complete (or one fails).

waitForAll

public static FutureUtils.ConjunctFuture<Void> waitForAll(Collection<? extends CompletableFuture<?>> futures)

Creates a future that is complete once all of the given futures have completed. The future fails (completes exceptionally) once one of the given futures fails.

The ConjunctFuture gives access to how many Futures have already completed successfully, via FutureUtils.ConjunctFuture.getNumFuturesCompleted().

Parameters:

futures - The futures to wait on. No null entries are allowed.

Returns:

The WaitingFuture that completes once all given futures are complete (or one fails).

completeAll

public static FutureUtils.ConjunctFuture<Void> completeAll(Collection<? extends CompletableFuture<?>> futuresToComplete)

Creates a FutureUtils.ConjunctFuture which is only completed after all given futures have completed. Unlike waitForAll(Collection), the resulting future won't be completed directly if one of the given futures is completed exceptionally. Instead, all occurring exception will be collected and combined to a single exception. If at least on exception occurs, then the resulting future will be completed exceptionally.

Parameters:

futuresToComplete - futures to complete

Returns:

Future which is completed after all given futures have been completed.

completedExceptionally

public static <T> CompletableFuture<T> completedExceptionally(Throwable cause)

Returns an exceptionally completed CompletableFuture.

Type Parameters:

T - type of the future

Parameters:

cause - to complete the future with

Returns:

An exceptionally completed CompletableFuture

supplyAsync

public static <T> CompletableFuture<T> supplyAsync(org.apache.flink.util.function.SupplierWithException<T,?> supplier,
                                                   Executor executor)

Returns a future which is completed with the result of the SupplierWithException.

Type Parameters:

T - type of the result

Parameters:

supplier - to provide the future's value

executor - to execute the supplier

Returns:

Future which is completed with the value of the supplier

toDuration

public static java.time.Duration toDuration(org.apache.flink.api.common.time.Time time)

Converts Flink time into a Duration.

Parameters:

time - to convert into a Duration

Returns:

Duration with the length of the given time

toJava

public static <T,U extends T> CompletableFuture<T> toJava(scala.concurrent.Future<U> scalaFuture)

Converts a Scala Future to a CompletableFuture.

Type Parameters:

T - type of the future value

U - type of the original future

Parameters:

scalaFuture - to convert to a Java 8 CompletableFuture

Returns:

Java 8 CompletableFuture

thenApplyAsyncIfNotDone

public static <IN,OUT> CompletableFuture<OUT> thenApplyAsyncIfNotDone(CompletableFuture<IN> completableFuture,
                                                                      Executor executor,
                                                                      java.util.function.Function<? super IN,? extends OUT> applyFun)

This function takes a CompletableFuture and a function to apply to this future. If the input future is already done, this function returns CompletableFuture.thenApply(Function). Otherwise, the return value is CompletableFuture.thenApplyAsync(Function, Executor) with the given executor.

Type Parameters:

IN - type of the input future.

OUT - type of the output future.

Parameters:

completableFuture - the completable future for which we want to apply.

executor - the executor to run the apply function if the future is not yet done.

applyFun - the function to apply.

Returns:

a completable future that is applying the given function to the input future.

thenComposeAsyncIfNotDone

public static <IN,OUT> CompletableFuture<OUT> thenComposeAsyncIfNotDone(CompletableFuture<IN> completableFuture,
                                                                        Executor executor,
                                                                        java.util.function.Function<? super IN,? extends CompletionStage<OUT>> composeFun)

This function takes a CompletableFuture and a function to compose with this future. If the input future is already done, this function returns CompletableFuture.thenCompose(Function). Otherwise, the return value is CompletableFuture.thenComposeAsync(Function, Executor) with the given executor.

Type Parameters:

IN - type of the input future.

OUT - type of the output future.

Parameters:

completableFuture - the completable future for which we want to compose.

executor - the executor to run the compose function if the future is not yet done.

composeFun - the function to compose.

Returns:

a completable future that is a composition of the input future and the function.

whenCompleteAsyncIfNotDone

public static <IN> CompletableFuture<IN> whenCompleteAsyncIfNotDone(CompletableFuture<IN> completableFuture,
                                                                    Executor executor,
                                                                    java.util.function.BiConsumer<? super IN,? super Throwable> whenCompleteFun)

This function takes a CompletableFuture and a bi-consumer to call on completion of this future. If the input future is already done, this function returns CompletableFuture.whenComplete(BiConsumer). Otherwise, the return value is CompletableFuture.whenCompleteAsync(BiConsumer, Executor) with the given executor.

Type Parameters:

IN - type of the input future.

Parameters:

completableFuture - the completable future for which we want to call #whenComplete.

executor - the executor to run the whenComplete function if the future is not yet done.

whenCompleteFun - the bi-consumer function to call when the future is completed.

Returns:

the new completion stage.

thenAcceptAsyncIfNotDone

public static <IN> CompletableFuture<Void> thenAcceptAsyncIfNotDone(CompletableFuture<IN> completableFuture,
                                                                    Executor executor,
                                                                    java.util.function.Consumer<? super IN> consumer)

This function takes a CompletableFuture and a consumer to accept the result of this future. If the input future is already done, this function returns CompletableFuture.thenAccept(Consumer). Otherwise, the return value is CompletableFuture.thenAcceptAsync(Consumer, Executor) with the given executor.

Type Parameters:

IN - type of the input future.

Parameters:

completableFuture - the completable future for which we want to call #thenAccept.

executor - the executor to run the thenAccept function if the future is not yet done.

consumer - the consumer function to call when the future is completed.

Returns:

the new completion stage.

handleAsyncIfNotDone

public static <IN,OUT> CompletableFuture<OUT> handleAsyncIfNotDone(CompletableFuture<IN> completableFuture,
                                                                   Executor executor,
                                                                   java.util.function.BiFunction<? super IN,Throwable,? extends OUT> handler)

This function takes a CompletableFuture and a handler function for the result of this future. If the input future is already done, this function returns CompletableFuture.handle(BiFunction). Otherwise, the return value is CompletableFuture.handleAsync(BiFunction, Executor) with the given executor.

Type Parameters:

IN - type of the handler input argument.

OUT - type of the handler return value.

Parameters:

completableFuture - the completable future for which we want to call #handle.

executor - the executor to run the handle function if the future is not yet done.

handler - the handler function to call when the future is completed.

Returns:

the new completion stage.

assertNoException

public static void assertNoException(CompletableFuture<?> completableFuture)

Asserts that the given CompletableFuture is not completed exceptionally. If the future is completed exceptionally, then it will call the FatalExitExceptionHandler.

Parameters:

completableFuture - to assert for no exceptions

handleUncaughtException

public static void handleUncaughtException(CompletableFuture<?> completableFuture,
                                           Thread.UncaughtExceptionHandler uncaughtExceptionHandler)

Checks that the given CompletableFuture is not completed exceptionally. If the future is completed exceptionally, then it will call the given uncaught exception handler.

Parameters:

completableFuture - to assert for no exceptions

uncaughtExceptionHandler - to call if the future is completed exceptionally

forward

public static <T> void forward(CompletableFuture<T> source,
                               CompletableFuture<T> target)

Forwards the value from the source future to the target future.

Type Parameters:

T - type of the value

Parameters:

source - future to forward the value from

target - future to forward the value to