Package com.apple.foundationdb.async

Class MoreAsyncUtil

java.lang.Object
com.apple.foundationdb.async.MoreAsyncUtil
@API(UNSTABLE) public class MoreAsyncUtil extends Object
More helpers in the spirit of AsyncUtil.

  • Method Details

    • alreadyCancelled

      public static <T> CompletableFuture<T> alreadyCancelled()

    • limitIterable

      @Nonnull public static <T> AsyncIterable<T> limitIterable(@Nonnull AsyncIterable<T> iterable, int limit)

    • filterIterable

      @Nonnull public static <T> AsyncIterable<T> filterIterable(@Nonnull AsyncIterable<T> iterable, @Nonnull Function<T,Boolean> filter)
      Filter items from an async iterable.
      Type Parameters:
      T - the source type
      Parameters:
      iterable - the source
      filter - only items in iterable for which this function returns true will appear in the return value
      Returns:
      a new AsyncIterable that only contains those items in iterable for which filter returns true

    • filterIterable

      @Nonnull public static <T> AsyncIterable<T> filterIterable(@Nonnull Executor executor, @Nonnull AsyncIterable<T> iterable, @Nonnull Function<T,Boolean> filter)

    • dedupIterable

      @Nonnull public static <T> AsyncIterable<T> dedupIterable(@Nonnull AsyncIterable<T> iterable)
      Remove adjacent duplicates form iterable. Note: if iterable is sorted, this will actually remove duplicates.
      Type Parameters:
      T - the source type
      Parameters:
      iterable - the source
      Returns:
      a new AsyncIterable that only contains those items in iterable for which the previous item was different

    • dedupIterable

      @Nonnull public static <T> AsyncIterable<T> dedupIterable(@Nonnull Executor executor, @Nonnull AsyncIterable<T> iterable)

    • concatIterables

      @Nonnull public static <T> AsyncIterable<T> concatIterables(@Nonnull AsyncIterable<T>... iterables)
      Create a new iterable that has the contents of all the parameters in order.
      Type Parameters:
      T - the source type
      Parameters:
      iterables - a list of iterables to concatenate together
      Returns:
      a new AsyncIterable that starts with all the elements of the first iterable provided, then all the elements of the second iterable and so on

    • concatIterables

      @Nonnull public static <T> AsyncIterable<T> concatIterables(@Nonnull Executor executor, @Nonnull AsyncIterable<T>... iterables)

    • mapConcatIterable

      @Nonnull public static <T1, T2> AsyncIterable<T2> mapConcatIterable(@Nonnull AsyncIterable<T1> iterable, @Nonnull Function<T1,AsyncIterable<T2>> func, int pipelineSize)
      Maps each value in an iterable to a new iterable and returns the concatenated results. This will start a pipeline of asynchronous requests for up to a requested number of elements of the iterable, in parallel with requests to the mapping results. This does not pipeline the overlapping concatenations, i.e. it won't grab the first item of the second result of func, until it has exhausted the first result of func.
      Type Parameters:
      T1 - the type of the source
      T2 - the type of the destination iterables
      Parameters:
      iterable - the source
      func - mapping function from each element of iterable to a new iterable
      pipelineSize - the number of elements to pipeline
      Returns:
      the results of all the AsyncIterables returned by func for each value of iterable, concatenated

    • mapConcatIterable

      @Nonnull public static <T1, T2> AsyncIterable<T2> mapConcatIterable(@Nonnull Executor executor, @Nonnull AsyncIterable<T1> iterable, @Nonnull Function<T1,AsyncIterable<T2>> func, int pipelineSize)

    • filterIterablePipelined

      @Nonnull public static <T> AsyncIterable<T> filterIterablePipelined(@Nonnull AsyncIterable<T> iterable, @Nonnull Function<T,CompletableFuture<Boolean>> filter, int pipelineSize)
      Filter an iterable, pipelining the asynchronous filter functions. Unlike filterIterable, the filter here is asynchronous. As items comes back from iterable, a pipeline of filter futures is kept without advancing the iterable.
      Type Parameters:
      T - the source type
      Parameters:
      iterable - the source
      filter - only the values of iterable for which the future returned by this filter returns true will be in the resulting iterable
      pipelineSize - the number of filter results to pipeline
      Returns:
      a new AsyncIterable containing the elements of iterable for which filter returns a true future

    • filterIterablePipelined

      @Nonnull public static <T> AsyncIterable<T> filterIterablePipelined(@Nonnull Executor executor, @Nonnull AsyncIterable<T> iterable, @Nonnull Function<T,CompletableFuture<Boolean>> filter, int pipelineSize)

    • mapIterablePipelined

      @Nonnull public static <T1, T2> AsyncIterable<T2> mapIterablePipelined(@Nonnull AsyncIterable<T1> iterable, @Nonnull Function<T1,CompletableFuture<T2>> func, int pipelineSize)
      Maps an AsyncIterable using an asynchronous mapping function.
      Type Parameters:
      T1 - the source type
      T2 - the destination type
      Parameters:
      iterable - the source
      func - Maps items of iterable to a new value asynchronously
      pipelineSize - the number of map results to pipeline. As items comes back from iterable, this will have up to this many func futures in waiting before waiting on them without advancing the iterable.
      Returns:
      a new AsyncIterable with the results of applying func to each of the elements of iterable

    • reduce

      @Nullable public static <U, T> CompletableFuture<U> reduce(@Nonnull AsyncIterator<T> iterator, U identity, BiFunction<U,? super T,U> accumulator)
      Reduce contents of iterator to single value.
      Type Parameters:
      U - the result type of the reduction
      T - the element type of the iterator
      Parameters:
      iterator - source of values
      identity - initial value for reduction
      accumulator - function that takes previous reduced value and computes new value combining iterator element
      Returns:
      the reduced result

    • reduce

      @Nullable public static <U, T> CompletableFuture<U> reduce(@Nonnull Executor executor, @Nonnull AsyncIterator<T> iterator, U identity, BiFunction<U,? super T,U> accumulator)

    • isCompletedNormally

      @API(UNSTABLE) public static boolean isCompletedNormally(@Nonnull CompletableFuture<?> future)
      Returns whether the given CompletableFuture has completed normally, i.e., not exceptionally. If the future is yet to complete or if the future completed with an error, then this will return false.
      Parameters:
      future - the future to check for normal completion
      Returns:
      whether the future has completed without exception

    • getDefaultScheduledExecutor

      @Nonnull public static ScheduledExecutorService getDefaultScheduledExecutor()
      Get the default scheduled executor service. This is used to schedule delayed tasks in an efficient way by delayedFuture(long, TimeUnit). Adopters can provide their own ScheduledExecutorService by using the overloaded method.

      By default, the returned executor service is a ScheduledThreadPoolExecutor with a single thread used for executing delayed tasks. In practice, with a future chain, this should be quick asynchronous callbacks, and blocking in such a callback can block the task thread.

      Returns:
      an executor service that allows for tasks to be efficiently scheduled for later
      See Also:

    • delayedFuture

      @API(UNSTABLE) @Nonnull public static CompletableFuture<Void> delayedFuture(long delay, @Nonnull TimeUnit unit)
      Creates a future that will be ready after the given delay. This uses the getDefaultScheduledExecutor() to schedule tasks but is otherwise identical to delayedFuture(long, TimeUnit, ScheduledExecutorService).
      Parameters:
      delay - the time from now to delay execution
      unit - the time unit of the delay parameter
      Returns:
      a future that will be ready after the given delay
      See Also:

    • delayedFuture

      @API(UNSTABLE) @Nonnull public static CompletableFuture<Void> delayedFuture(long delay, @Nonnull TimeUnit unit, @Nonnull ScheduledExecutorService scheduledExecutor)
      Creates a future that will be ready after the given delay. The delayed future will be executed using the supplied ScheduledExecutorService to complete the returned future. Exact performance can depend on the scheduled executor implementation, but it should generally be safe to create many delayed futures at once. The guarantee given by this function is that the future will not be ready sooner than the delay specified. It may, however, fire after the given delay (especially if there are multiple delayed futures that are trying to fire at once).
      Parameters:
      delay - the time from now to delay execution
      unit - the time unit of the delay parameter
      scheduledExecutor - executor service used to complete the returned future and run any same-thread callbacks
      Returns:
      a CompletableFuture that will fire after the given delay

    • getWithDeadline

      @API(EXPERIMENTAL) public static <T> CompletableFuture<T> getWithDeadline(long deadlineTimeMillis, @Nonnull Supplier<CompletableFuture<T>> supplier, @Nonnull ScheduledExecutorService scheduledExecutor)
      Get a completable future that will either complete within the specified deadline time or complete exceptionally with MoreAsyncUtil.DeadlineExceededException. If deadlineTimeMillis is set to Long.MAX_VALUE, then no deadline is imposed on the future.
      Type Parameters:
      T - the return type for the get operation
      Parameters:
      deadlineTimeMillis - the maximum time to wait for the asynchronous operation to complete, specified in milliseconds
      supplier - the Supplier of the asynchronous result
      scheduledExecutor - executor used to handle managing the deadline
      Returns:
      a future that will either complete with the result of the asynchronous get operation or complete exceptionally if the deadline is exceeded

    • closeIterator

      @API(UNSTABLE) public static void closeIterator(@Nonnull Iterator<?> iterator)
      Close the given iterator, or at least cancel it.
      Parameters:
      iterator - iterator to close

    • composeWhenComplete

      public static <V> CompletableFuture<V> composeWhenComplete(@Nonnull CompletableFuture<V> future, @Nonnull BiFunction<V,Throwable,CompletableFuture<Void>> handler, @Nullable Function<Throwable,RuntimeException> exceptionMapper)
      This is supposed to replicate the semantics of CompletionStage.whenComplete(BiConsumer) but to handle the case where the completion handler might itself contain async work.
      Type Parameters:
      V - return type of original future
      Parameters:
      future - future to compose the handler onto
      handler - handler bi-function to compose onto the passed future
      exceptionMapper - function for mapping the underlying exception to a RuntimeException
      Returns:
      future with same completion properties as the future returned by the handler
      See Also:

    • composeWhenCompleteAndHandle

      public static <V, T> CompletableFuture<T> composeWhenCompleteAndHandle(@Nonnull CompletableFuture<V> future, @Nonnull BiFunction<V,Throwable,? extends CompletableFuture<T>> handler, @Nullable Function<Throwable,RuntimeException> exceptionMapper)
      Compose a handler bi-function to the result of a future. Unlike the AsyncUtil.composeHandle(CompletableFuture, BiFunction), which completes exceptionally only when the handler completes exceptionally, it completes exceptionally even if the supplied action itself (future) encounters an exception.
      Type Parameters:
      V - type of original future
      T - type of final future
      Parameters:
      future - future to compose the handler onto
      handler - handler bi-function to compose onto the passed future
      exceptionMapper - function for mapping the underlying exception to a RuntimeException
      Returns:
      future with same completion properties as the future returned by the handler
      See Also:

    • handleOnException

      public static <V> CompletableFuture<V> handleOnException(Supplier<CompletableFuture<V>> futureSupplier, Function<Throwable,CompletableFuture<V>> handlerOnException)
      Handle when futureSupplier encounters an exception when supplying a future, or the future is completed exceptionally. Unlike the "handle" in CompletableFuture, handlerOnException is not executed if the future is successful.
      Type Parameters:
      V - the result type of the future
      Parameters:
      futureSupplier - the supplier of future which needs to be handled
      handlerOnException - the handler when the future encounters an exception
      Returns:
      future that completes exceptionally if the handler has exception

    • combineAndFailFast

      public static <T, U, R> CompletableFuture<R> combineAndFailFast(CompletableFuture<T> future1, CompletableFuture<U> future2, BiFunction<T,U,R> combiner)
      Combine the results of two futures, but fail fast if either future fails.

      This has the same behavior as CompletableFuture.thenCombine(java.util.concurrent.CompletionStage<? extends U>, java.util.function.BiFunction<? super T, ? super U, ? extends V>), except, if either future fails, it won't wait for the other one to complete before completing the result with the failure.

      Type Parameters:
      T - the result type for future1
      U - the result type for future2
      R - the result type for the returned future
      Parameters:
      future1 - one future
      future2 - another future
      combiner - a function to combine the results of both future1 and future2 into a single result.
      Returns:
      a future that fails with one of the exceptions from future1 or future2 if either of those failed, or the result of applying combiner to their results if both succeeded.

    • swallowException

      public static CompletableFuture<Void> swallowException(@Nonnull CompletableFuture<Void> future, @Nonnull Predicate<Throwable> shouldSwallow)
      Swallows exceptions matching a given predicate from a future.
      Parameters:
      future - a future which you expect to potentially throw an exception
      shouldSwallow - a predicate on whether to swallow the error from the future. Note that if the future failed with a CompletionException, swallowException will also be called with its cause so that you don't need special handling to cover this.
      Returns:
      a future that will complete successfully if future completed successfully, or the shouldSwallow predicate returned true for the error that future threw

    • forLoop

      @Nonnull public static <U> CompletableFuture<U> forLoop(int startI, @Nullable U startU, @Nonnull IntPredicate conditionPredicate, @Nonnull IntUnaryOperator stepFunction, @Nonnull BiFunction<Integer,U,CompletableFuture<U>> body, @Nonnull Executor executor)
      Method that provides the functionality of a for loop, however, in an asynchronous way. The result of this method is a CompletableFuture that represents the result of the last iteration of the loop body.
      Type Parameters:
      U - the type of the result of the body BiFunction
      Parameters:
      startI - an integer analogous to the starting value of a loop variable in a for loop
      startU - an object of some type U that represents some initial state that is passed to the loop's initial state
      conditionPredicate - a predicate on the loop variable that must be true before the next iteration is entered; analogous to the condition in a for loop
      stepFunction - a unary operator used for modifying the loop variable after each iteration
      body - a bi-function to be called for each iteration; this function is initially invoked using startI and startU; the result of the body is then passed into the next iterator's body together with a new value for the loop variable. In this way callers can access state inside an iteration that was computed in a previous iteration.
      executor - the executor
      Returns:
      a CompletableFuture containing the result of the last iteration's body invocation.

    • forEach

      @Nonnull public static <T, U> CompletableFuture<List<U>> forEach(@Nonnull Iterable<T> items, @Nonnull Function<T,CompletableFuture<U>> body, int parallelism, @Nonnull Executor executor)
      Method to iterate over some items, for each of which a body is executed asynchronously. The result of each such executed is then collected in a list and returned as a CompletableFuture over that list.
      Type Parameters:
      T - the type of item
      U - the type of the result
      Parameters:
      items - the items to iterate over
      body - a function to be called for each item
      parallelism - the maximum degree of parallelism this method should use
      executor - the executor
      Returns:
      a CompletableFuture containing a list of results collected from the individual body invocations