com.apple.foundationdb.async

Class AsyncUtil

java.lang.Object

com.apple.foundationdb.async.AsyncUtil

public class AsyncUtil
extends java.lang.Object

Provided utilities for using and manipulating CompletableFutures.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.concurrent.CompletableFuture<java.lang.Void>	DONE A completed future of type Void.
static java.util.concurrent.CompletableFuture<java.lang.Boolean>	READY_FALSE A completed future of type Boolean that is set to false.
static java.util.concurrent.CompletableFuture<java.lang.Boolean>	READY_TRUE A completed future of type Boolean that is set to true.

Method Summary

Modifier and Type	Method and Description
static <I,O> java.util.concurrent.CompletableFuture<O>	applySafely(java.util.function.Function<I,? extends java.util.concurrent.CompletableFuture<O>> func, I value) Run Function func, returning all caught exceptions as a CompletableFuture in an error state.
static <V> java.util.concurrent.CompletableFuture<java.util.List<V>>	collect(AsyncIterable<V> iterable) Iterates over a stream of items and returns the result as a list.
static <V> java.util.concurrent.CompletableFuture<java.util.List<V>>	collect(AsyncIterable<V> iterable, java.util.concurrent.Executor executor) Iterates over a set of items and returns the result as a list.
static <V> java.util.concurrent.CompletableFuture<java.util.List<V>>	collectRemaining(AsyncIterator<V> iterator) Iterates over a set of items and returns the remaining results as a list.
static <V> java.util.concurrent.CompletableFuture<java.util.List<V>>	collectRemaining(AsyncIterator<V> iterator, java.util.concurrent.Executor executor) Iterates over a set of items and returns the remaining results as a list.
static <V> java.util.concurrent.CompletableFuture<V>	composeExceptionally(java.util.concurrent.CompletableFuture<V> task, java.util.function.Function<java.lang.Throwable,java.util.concurrent.CompletableFuture<V>> fn) Composes an asynchronous task with an exception-handler that returns a CompletableFuture of the same type.
static <V,T> java.util.concurrent.CompletableFuture<T>	composeHandle(java.util.concurrent.CompletableFuture<V> future, java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler) Compose a handler bi-function to the result of a future.
static <V,T> java.util.concurrent.CompletableFuture<T>	composeHandleAsync(java.util.concurrent.CompletableFuture<V> future, java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler) Compose a handler bi-function to the result of a future.
static <V,T> java.util.concurrent.CompletableFuture<T>	composeHandleAsync(java.util.concurrent.CompletableFuture<V> future, java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler, java.util.concurrent.Executor executor) Compose a handler bi-function to the result of a future.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	forEach(AsyncIterable<V> iterable, java.util.function.Consumer<? super V> consumer) Run the consumer on each element of the iterable in order.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	forEach(AsyncIterable<V> iterable, java.util.function.Consumer<? super V> consumer, java.util.concurrent.Executor executor) Run the consumer on each element of the iterable in order.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	forEachRemaining(AsyncIterator<V> iterator, java.util.function.Consumer<? super V> consumer) Run the consumer on each element remaining in the iterator in order.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	forEachRemaining(AsyncIterator<V> iterator, java.util.function.Consumer<? super V> consumer, java.util.concurrent.Executor executor) Run the consumer on each element remaining if the iterator in order.
static <V> java.util.concurrent.CompletableFuture<java.util.List<V>>	getAll(java.util.Collection<java.util.concurrent.CompletableFuture<V>> tasks) Collects the results of many asynchronous processes into one asynchronous output.
static <V,T> AsyncIterable<T>	mapIterable(AsyncIterable<V> iterable, java.util.function.Function<V,T> func) Map an AsyncIterable into an AsyncIterable of another type or with each element modified in some fashion.
static <V,T> AsyncIterator<T>	mapIterator(AsyncIterator<V> iterator, java.util.function.Function<V,T> func) Map an AsyncIterator into an AsyncIterator of another type or with each element modified in some fashion.
static <V,T> CloseableAsyncIterator<T>	mapIterator(CloseableAsyncIterator<V> iterator, java.util.function.Function<V,T> func) Map a CloseableAsyncIterator into a CloseableAsyncIterator of another type or with each element modified in some fashion.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	success(java.util.concurrent.CompletableFuture<V> task) Maps the outcome of a task into a completion signal.
static <V,T> java.util.concurrent.CompletableFuture<V>	tag(java.util.concurrent.CompletableFuture<T> task, V value) Replaces the output of an asynchronous task with a predetermined value.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	whenAll(java.util.Collection<? extends java.util.concurrent.CompletableFuture<V>> input) Return a CompletableFuture that will be set when all the CompletableFuture inputs are done.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	whenAny(java.util.Collection<? extends java.util.concurrent.CompletableFuture<V>> input) Return a CompletableFuture that will be set when any of the CompletableFuture inputs are done.
static <V> java.util.concurrent.CompletableFuture<java.lang.Void>	whenReady(java.util.concurrent.CompletableFuture<V> task) Maps the readiness of a CompletableFuture into a completion signal.
static java.util.concurrent.CompletableFuture<java.lang.Void>	whileTrue(java.util.function.Function<java.lang.Void,? extends java.util.concurrent.CompletableFuture<java.lang.Boolean>> body) Deprecated. Since version 5.1.0. Use the version of whileTrue that takes a Supplier instead.
static java.util.concurrent.CompletableFuture<java.lang.Void>	whileTrue(java.util.function.Function<java.lang.Void,? extends java.util.concurrent.CompletableFuture<java.lang.Boolean>> body, java.util.concurrent.Executor executor) Deprecated. Since version 5.1.0. Use the version of whileTrue that takes a Supplier instead.
static java.util.concurrent.CompletableFuture<java.lang.Void>	whileTrue(java.util.function.Supplier<java.util.concurrent.CompletableFuture<java.lang.Boolean>> body) Executes an asynchronous operation repeatedly until it returns False.
static java.util.concurrent.CompletableFuture<java.lang.Void>	whileTrue(java.util.function.Supplier<java.util.concurrent.CompletableFuture<java.lang.Boolean>> body, java.util.concurrent.Executor executor) Executes an asynchronous operation repeatedly until it returns False.

