Package com.apple.foundationdb.async

Class AsyncUtil

  • public class AsyncUtil
extends java.lang.Object
    Provided utilities for using and manipulating CompletableFutures.

    • Field Summary

      Fields 
      Modifier and Type Field 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

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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.
      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.
      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