Package com.apple.foundationdb.async

Class AsyncUtil

java.lang.Object
com.apple.foundationdb.async.AsyncUtil
public class AsyncUtil extends Object
Provided utilities for using and manipulating CompletableFutures.

  • Field Details

    • DONE

      public static final CompletableFuture<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 CompletableFuture<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 CompletableFuture<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 Details

    • applySafely

      public static <I, O> CompletableFuture<O> applySafely(Function<I,? extends 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> CompletableFuture<Void> forEach(AsyncIterable<V> iterable, 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> CompletableFuture<Void> forEach(AsyncIterable<V> iterable, Consumer<? super V> consumer, 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> CompletableFuture<Void> forEachRemaining(AsyncIterator<V> iterator, 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> CompletableFuture<Void> forEachRemaining(AsyncIterator<V> iterator, Consumer<? super V> consumer, 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> CompletableFuture<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> CompletableFuture<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> CompletableFuture<List<V>> collect(AsyncIterable<V> iterable, 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> CompletableFuture<List<V>> collectRemaining(AsyncIterator<V> iterator, 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, 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, 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, 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 CompletableFuture<Void> whileTrue(Function<Void,? extends CompletableFuture<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 CompletableFuture<Void> whileTrue(Function<Void,? extends CompletableFuture<Boolean>> body, 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 CompletableFuture<Void> whileTrue(Supplier<CompletableFuture<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 CompletableFuture<Void> whileTrue(Supplier<CompletableFuture<Boolean>> body, 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> CompletableFuture<Void> success(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> CompletableFuture<Void> whenReady(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> CompletableFuture<V> composeExceptionally(CompletableFuture<V> task, Function<Throwable,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> CompletableFuture<T> composeHandle(CompletableFuture<V> future, BiFunction<V,Throwable,? extends 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> CompletableFuture<T> composeHandleAsync(CompletableFuture<V> future, BiFunction<V,Throwable,? extends 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 asynchronous 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> CompletableFuture<T> composeHandleAsync(CompletableFuture<V> future, BiFunction<V,Throwable,? extends CompletableFuture<T>> handler, 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> CompletableFuture<List<V>> getAll(Collection<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> CompletableFuture<V> tag(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> CompletableFuture<Void> whenAny(Collection<? extends 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> CompletableFuture<Void> whenAll(Collection<? extends 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