Methods inherited from class java.lang.Object

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

Field Detail

DONE

public static final java.util.concurrent.CompletableFuture<java.lang.Void> DONE

A completed future of type Void. In particular, it is completed to null, but that shouldn't really matter for the Void type. This can be used instead of creating a new future if one wants to signal that some asynchronous task has already been completed.

READY_TRUE

public static final java.util.concurrent.CompletableFuture<java.lang.Boolean> READY_TRUE

A completed future of type Boolean that is set to true. This can be used instead of creating a new future if one wants to signal that some task has already been completed with a true result.

READY_FALSE

public static final java.util.concurrent.CompletableFuture<java.lang.Boolean> READY_FALSE

A completed future of type Boolean that is set to false. This can be used instead of creating a new future if one wants to signal that some task has already been completed with a false result.

Method Detail

applySafely

public static <I,O> java.util.concurrent.CompletableFuture<O> applySafely(java.util.function.Function<I,? extends java.util.concurrent.CompletableFuture<O>> func,
                                                                          I value)

Run Function func, returning all caught exceptions as a CompletableFuture in an error state.

Type Parameters:

I - type of input to func

O - type of output of func

Parameters:

func - the Function to run

value - the input to pass to func

Returns:

the output of func, or a CompletableFuture carrying any exception caught in the process.

forEach

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> forEach(AsyncIterable<V> iterable,
                                                                                 java.util.function.Consumer<? super V> consumer)

Run the consumer on each element of the iterable in order. The future will complete with either the first error encountered by either the iterable itself or by the consumer provided or with null if the future completes successfully. Items are processed in order from the iterable, and each item will be processed only after the item before it has finished processing.

Type Parameters:

V - type of the items returned by the iterable

Parameters:

iterable - the source of data over from which to consume

consumer - operation to apply to each item

Returns:

a future that is ready once the asynchronous operation completes

forEach

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> forEach(AsyncIterable<V> iterable,
                                                                                 java.util.function.Consumer<? super V> consumer,
                                                                                 java.util.concurrent.Executor executor)

Run the consumer on each element of the iterable in order. The future will complete with either the first error encountered by either the iterable itself or by the consumer provided or with null if the future completes successfully. Items are processed in order from the iterable, and each item will be processed only after the item before it has finished processing. Asynchronous tasks needed to complete this operation are scheduled on the provided executor.

