Interface Future<T>

  • Type Parameters:
    T - Type of the computation result.
    All Superinterfaces:
    java.lang.Iterable<T>, Value<T>
    All Known Implementing Classes:
    FutureImpl

    public interface Future<T>
    extends Value<T>
    A Future is a computation result that becomes available at some point. All operations provided are non-blocking.

    The underlying Executor is used to execute asynchronous handlers, e.g. via onComplete(...).

    A Future has two states: pending and completed.

    • Pending: The computation is ongoing. Only a pending future may be completed or cancelled.
    • Completed: The computation finished successfully with a result, failed with an exception or was cancelled.
    Callbacks may be registered on a Future at each point of time. These actions are performed as soon as the Future is completed. An action which is registered on a completed Future is immediately performed. The action may run on a separate Thread, depending on the underlying Executor. Actions which are registered on a cancelled Future are performed with the failed result.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.concurrent.Executor DEFAULT_EXECUTOR
      The default executor is ForkJoinPool.commonPool().
      static java.util.concurrent.ExecutorService DEFAULT_EXECUTOR_SERVICE
      Deprecated.
      Will be removed in Vavr 1.0.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      default Future<T> andThen​(java.util.function.Consumer<? super Try<T>> action)
      Support for chaining of callbacks that are guaranteed to be executed in a specific order.
      Future<T> await()
      Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
      Future<T> await​(long timeout, java.util.concurrent.TimeUnit unit)
      Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.
      default boolean cancel()
      Cancels the Future.
      boolean cancel​(boolean mayInterruptIfRunning)
      Cancels the Future.
      default <R> Future<R> collect​(PartialFunction<? super T,​? extends R> partialFunction)
      Collects value that is in the domain of the given partialFunction by mapping the value to type R.
      default java.util.concurrent.Executor executor()
      Returns the Executor used by this Future.
      java.util.concurrent.ExecutorService executorService()
      Deprecated.
      Removed starting with Vavr 0.10.0, use executor() instead.
      default Future<java.lang.Throwable> failed()
      A projection that inverses the result of this Future.
      static <T> Future<T> failed​(java.lang.Throwable exception)
      Creates a failed Future with the given exception, backed by the DEFAULT_EXECUTOR.
      static <T> Future<T> failed​(java.util.concurrent.Executor executor, java.lang.Throwable exception)
      Creates a failed Future with the given exception, backed by the given Executor.
      default Future<T> fallbackTo​(Future<? extends T> that)
      Returns a Future that returns the result of this Future, if it is a success.
      default Future<T> filter​(java.util.function.Predicate<? super T> predicate)
      Shortcut for filterTry(predicate::test.
      default Future<T> filterTry​(CheckedPredicate<? super T> predicate)
      Filters the result of this Future by calling Try.filterTry(CheckedPredicate).
      static <T> Future<Option<T>> find​(java.lang.Iterable<? extends Future<? extends T>> futures, java.util.function.Predicate<? super T> predicate)
      Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate.
      static <T> Future<Option<T>> find​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends Future<? extends T>> futures, java.util.function.Predicate<? super T> predicate)
      Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate.
      static <T> Future<T> firstCompletedOf​(java.lang.Iterable<? extends Future<? extends T>> futures)
      Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the DEFAULT_EXECUTOR.
      static <T> Future<T> firstCompletedOf​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends Future<? extends T>> futures)
      Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the given Executor.
      default <U> Future<U> flatMap​(java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)  
      default <U> Future<U> flatMapTry​(CheckedFunction1<? super T,​? extends Future<? extends U>> mapper)  
      static <T,​U>
      Future<U>
      fold​(java.lang.Iterable<? extends Future<? extends T>> futures, U zero, java.util.function.BiFunction<? super U,​? super T,​? extends U> f)
      Returns a Future which contains the result of the fold of the given future values.
      static <T,​U>
      Future<U>
      fold​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends Future<? extends T>> futures, U zero, java.util.function.BiFunction<? super U,​? super T,​? extends U> f)
      Returns a Future which contains the result of the fold of the given future values.
      default void forEach​(java.util.function.Consumer<? super T> action)
      Performs the given action asynchronously hence this Future result becomes available.
      static <T> Future<T> fromCompletableFuture​(java.util.concurrent.CompletableFuture<T> future)
      Creates a Future with the given CompletableFuture, backed by the DEFAULT_EXECUTOR
      static <T> Future<T> fromCompletableFuture​(java.util.concurrent.Executor executor, java.util.concurrent.CompletableFuture<T> future)
      Creates a Future with the given CompletableFuture, backed by given Executor
      static <T> Future<T> fromJavaFuture​(java.util.concurrent.Executor executor, java.util.concurrent.Future<T> future)
      Creates a Future with the given java.util.concurrent.Future, backed by given Executor
      static <T> Future<T> fromJavaFuture​(java.util.concurrent.Future<T> future)
      Creates a Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR
      static <T> Future<T> fromTry​(Try<? extends T> result)
      Creates a Future from a Try, backed by the DEFAULT_EXECUTOR.
      static <T> Future<T> fromTry​(java.util.concurrent.Executor executor, Try<? extends T> result)
      Creates a Future from a Try, backed by the given Executor.
      default T get()
      Gets the value if the computation result is a Success or throws if it was a Failure.
      default Option<java.lang.Throwable> getCause()
      Returns the underlying exception of this Future, syntactic sugar for future.getValue().map(Try::getCause).
      Option<Try<T>> getValue()
      Returns the value of the Future.
      default boolean isAsync()
      A Futures's value is computed asynchronously.
      boolean isCancelled()
      Checks if this Future is cancelled, i.e.
      boolean isCompleted()
      Checks if this Future is completed, i.e.
      default boolean isEmpty()
      Checks, if this future has a value.
      default boolean isFailure()
      Checks if this Future completed with a failure.
      default boolean isLazy()
      A Future's value is computed eagerly.
      default boolean isSingleValued()
      A Future is single-valued.
      default boolean isSuccess()
      Checks if this Future completed with a success.
      default Iterator<T> iterator()
      Returns a rich io.vavr.collection.Iterator.
      default <U> Future<U> map​(java.util.function.Function<? super T,​? extends U> mapper)
      Maps the underlying value to a different component type.
      default <U> Future<U> mapTry​(CheckedFunction1<? super T,​? extends U> mapper)  
      static <T> Future<T> narrow​(Future<? extends T> future)
      Narrows a widened Future<? extends T> to Future<T> by performing a type-safe cast.
      static <T> Future<T> of​(CheckedFunction0<? extends T> computation)
      Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR.
      static <T> Future<T> of​(java.util.concurrent.Executor executor, CheckedFunction0<? extends T> computation)
      Starts an asynchronous computation, backed by the given Executor.
      static <T> Future<T> ofCallable​(java.util.concurrent.Callable<? extends T> computation)
      Deprecated.
      Will be removed.
      static <T> Future<T> ofCallable​(java.util.concurrent.Executor executor, java.util.concurrent.Callable<? extends T> computation)
      Deprecated.
      Will be removed.
      static <T> Future<T> ofSupplier​(java.util.concurrent.Executor executor, java.util.function.Supplier<? extends T> computation)
      Deprecated.
      Will be removed.
      static <T> Future<T> ofSupplier​(java.util.function.Supplier<? extends T> computation)
      Deprecated.
      Will be removed.
      Future<T> onComplete​(java.util.function.Consumer<? super Try<T>> action)
      Performs the action once the Future is complete.
      default Future<T> onFailure​(java.util.function.Consumer<? super java.lang.Throwable> action)
      Performs the action once the Future is complete and the result is a Try.Failure.
      default Future<T> onSuccess​(java.util.function.Consumer<? super T> action)
      Performs the action once the Future is complete and the result is a Try.Success.
      default Future<T> orElse​(Future<? extends T> other)  
      default Future<T> orElse​(java.util.function.Supplier<? extends Future<? extends T>> supplier)  
      default Future<T> peek​(java.util.function.Consumer<? super T> action)
      Performs the given action on the first element if this is an eager implementation.
      default Future<T> recover​(java.util.function.Function<? super java.lang.Throwable,​? extends T> f)
      Handles a failure of this Future by returning another result.
      default Future<T> recoverWith​(java.util.function.Function<? super java.lang.Throwable,​? extends Future<? extends T>> f)
      Handles a failure of this Future by returning the result of another Future.
      static <T> Future<T> reduce​(java.lang.Iterable<? extends Future<? extends T>> futures, java.util.function.BiFunction<? super T,​? super T,​? extends T> f)
      Returns a Future which contains the reduce result of the given future values.
      static <T> Future<T> reduce​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends Future<? extends T>> futures, java.util.function.BiFunction<? super T,​? super T,​? extends T> f)
      Returns a Future which contains the reduce result of the given future values.
      static Future<java.lang.Void> run​(CheckedRunnable unit)
      Runs an asynchronous computation, backed by the DEFAULT_EXECUTOR.
      static <T> Future<T> run​(Task<? extends T> task)
      Deprecated.
      Experimental API
      static Future<java.lang.Void> run​(java.util.concurrent.Executor executor, CheckedRunnable unit)
      Starts an asynchronous computation, backed by the given Executor.
      static <T> Future<T> run​(java.util.concurrent.Executor executor, Task<? extends T> task)
      Deprecated.
      Experimental API
      static Future<java.lang.Void> runRunnable​(java.lang.Runnable computation)
      Deprecated.
      Will be removed.
      static Future<java.lang.Void> runRunnable​(java.util.concurrent.Executor executor, java.lang.Runnable computation)
      Deprecated.
      Will be removed.
      static <T> Future<Seq<T>> sequence​(java.lang.Iterable<? extends Future<? extends T>> futures)
      Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
      static <T> Future<Seq<T>> sequence​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends Future<? extends T>> futures)
      Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
      default java.lang.String stringPrefix()
      Returns the name of this Value type, which is used by toString().
      static <T> Future<T> successful​(java.util.concurrent.Executor executor, T result)
      Creates a succeeded Future, backed by the given Executor.
      static <T> Future<T> successful​(T result)
      Creates a succeeded Future, backed by the DEFAULT_EXECUTOR.
      default java.util.concurrent.CompletableFuture<T> toCompletableFuture()
      Converts this to a CompletableFuture
      default <U> U transform​(java.util.function.Function<? super Future<T>,​? extends U> f)
      Transforms this Future.
      default <U> Future<U> transformValue​(java.util.function.Function<? super Try<T>,​? extends Try<? extends U>> f)
      Transforms the value of this Future, whether it is a success or a failure.
      static <T,​U>
      Future<Seq<U>>
      traverse​(java.lang.Iterable<? extends T> values, java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)
      Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
      static <T,​U>
      Future<Seq<U>>
      traverse​(java.util.concurrent.Executor executor, java.lang.Iterable<? extends T> values, java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)
      Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
      default <U> Future<Tuple2<T,​U>> zip​(Future<? extends U> that)
      Returns a tuple of this and that Future result.
      default <U,​R>
      Future<R>
      zipWith​(Future<? extends U> that, java.util.function.BiFunction<? super T,​? super U,​? extends R> combinator)
      Returns a this and that Future result combined using a given combinator function.
    • Field Detail

      • DEFAULT_EXECUTOR_SERVICE

        @Deprecated
        static final java.util.concurrent.ExecutorService DEFAULT_EXECUTOR_SERVICE
        Deprecated.
        Will be removed in Vavr 1.0. Use instead.
        The default executor service is ForkJoinPool.commonPool().

        Facts about ForkJoinPool:

        • It is work-stealing, i.e. all threads in the pool attempt to find work submitted to the pool. Especially this is efficient under heavy load (many small tasks), e.g. when tasks create subtasks (recursive threads).
        • The ForkJoinPool is dynamic, it has a maximum of 32767 running threads. Compared to fixed-size pools, this reduces the risk of dead-locks.
        • The commonPool() is shared across the entire VM. Keep this in mind when also using BaseStream.parallel() and CompletableFuture}
        The ForkJoinPool creates daemon threads but its run state is unaffected by attempts to shutdown() or shutdownNow(). However, all running tasks are immediately terminated upon program System.exit(int).

        IMPORTANT: Invoke ForkJoinPool.commonPool().awaitQuiescence(long, TimeUnit) before exit in order to ensure that all running async tasks complete before program termination.

        See Also:
        ForkJoinPool.awaitQuiescence(long, TimeUnit)
      • DEFAULT_EXECUTOR

        static final java.util.concurrent.Executor DEFAULT_EXECUTOR
        The default executor is ForkJoinPool.commonPool().

        Facts about ForkJoinPool:

        • It is work-stealing, i.e. all threads in the pool attempt to find work submitted to the pool. Especially this is efficient under heavy load (many small tasks), e.g. when tasks create subtasks (recursive threads).
        • The ForkJoinPool is dynamic, it has a maximum of 32767 running threads. Compared to fixed-size pools, this reduces the risk of dead-locks.
        • The commonPool() is shared across the entire VM. Keep this in mind when also using BaseStream.parallel() and CompletableFuture}
        The ForkJoinPool creates daemon threads but its run state is unaffected by attempts to shutdown() or shutdownNow(). However, all running tasks are immediately terminated upon program System.exit(int).

        IMPORTANT: Invoke ForkJoinPool.commonPool().awaitQuiescence(long, TimeUnit) before exit in order to ensure that all running async tasks complete before program termination.

        See Also:
        ForkJoinPool.awaitQuiescence(long, TimeUnit)
    • Method Detail

      • failed

        static <T> Future<T> failed​(java.lang.Throwable exception)
        Creates a failed Future with the given exception, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        exception - The reason why it failed.
        Returns:
        A failed Future.
        Throws:
        java.lang.NullPointerException - if exception is null
      • failed

        static <T> Future<T> failed​(java.util.concurrent.Executor executor,
                                    java.lang.Throwable exception)
        Creates a failed Future with the given exception, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor.
        exception - The reason why it failed.
        Returns:
        A failed Future.
        Throws:
        java.lang.NullPointerException - if executor or exception is null
      • find

        static <T> Future<Option<T>> find​(java.lang.Iterable<? extends Future<? extends T>> futures,
                                          java.util.function.Predicate<? super T> predicate)
        Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate. If no result matches, the Future will contain Option.None.

        The returned Future is backed by the DEFAULT_EXECUTOR.

        Type Parameters:
        T - Result type of the futures.
        Parameters:
        futures - An iterable of futures.
        predicate - A predicate that tests successful future results.
        Returns:
        A Future of an Option of the first result of the given futures that satisfies the given predicate.
        Throws:
        java.lang.NullPointerException - if one of the arguments is null
      • find

        static <T> Future<Option<T>> find​(java.util.concurrent.Executor executor,
                                          java.lang.Iterable<? extends Future<? extends T>> futures,
                                          java.util.function.Predicate<? super T> predicate)
        Returns a Future that eventually succeeds with the first result of the given Futures which matches the given predicate. If no result matches, the Future will contain Option.None.

        The returned Future is backed by the given Executor.

        Type Parameters:
        T - Result type of the futures.
        Parameters:
        executor - An Executor.
        futures - An iterable of futures.
        predicate - A predicate that tests successful future results.
        Returns:
        A Future of an Option of the first result of the given futures that satisfies the given predicate.
        Throws:
        java.lang.NullPointerException - if one of the arguments is null
      • firstCompletedOf

        static <T> Future<T> firstCompletedOf​(java.lang.Iterable<? extends Future<? extends T>> futures)
        Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - The result type.
        Parameters:
        futures - An iterable of futures.
        Returns:
        A new Future.
        Throws:
        java.lang.NullPointerException - if futures is null
      • firstCompletedOf

        static <T> Future<T> firstCompletedOf​(java.util.concurrent.Executor executor,
                                              java.lang.Iterable<? extends Future<? extends T>> futures)
        Returns a new Future that will contain the result of the first of the given futures that is completed, backed by the given Executor.
        Type Parameters:
        T - The result type.
        Parameters:
        executor - An Executor.
        futures - An iterable of futures.
        Returns:
        A new Future.
        Throws:
        java.lang.NullPointerException - if executor or futures is null
      • fold

        static <T,​U> Future<U> fold​(java.lang.Iterable<? extends Future<? extends T>> futures,
                                          U zero,
                                          java.util.function.BiFunction<? super U,​? super T,​? extends U> f)
        Returns a Future which contains the result of the fold of the given future values. If any future or the fold fail, the result is a failure.

        The resulting Future is backed by the DEFAULT_EXECUTOR.

        Type Parameters:
        T - The result type of the given Futures.
        U - The fold result type.
        Parameters:
        futures - An iterable of futures.
        zero - The zero element of the fold.
        f - The fold operation.
        Returns:
        A new Future that will contain the fold result.
        Throws:
        java.lang.NullPointerException - if futures or f is null.
      • fold

        static <T,​U> Future<U> fold​(java.util.concurrent.Executor executor,
                                          java.lang.Iterable<? extends Future<? extends T>> futures,
                                          U zero,
                                          java.util.function.BiFunction<? super U,​? super T,​? extends U> f)
        Returns a Future which contains the result of the fold of the given future values. If any future or the fold fail, the result is a failure.

        The resulting Future is backed by the given Executor.

        Type Parameters:
        T - The result type of the given Futures.
        U - The fold result type.
        Parameters:
        executor - An Executor.
        futures - An iterable of futures.
        zero - The zero element of the fold.
        f - The fold operation.
        Returns:
        A new Future that will contain the fold result.
        Throws:
        java.lang.NullPointerException - if executor, futures or f is null.
      • fromJavaFuture

        static <T> Future<T> fromJavaFuture​(java.util.concurrent.Future<T> future)
        Creates a Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR
        Type Parameters:
        T - Result type of the Future
        Parameters:
        future - A Future
        Returns:
        A new Future wrapping the result of the Java future
        Throws:
        java.lang.NullPointerException - if future is null
      • fromJavaFuture

        static <T> Future<T> fromJavaFuture​(java.util.concurrent.Executor executor,
                                            java.util.concurrent.Future<T> future)
        Creates a Future with the given java.util.concurrent.Future, backed by given Executor
        Type Parameters:
        T - Result type of the Future
        Parameters:
        executor - An Executor.
        future - A Future.
        Returns:
        A new Future wrapping the result of the Java future
        Throws:
        java.lang.NullPointerException - if executor or future is null
      • fromCompletableFuture

        @GwtIncompatible
        static <T> Future<T> fromCompletableFuture​(java.util.concurrent.CompletableFuture<T> future)
        Creates a Future with the given CompletableFuture, backed by the DEFAULT_EXECUTOR
        Type Parameters:
        T - Result type of the Future
        Parameters:
        future - A CompletableFuture
        Returns:
        A new Future wrapping the result of the CompletableFuture
        Throws:
        java.lang.NullPointerException - if future is null
      • fromCompletableFuture

        @GwtIncompatible
        static <T> Future<T> fromCompletableFuture​(java.util.concurrent.Executor executor,
                                                   java.util.concurrent.CompletableFuture<T> future)
        Creates a Future with the given CompletableFuture, backed by given Executor
        Type Parameters:
        T - Result type of the Future
        Parameters:
        executor - An Executor.
        future - A CompletableFuture.
        Returns:
        A new Future wrapping the result of the CompletableFuture
        Throws:
        java.lang.NullPointerException - if executor or future is null
      • fromTry

        static <T> Future<T> fromTry​(Try<? extends T> result)
        Creates a Future from a Try, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        result - The result.
        Returns:
        A completed Future which contains either a Success or a Failure.
        Throws:
        java.lang.NullPointerException - if result is null
      • fromTry

        static <T> Future<T> fromTry​(java.util.concurrent.Executor executor,
                                     Try<? extends T> result)
        Creates a Future from a Try, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor.
        result - The result.
        Returns:
        A completed Future which contains either a Success or a Failure.
        Throws:
        java.lang.NullPointerException - if executor or result is null
      • narrow

        static <T> Future<T> narrow​(Future<? extends T> future)
        Narrows a widened Future<? extends T> to Future<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.
        Type Parameters:
        T - Component type of the Future.
        Parameters:
        future - A Future.
        Returns:
        the given future instance as narrowed type Future<T>.
      • ofSupplier

        @Deprecated
        static <T> Future<T> ofSupplier​(java.util.function.Supplier<? extends T> computation)
        Deprecated.
        Will be removed. Use Future.of(supplier::get) instead of Future.ofSupplier(supplier).
        Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        computation - A computation.
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if computation is null.
      • ofSupplier

        @Deprecated
        static <T> Future<T> ofSupplier​(java.util.concurrent.Executor executor,
                                        java.util.function.Supplier<? extends T> computation)
        Deprecated.
        Will be removed. Use Future.of(executor, supplier::get) instead of Future.ofSupplier(executor, supplier).
        Starts an asynchronous computation, backed by the given Executor.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        executor - An executor service.
        computation - A computation.
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if one of executor or computation is null.
      • ofCallable

        @Deprecated
        static <T> Future<T> ofCallable​(java.util.concurrent.Callable<? extends T> computation)
        Deprecated.
        Will be removed. Use Future.of(callable::call) instead of Future.ofCallable(callable).
        Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        computation - A computation
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if computation is null.
      • ofCallable

        @Deprecated
        static <T> Future<T> ofCallable​(java.util.concurrent.Executor executor,
                                        java.util.concurrent.Callable<? extends T> computation)
        Deprecated.
        Will be removed. Use Future.of(executor, callable::call) instead of Future.ofCallable(executor, callable).
        Starts an asynchronous computation, backed by the given Executor.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        executor - An executor service.
        computation - A computation.
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if one of executor or computation is null.
      • runRunnable

        @Deprecated
        static Future<java.lang.Void> runRunnable​(java.lang.Runnable computation)
        Deprecated.
        Will be removed. Use Future.of(runnable::run) instead of Future.runRunnable(runnable).
        Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR.
        Parameters:
        computation - A computation
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if computation is null.
      • runRunnable

        @Deprecated
        static Future<java.lang.Void> runRunnable​(java.util.concurrent.Executor executor,
                                                  java.lang.Runnable computation)
        Deprecated.
        Will be removed. Use Future.of(executor, runnable::run) instead of Future.runRunnable(executor, runnable).
        Starts an asynchronous computation, backed by the given Executor.
        Parameters:
        executor - An executor service.
        computation - A computation.
        Returns:
        A new Future instance
        Throws:
        java.lang.NullPointerException - if one of executor or computation is null.
      • of

        static <T> Future<T> of​(CheckedFunction0<? extends T> computation)
        Starts an asynchronous computation, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        computation - A computation.
        Returns:
        A new Future instance.
        Throws:
        java.lang.NullPointerException - if computation is null.
      • of

        static <T> Future<T> of​(java.util.concurrent.Executor executor,
                                CheckedFunction0<? extends T> computation)
        Starts an asynchronous computation, backed by the given Executor.
        Type Parameters:
        T - Type of the computation result.
        Parameters:
        executor - An Executor.
        computation - A computation.
        Returns:
        A new Future instance.
        Throws:
        java.lang.NullPointerException - if one of executor or computation is null.
      • run

        @Deprecated
        static <T> Future<T> run​(Task<? extends T> task)
        Deprecated.
        Experimental API
        Creates a (possibly blocking) Future that runs the results of the given computation using a completion handler:
        
         CheckedConsumer<Predicate<Try<T>>> computation = complete -> {
             // computation
         };
         
        The computation is executed synchronously. It requires to complete the returned Future. A common use-case is to hand over the complete predicate to another Future in order to prevent blocking:
        
         Future<String> greeting(Future<String> nameFuture) {
             return Future.run(complete -> {
                 nameFuture.onComplete(name -> complete.test("Hi " + name));
             });
         }
        The computation receives a Predicate, named complete by convention, that takes a result of type Try<T> and returns a boolean that states whether the Future was completed.

        Future completion is an idempotent operation in the way that the first call of complete will return true, successive calls will return false.

        Type Parameters:
        T - Type of the result
        Parameters:
        task - A computational task
        Returns:
        a new Future instance
      • run

        @Deprecated
        static <T> Future<T> run​(java.util.concurrent.Executor executor,
                                 Task<? extends T> task)
        Deprecated.
        Experimental API
        Creates a (possibly blocking) Future that runs the results of the given computation using a completion handler:
        
         CheckedConsumer<Predicate<Try<T>>> computation = complete -> {
             // computation
         };
         
        The computation is executed synchronously. It requires to complete the returned Future. A common use-case is to hand over the complete predicate to another Future in order to prevent blocking:
        
         Future<String> greeting(Future<String> nameFuture) {
             return Future.run(complete -> {
                 nameFuture.onComplete(name -> complete.with("Hi " + name));
             });
         }
        The computation receives a Predicate, named complete by convention, that takes a result of type Try<T> and returns a boolean that states whether the Future was completed.

        Future completion is an idempotent operation in the way that the first call of complete will return true, successive calls will return false.

        Type Parameters:
        T - Type of the result
        Parameters:
        executor - An Executor that runs the given computation
        task - A computational task
        Returns:
        a new Future instance
      • reduce

        static <T> Future<T> reduce​(java.lang.Iterable<? extends Future<? extends T>> futures,
                                    java.util.function.BiFunction<? super T,​? super T,​? extends T> f)
        Returns a Future which contains the reduce result of the given future values. The zero is the result of the first future that completes. If any future or the reduce operation fail, the result is a failure.

        The resulting Future is backed by the DEFAULT_EXECUTOR.

        Type Parameters:
        T - The result type of the given Futures.
        Parameters:
        futures - An iterable of futures.
        f - The reduce operation.
        Returns:
        A new Future that will contain the reduce result.
        Throws:
        java.lang.NullPointerException - if executor, futures or f is null.
      • reduce

        static <T> Future<T> reduce​(java.util.concurrent.Executor executor,
                                    java.lang.Iterable<? extends Future<? extends T>> futures,
                                    java.util.function.BiFunction<? super T,​? super T,​? extends T> f)
        Returns a Future which contains the reduce result of the given future values. The zero is the result of the first future that completes. If any future or the reduce operation fail, the result is a failure.

        The resulting Future is backed by the given Executor.

        Type Parameters:
        T - The result type of the given Futures.
        Parameters:
        executor - An Executor.
        futures - An iterable of futures.
        f - The reduce operation.
        Returns:
        A new Future that will contain the reduce result.
        Throws:
        java.lang.NullPointerException - if executor, futures or f is null.
      • run

        static Future<java.lang.Void> run​(CheckedRunnable unit)
        Runs an asynchronous computation, backed by the DEFAULT_EXECUTOR.
        Parameters:
        unit - A unit of work.
        Returns:
        A new Future instance which results in nothing.
        Throws:
        java.lang.NullPointerException - if unit is null.
      • run

        static Future<java.lang.Void> run​(java.util.concurrent.Executor executor,
                                          CheckedRunnable unit)
        Starts an asynchronous computation, backed by the given Executor.
        Parameters:
        executor - An Executor.
        unit - A unit of work.
        Returns:
        A new Future instance which results in nothing.
        Throws:
        java.lang.NullPointerException - if one of executor or unit is null.
      • sequence

        static <T> Future<Seq<T>> sequence​(java.lang.Iterable<? extends Future<? extends T>> futures)
        Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

        The resulting Future is backed by the DEFAULT_EXECUTOR.

        • If all of the given Futures succeed, sequence() succeeds too:
          // = Future(Success(Seq(1, 2)))
           sequence(
               List.of(
                   Future.of(() -> 1),
                   Future.of(() -> 2)
               )
           );
        • If a given Future fails, sequence() fails too:
          // = Future(Failure(Error)))
           sequence(
               List.of(
                   Future.of(() -> 1),
                   Future.of(() -> { throw new Error(); }
               )
           );
        Type Parameters:
        T - Result type of the futures.
        Parameters:
        futures - An Iterable of Futures.
        Returns:
        A Future of a Seq of results.
        Throws:
        java.lang.NullPointerException - if futures is null.
      • sequence

        static <T> Future<Seq<T>> sequence​(java.util.concurrent.Executor executor,
                                           java.lang.Iterable<? extends Future<? extends T>> futures)
        Reduces many Futures into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

        The resulting Future is backed by the given Executor.

        Type Parameters:
        T - Result type of the futures.
        Parameters:
        executor - An Executor.
        futures - An Iterable of Futures.
        Returns:
        A Future of a Seq of results.
        Throws:
        java.lang.NullPointerException - if executor or futures is null.
      • successful

        static <T> Future<T> successful​(T result)
        Creates a succeeded Future, backed by the DEFAULT_EXECUTOR.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        result - The result.
        Returns:
        A succeeded Future.
      • successful

        static <T> Future<T> successful​(java.util.concurrent.Executor executor,
                                        T result)
        Creates a succeeded Future, backed by the given Executor.
        Type Parameters:
        T - The value type of a successful result.
        Parameters:
        executor - An Executor.
        result - The result.
        Returns:
        A succeeded Future.
        Throws:
        java.lang.NullPointerException - if executor is null
      • toCompletableFuture

        @GwtIncompatible
        default java.util.concurrent.CompletableFuture<T> toCompletableFuture()
        Description copied from interface: Value
        Converts this to a CompletableFuture
        Specified by:
        toCompletableFuture in interface Value<T>
        Returns:
        A new CompletableFuture containing the value
      • traverse

        static <T,​U> Future<Seq<U>> traverse​(java.lang.Iterable<? extends T> values,
                                                   java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)
        Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

        The resulting Future is backed by the DEFAULT_EXECUTOR.

        Type Parameters:
        T - The type of the given values.
        U - The mapped value type.
        Parameters:
        values - An Iterable of Futures.
        mapper - A mapper of values to Futures
        Returns:
        A Future of a Seq of results.
        Throws:
        java.lang.NullPointerException - if values or f is null.
      • traverse

        static <T,​U> Future<Seq<U>> traverse​(java.util.concurrent.Executor executor,
                                                   java.lang.Iterable<? extends T> values,
                                                   java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)
        Maps the values of an iterable in parallel to a sequence of mapped values into a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

        The resulting Future is backed by the given Executor.

        Type Parameters:
        T - The type of the given values.
        U - The mapped value type.
        Parameters:
        executor - An Executor.
        values - An Iterable of values.
        mapper - A mapper of values to Futures
        Returns:
        A Future of a Seq of results.
        Throws:
        java.lang.NullPointerException - if executor, values or f is null.
      • andThen

        default Future<T> andThen​(java.util.function.Consumer<? super Try<T>> action)
        Support for chaining of callbacks that are guaranteed to be executed in a specific order.

        An exception, which occurs when performing the given action, is not propagated to the outside. In other words, subsequent actions are performed based on the value of the original Future.

        Example:

        
         // prints Success(1)
         Future.of(() -> 1)
               .andThen(t -> { throw new Error(""); })
               .andThen(System.out::println);
         
        Parameters:
        action - A side-effecting action.
        Returns:
        A new Future that contains this result and which is completed after the given action was performed.
        Throws:
        java.lang.NullPointerException - if action is null
      • await

        Future<T> await()
        Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.

        In the case the current thread was interrupted while waiting, a failed Future is returned containing the corresponding InterruptedException.

        Returns:
        this Future instance
      • await

        Future<T> await​(long timeout,
                        java.util.concurrent.TimeUnit unit)
        Blocks the current Thread until this Future completed or returns immediately if this Future is already completed.

        In the case the current thread was interrupted while waiting, a failed Future is returned containing the corresponding InterruptedException.

        If the deadline wasn't met, a failed Future is returned containing a TimeoutException.

        Parameters:
        timeout - the maximum time to wait
        unit - the time unit of the timeout argument
        Returns:
        this Future instance
        Throws:
        java.lang.IllegalArgumentException - if timeout is negative
        java.lang.NullPointerException - if unit is null
      • cancel

        default boolean cancel()
        Cancels the Future. A running thread is interrupted.

        If the Future was successfully cancelled, the result is a Failure(CancellationException).

        Returns:
        false, if this Future is already completed or could not be cancelled, otherwise true.
        Throws:
        java.lang.SecurityException - if the current thread cannot modify the Future's thread
        See Also:
        isCancelled()
      • cancel

        boolean cancel​(boolean mayInterruptIfRunning)
        Cancels the Future. A pending Future may be interrupted, depending on the underlying Executor.

        If the Future was successfully cancelled, the result is a Failure(CancellationException).

        Parameters:
        mayInterruptIfRunning - true if a running thread should be interrupted, otherwise a running thread is allowed to complete its computation.
        Returns:
        false, if this Future is already completed or could not be cancelled, otherwise true.
        Throws:
        java.lang.SecurityException - if the current thread cannot modify the Future's thread
        See Also:
        isCancelled(), Future.cancel(boolean)
      • collect

        default <R> Future<R> collect​(PartialFunction<? super T,​? extends R> partialFunction)
        Collects value that is in the domain of the given partialFunction by mapping the value to type R.
        
         partialFunction.isDefinedAt(value)
         
        If the element makes it through that filter, the mapped instance is wrapped in Future
        
         R newValue = partialFunction.apply(value)
         
        Type Parameters:
        R - The new value type
        Parameters:
        partialFunction - A function that is not necessarily defined on value of this future.
        Returns:
        A new Future instance containing value of type R
        Throws:
        java.lang.NullPointerException - if partialFunction is null
      • executor

        default java.util.concurrent.Executor executor()
        Returns the Executor used by this Future.
        Returns:
        The underlying Executor.
      • executorService

        @Deprecated
        java.util.concurrent.ExecutorService executorService()
                                                      throws java.lang.UnsupportedOperationException
        Deprecated.
        Removed starting with Vavr 0.10.0, use executor() instead.
        This method is deprecated.

        THE DEFAULT IMPLEMENTATION (obtained by one of the Future factory methods) MIGHT THROW AN UnsupportedOperationException AT RUNTIME.

        Returns:
        (never)
        Throws:
        java.lang.UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.
      • failed

        default Future<java.lang.Throwable> failed()
        A projection that inverses the result of this Future.

        If this Future succeeds, the failed projection returns a failure containing a NoSuchElementException.

        If this Future fails, the failed projection returns a success containing the exception.

        Returns:
        A new Future which contains an exception at a point of time.
      • fallbackTo

        default Future<T> fallbackTo​(Future<? extends T> that)
        Returns a Future that returns the result of this Future, if it is a success. If the value of this Future is a failure, the result of that Future is returned, if that is a success. If both Futures fail, the failure of this Future is returned.

        Example:

        
         Future<Integer> future = Future.of(() -> { throw new Error(); });
         Future<Integer> that = Future.of(() -> 1);
         Future<Integer> result = future.fallbackTo(that);
        
         // prints Some(1)
         result.onComplete(System.out::println);
         
        Parameters:
        that - A fallback future computation
        Returns:
        A new Future
        Throws:
        java.lang.NullPointerException - if that is null
      • filter

        default Future<T> filter​(java.util.function.Predicate<? super T> predicate)
        Shortcut for filterTry(predicate::test.
        Parameters:
        predicate - A predicate
        Returns:
        A new Future
        Throws:
        java.lang.NullPointerException - if predicate is null
      • filterTry

        default Future<T> filterTry​(CheckedPredicate<? super T> predicate)
        Filters the result of this Future by calling Try.filterTry(CheckedPredicate).
        Parameters:
        predicate - A checked predicate
        Returns:
        A new Future
        Throws:
        java.lang.NullPointerException - if predicate is null
      • getCause

        default Option<java.lang.Throwable> getCause()
        Returns the underlying exception of this Future, syntactic sugar for future.getValue().map(Try::getCause).
        Returns:
        None if the Future is not completed yet. Returns Some(Throwable) if the Future was completed with a failure.
        Throws:
        java.lang.UnsupportedOperationException - if the Future was successfully completed with a value
      • getValue

        Option<Try<T>> getValue()
        Returns the value of the Future.
        Returns:
        None, if the Future is not yet completed or was cancelled, otherwise Some(Try).
      • isCancelled

        boolean isCancelled()
        Checks if this Future is cancelled, i.e. the thread was forced to stop before completion.
        Returns:
        true, if the computation was cancelled, false otherwise
      • isCompleted

        boolean isCompleted()
        Checks if this Future is completed, i.e. has a value.
        Returns:
        true, if the computation successfully finished, failed or was cancelled, false otherwise.
      • isSuccess

        default boolean isSuccess()
        Checks if this Future completed with a success.
        Returns:
        true, if this Future completed and is a Success, false otherwise.
      • isFailure

        default boolean isFailure()
        Checks if this Future completed with a failure.
        Returns:
        true, if this Future completed and is a Failure, false otherwise.
      • onComplete

        Future<T> onComplete​(java.util.function.Consumer<? super Try<T>> action)
        Performs the action once the Future is complete.
        Parameters:
        action - An action to be performed when this future is complete.
        Returns:
        this Future
        Throws:
        java.lang.NullPointerException - if action is null.
      • onFailure

        default Future<T> onFailure​(java.util.function.Consumer<? super java.lang.Throwable> action)
        Performs the action once the Future is complete and the result is a Try.Failure. Please note that the future is also a failure when it was cancelled.
        Parameters:
        action - An action to be performed when this future failed.
        Returns:
        this Future
        Throws:
        java.lang.NullPointerException - if action is null.
      • onSuccess

        default Future<T> onSuccess​(java.util.function.Consumer<? super T> action)
        Performs the action once the Future is complete and the result is a Try.Success.
        Parameters:
        action - An action to be performed when this future succeeded.
        Returns:
        this Future
        Throws:
        java.lang.NullPointerException - if action is null.
      • recover

        default Future<T> recover​(java.util.function.Function<? super java.lang.Throwable,​? extends T> f)
        Handles a failure of this Future by returning another result.

        Example:

        
         // = "oh!"
         Future.of(() -> new Error("oh!")).recover(Throwable::getMessage);
         
        Parameters:
        f - A function which takes the exception of a failure and returns a new value.
        Returns:
        A new Future.
        Throws:
        java.lang.NullPointerException - if f is null
      • recoverWith

        default Future<T> recoverWith​(java.util.function.Function<? super java.lang.Throwable,​? extends Future<? extends T>> f)
        Handles a failure of this Future by returning the result of another Future.

        Example:

        
         // = "oh!"
         Future.of(() -> { throw new Error("oh!"); }).recoverWith(x -> Future.of(x::getMessage));
         
        Parameters:
        f - A function which takes the exception of a failure and returns a new future.
        Returns:
        A new Future.
        Throws:
        java.lang.NullPointerException - if f is null
      • transform

        default <U> U transform​(java.util.function.Function<? super Future<T>,​? extends U> f)
        Transforms this Future.
        Type Parameters:
        U - Type of transformation result
        Parameters:
        f - A transformation
        Returns:
        An instance of type U
        Throws:
        java.lang.NullPointerException - if f is null
      • transformValue

        default <U> Future<U> transformValue​(java.util.function.Function<? super Try<T>,​? extends Try<? extends U>> f)
        Transforms the value of this Future, whether it is a success or a failure.
        Type Parameters:
        U - Generic type of transformation Try result
        Parameters:
        f - A transformation
        Returns:
        A Future of type U
        Throws:
        java.lang.NullPointerException - if f is null
      • zip

        default <U> Future<Tuple2<T,​U>> zip​(Future<? extends U> that)
        Returns a tuple of this and that Future result.

        If this Future failed the result contains this failure. Otherwise the result contains that failure or a tuple of both successful Future results.

        Type Parameters:
        U - Result type of that
        Parameters:
        that - Another Future
        Returns:
        A new Future that returns both Future results.
        Throws:
        java.lang.NullPointerException - if that is null
      • zipWith

        default <U,​R> Future<R> zipWith​(Future<? extends U> that,
                                              java.util.function.BiFunction<? super T,​? super U,​? extends R> combinator)
        Returns a this and that Future result combined using a given combinator function.

        If this Future failed the result contains this failure. Otherwise the result contains that failure or a combination of both successful Future results.

        Type Parameters:
        U - Result type of that
        R - Result type of f
        Parameters:
        that - Another Future
        combinator - The combinator function
        Returns:
        A new Future that returns both Future results.
        Throws:
        java.lang.NullPointerException - if that is null
      • flatMap

        default <U> Future<U> flatMap​(java.util.function.Function<? super T,​? extends Future<? extends U>> mapper)
      • forEach

        default void forEach​(java.util.function.Consumer<? super T> action)
        Performs the given action asynchronously hence this Future result becomes available. The action is not performed, if the result is a failure.
        Specified by:
        forEach in interface java.lang.Iterable<T>
        Specified by:
        forEach in interface Value<T>
        Parameters:
        action - A Consumer
      • get

        default T get()
        Gets the value if the computation result is a Success or throws if it was a Failure. Waits for the result if necessary by blocking the current thread.

        IMPORTANT! If the computation result is a Try.Failure, the underlying cause of type Throwable is thrown.

        Specified by:
        get in interface Value<T>
        Returns:
        The value of this Future.
      • isAsync

        default boolean isAsync()
        A Futures's value is computed asynchronously.
        Specified by:
        isAsync in interface Value<T>
        Returns:
        true
      • isEmpty

        default boolean isEmpty()
        Checks, if this future has a value.
        Specified by:
        isEmpty in interface Value<T>
        Returns:
        true, if this future succeeded with a value, false otherwise.
      • isLazy

        default boolean isLazy()
        A Future's value is computed eagerly.
        Specified by:
        isLazy in interface Value<T>
        Returns:
        false
      • isSingleValued

        default boolean isSingleValued()
        A Future is single-valued.
        Specified by:
        isSingleValued in interface Value<T>
        Returns:
        true
      • iterator

        default Iterator<T> iterator()
        Description copied from interface: Value
        Returns a rich io.vavr.collection.Iterator.
        Specified by:
        iterator in interface java.lang.Iterable<T>
        Specified by:
        iterator in interface Value<T>
        Returns:
        A new Iterator
      • map

        default <U> Future<U> map​(java.util.function.Function<? super T,​? extends U> mapper)
        Description copied from interface: Value
        Maps the underlying value to a different component type.
        Specified by:
        map in interface Value<T>
        Type Parameters:
        U - The new component type
        Parameters:
        mapper - A mapper
        Returns:
        A new value
      • orElse

        default Future<T> orElse​(java.util.function.Supplier<? extends Future<? extends T>> supplier)
      • peek

        default Future<T> peek​(java.util.function.Consumer<? super T> action)
        Description copied from interface: Value
        Performs the given action on the first element if this is an eager implementation. Performs the given action on all elements (the first immediately, successive deferred), if this is a lazy implementation.
        Specified by:
        peek in interface Value<T>
        Parameters:
        action - The action that will be performed on the element(s).
        Returns:
        this instance
      • stringPrefix

        default java.lang.String stringPrefix()
        Description copied from interface: Value
        Returns the name of this Value type, which is used by toString().
        Specified by:
        stringPrefix in interface Value<T>
        Returns:
        This type name.