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 `CompletableFuture`s.

### Field Summary

Fields
`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

All Methods Static Methods Concrete Methods Deprecated Methods
`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 `CompletableFuture`s 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 `CompletableFuture`s 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 `CompletableFuture`s 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 `CompletableFuture`s are done