Type Parameters:

V - type of the items returned by the iterable

Parameters:

iterable - the source of data over from which to consume

consumer - operation to apply to each item

executor - executor on which to schedule asynchronous tasks

Returns:

a future that is ready once the asynchronous operation completes

forEachRemaining

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> forEachRemaining(AsyncIterator<V> iterator,
                                                                                          java.util.function.Consumer<? super V> consumer)

Run the consumer on each element remaining in the iterator in order. The future will complete with either the first error encountered by either the iterator itself or by the consumer provided or with null if the future completes successfully. Items are processed in order from the iterator, and each item will be processed only after the item before it has finished processing.

Type Parameters:

V - type of the items returned by the iterator

Parameters:

iterator - the source of data over from which to consume

consumer - operation to apply to each item

Returns:

a future that is ready once the asynchronous operation completes

forEachRemaining

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> forEachRemaining(AsyncIterator<V> iterator,
                                                                                          java.util.function.Consumer<? super V> consumer,
                                                                                          java.util.concurrent.Executor executor)

Run the consumer on each element remaining if the iterator in order. The future will complete with either the first error encountered by either the iterator itself or by the consumer provided or with null if the future completes successfully. Items are processed in order from the iterator, and each item will be processed only after the item before it has finished processing. Asynchronous tasks needed to complete this operation are scheduled on the provided executor.

Type Parameters:

V - type of the items returned by the iterator

Parameters:

iterator - the source of data over from which to consume

consumer - operation to apply to each item

executor - executor on which to schedule asynchronous tasks

Returns:

a future that is ready once the asynchronous operation completes

collect

public static <V> java.util.concurrent.CompletableFuture<java.util.List<V>> collect(AsyncIterable<V> iterable)

Iterates over a stream of items and returns the result as a list.

Type Parameters:

V - type of the items returned by the iterable

Parameters:

iterable - the source of data over which to iterate

Returns:

a CompletableFuture which will be set to the amalgamation of results from iteration.

collectRemaining

public static <V> java.util.concurrent.CompletableFuture<java.util.List<V>> collectRemaining(AsyncIterator<V> iterator)

Iterates over a set of items and returns the remaining results as a list.

Type Parameters:

V - type of the items returned by the iterator

Parameters:

iterator - the source of data over which to iterate. This function will exhaust the iterator.

Returns:

a CompletableFuture which will be set to the amalgamation of results from iteration.

collect

public static <V> java.util.concurrent.CompletableFuture<java.util.List<V>> collect(AsyncIterable<V> iterable,
                                                                                    java.util.concurrent.Executor executor)

Iterates over a set of items and returns the result as a list.

Type Parameters:

V - type of the items returned by the iterable

Parameters:

iterable - the source of data over which to iterate

executor - the Executor to use for asynchronous operations

Returns:

a CompletableFuture which will be set to the amalgamation of results from iteration.

collectRemaining

public static <V> java.util.concurrent.CompletableFuture<java.util.List<V>> collectRemaining(AsyncIterator<V> iterator,
                                                                                             java.util.concurrent.Executor executor)

Iterates over a set of items and returns the remaining results as a list.

Type Parameters:

V - type of the items returned by the iterator

Parameters:

iterator - the source of data over which to iterate. This function will exhaust the iterator.

executor - the Executor to use for asynchronous operations

Returns:

a CompletableFuture which will be set to the amalgamation of results from iteration.

mapIterable

public static <V,T> AsyncIterable<T> mapIterable(AsyncIterable<V> iterable,
                                                 java.util.function.Function<V,T> func)

Map an AsyncIterable into an AsyncIterable of another type or with each element modified in some fashion.

Type Parameters:

V - type of the items returned by the original iterable

T - type of the items returned by the final iterable

Parameters:

iterable - input

func - mapping function applied to each element

Returns:

a new iterable with each element mapped to a different value

mapIterator

public static <V,T> AsyncIterator<T> mapIterator(AsyncIterator<V> iterator,
                                                 java.util.function.Function<V,T> func)

Map an AsyncIterator into an AsyncIterator of another type or with each element modified in some fashion.

Type Parameters:

V - type of the items returned by the original iterator

T - type of the items returned by the final iterator

Parameters:

iterator - input

func - mapping function applied to each element

Returns:

a new iterator with each element mapped to a different value

mapIterator

public static <V,T> CloseableAsyncIterator<T> mapIterator(CloseableAsyncIterator<V> iterator,
                                                          java.util.function.Function<V,T> func)

Map a CloseableAsyncIterator into a CloseableAsyncIterator of another type or with each element modified in some fashion.

Type Parameters:

V - type of the items returned by the original iterator

T - type of the items returned by the final iterator

Parameters:

iterator - input

func - mapping function applied to each element

Returns:

a new iterator with each element mapped to a different value

whileTrue

@Deprecated
public static java.util.concurrent.CompletableFuture<java.lang.Void> whileTrue(java.util.function.Function<java.lang.Void,? extends java.util.concurrent.CompletableFuture<java.lang.Boolean>> body)

Deprecated. Since version 5.1.0. Use the version of whileTrue that takes a Supplier instead.

Executes an asynchronous operation repeatedly until it returns False.

Parameters:

body - the asynchronous operation over which to loop

Returns:

a CompletableFuture which will be set at completion of the loop.

whileTrue

@Deprecated
public static java.util.concurrent.CompletableFuture<java.lang.Void> whileTrue(java.util.function.Function<java.lang.Void,? extends java.util.concurrent.CompletableFuture<java.lang.Boolean>> body,
                                                                                           java.util.concurrent.Executor executor)

Deprecated. Since version 5.1.0. Use the version of whileTrue that takes a Supplier instead.

Executes an asynchronous operation repeatedly until it returns False.

Parameters:

body - the asynchronous operation over which to loop

executor - the Executor to use for asynchronous operations

Returns:

a CompletableFuture which will be set at completion of the loop.

whileTrue

public static java.util.concurrent.CompletableFuture<java.lang.Void> whileTrue(java.util.function.Supplier<java.util.concurrent.CompletableFuture<java.lang.Boolean>> body)

Executes an asynchronous operation repeatedly until it returns False.

Parameters:

body - the asynchronous operation over which to loop

Returns:

a CompletableFuture which will be set at completion of the loop.

whileTrue

public static java.util.concurrent.CompletableFuture<java.lang.Void> whileTrue(java.util.function.Supplier<java.util.concurrent.CompletableFuture<java.lang.Boolean>> body,
                                                                               java.util.concurrent.Executor executor)

Executes an asynchronous operation repeatedly until it returns False.

Parameters:

body - the asynchronous operation over which to loop

executor - the Executor to use for asynchronous operations

Returns:

a CompletableFuture which will be set at completion of the loop.

success

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> success(java.util.concurrent.CompletableFuture<V> task)

Maps the outcome of a task into a completion signal. Can be useful if task has side-effects for which all is needed is a signal of completion. All errors from task will be passed to the resulting CompletableFuture.

Type Parameters:

V - type of element returned by task

Parameters:

task - the asynchronous process for which to signal completion

Returns:

a newly created CompletableFuture that is set when task completes

whenReady

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> whenReady(java.util.concurrent.CompletableFuture<V> task)

Maps the readiness of a CompletableFuture into a completion signal. When the given CompletableFuture is set to a value or an error, the returned CompletableFuture will be set to null. The returned CompletableFuture will never be set to an error unless it is explicitly cancelled.

Type Parameters:

V - return type of the asynchronous task

Parameters:

task - the asynchronous process to monitor the readiness of

Returns:

a new CompletableFuture that is set when task is ready.

composeExceptionally

public static <V> java.util.concurrent.CompletableFuture<V> composeExceptionally(java.util.concurrent.CompletableFuture<V> task,
                                                                                 java.util.function.Function<java.lang.Throwable,java.util.concurrent.CompletableFuture<V>> fn)

Composes an asynchronous task with an exception-handler that returns a CompletableFuture of the same type. If task completes normally, this will return a CompletableFuture with the same value as task. If task completes exceptionally, this will call fn with the exception returned by task and return the result of the CompletableFuture returned by that function.

Type Parameters:

V - return type of the asynchronous task

Parameters:

task - the asynchronous process to handle exceptions from

fn - a function mapping exceptions from task to a CompletableFuture of the same type as task

Returns:

a CompletableFuture that contains the value returned by task if task completes normally and the result of fn if task completes exceptionally

composeHandle

public static <V,T> java.util.concurrent.CompletableFuture<T> composeHandle(java.util.concurrent.CompletableFuture<V> future,
                                                                            java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler)

Compose a handler bi-function to the result of a future. Unlike the CompletableFuture.handle() function, which requires that the handler return a regular value, this method requires that the handler return a CompletableFuture. The returned future will then be ready with the result of the handler's future (or an error if that future completes exceptionally).

Type Parameters:

V - return type of original future

T - return type of final future

Parameters:

future - future to compose the handler onto

handler - handler bi-function to compose onto the passed future

Returns:

future with same completion properties as the future returned by the handler

composeHandleAsync

public static <V,T> java.util.concurrent.CompletableFuture<T> composeHandleAsync(java.util.concurrent.CompletableFuture<V> future,
                                                                                 java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler)

Compose a handler bi-function to the result of a future. Unlike the CompletableFuture.handle() function, which requires that the handler return a regular value, this method requires that the handler return a CompletableFuture. The returned future will then be ready with the result of the handler's future (or an error if that future completes exceptionally). The handler will execute on the default executor used for asychronous tasks.

Type Parameters:

V - return type of original future

T - return type of final future

Parameters:

future - future to compose the handler onto

handler - handler bi-function to compose onto the passed future

Returns:

future with same completion properties as the future returned by the handler

composeHandleAsync

public static <V,T> java.util.concurrent.CompletableFuture<T> composeHandleAsync(java.util.concurrent.CompletableFuture<V> future,
                                                                                 java.util.function.BiFunction<V,java.lang.Throwable,? extends java.util.concurrent.CompletableFuture<T>> handler,
                                                                                 java.util.concurrent.Executor executor)

Compose a handler bi-function to the result of a future. Unlike the CompletableFuture.handle() function, which requires that the handler return a regular value, this method requires that the handler return a CompletableFuture. The returned future will then be ready with the result of the handler's future (or an error if that future completes excpetionally). The handler will execute on the passed Executor.

Type Parameters:

V - return type of original future

T - return type of final future

Parameters:

future - future to compose the handler onto

handler - handler bi-function to compose onto the passed future

executor - executor on which to execute the handler function

Returns:

future with same completion properties as the future returned by the handler

getAll

public static <V> java.util.concurrent.CompletableFuture<java.util.List<V>> getAll(java.util.Collection<java.util.concurrent.CompletableFuture<V>> tasks)

Collects the results of many asynchronous processes into one asynchronous output. If any of the tasks returns an error, the output is set to that error.

Type Parameters:

V - return type of the asynchronous tasks

Parameters:

tasks - the tasks whose output is to be added to the output

Returns:

a CompletableFuture that will be set to the collective result of the tasks

tag

public static <V,T> java.util.concurrent.CompletableFuture<V> tag(java.util.concurrent.CompletableFuture<T> task,
                                                                  V value)

Replaces the output of an asynchronous task with a predetermined value.

Type Parameters:

V - return type of original future

T - return type of final future

Parameters:

task - the asynchronous process whose output is to be replaced

value - the predetermined value to be returned on success of task

Returns:

a CompletableFuture that will be set to value on completion of task

whenAny

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> whenAny(java.util.Collection<? extends java.util.concurrent.CompletableFuture<V>> input)

Return a CompletableFuture that will be set when any of the CompletableFuture inputs are done. A CompletableFuture is done both on success and failure.

Type Parameters:

V - return type of the asynchronous tasks

Parameters:

input - the list of CompletableFutures to monitor. This list must not be modified during the execution of this call.

Returns:

a signal that will be set when any of the CompletableFutures are done

whenAll

public static <V> java.util.concurrent.CompletableFuture<java.lang.Void> whenAll(java.util.Collection<? extends java.util.concurrent.CompletableFuture<V>> input)

Return a CompletableFuture that will be set when all the CompletableFuture inputs are done. A CompletableFuture is done both on success and failure.

Type Parameters:

V - return type of the asynchronous tasks

Parameters:

input - the list of CompletableFutures to monitor. This list must not be modified during the execution of this call.

Returns:

a signal that will be set when all of the CompletableFutures are done