Interface Future<T>

Type Parameters:
T - Type of the computation result.
All Superinterfaces:
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 Details

    • DEFAULT_EXECUTOR_SERVICE

      @Deprecated static final 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:
    • DEFAULT_EXECUTOR

      static final 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:
  • Method Details

    • failed

      static <T> Future<T> failed(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:
      NullPointerException - if exception is null
    • failed

      static <T> Future<T> failed(Executor executor, 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:
      NullPointerException - if executor or exception is null
    • find

      static <T> Future<Option<T>> find(Iterable<? extends Future<? extends T>> futures, 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:
      NullPointerException - if one of the arguments is null
    • find

      static <T> Future<Option<T>> find(Executor executor, Iterable<? extends Future<? extends T>> futures, 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:
      NullPointerException - if one of the arguments is null
    • firstCompletedOf

      static <T> Future<T> firstCompletedOf(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:
      NullPointerException - if futures is null
    • firstCompletedOf

      static <T> Future<T> firstCompletedOf(Executor executor, 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:
      NullPointerException - if executor or futures is null
    • fold

      static <T, U> Future<U> fold(Iterable<? extends Future<? extends T>> futures, U zero, 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:
      NullPointerException - if futures or f is null.
    • fold

      static <T, U> Future<U> fold(Executor executor, Iterable<? extends Future<? extends T>> futures, U zero, 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:
      NullPointerException - if executor, futures or f is null.
    • fromJavaFuture

      static <T> Future<T> fromJavaFuture(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:
      NullPointerException - if future is null
    • fromJavaFuture

      static <T> Future<T> fromJavaFuture(Executor executor, 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:
      NullPointerException - if executor or future is null
    • fromCompletableFuture

      @GwtIncompatible static <T> Future<T> fromCompletableFuture(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:
      NullPointerException - if future is null
    • fromCompletableFuture

      @GwtIncompatible static <T> Future<T> fromCompletableFuture(Executor executor, 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:
      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:
      NullPointerException - if result is null
    • fromTry

      static <T> Future<T> fromTry(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:
      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(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:
      NullPointerException - if computation is null.
    • ofSupplier

      @Deprecated static <T> Future<T> ofSupplier(Executor executor, 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:
      NullPointerException - if one of executor or computation is null.
    • ofCallable

      @Deprecated static <T> Future<T> ofCallable(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:
      NullPointerException - if computation is null.
    • ofCallable

      @Deprecated static <T> Future<T> ofCallable(Executor executor, 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:
      NullPointerException - if one of executor or computation is null.
    • runRunnable

      @Deprecated static Future<Void> runRunnable(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:
      NullPointerException - if computation is null.
    • runRunnable

      @Deprecated static Future<Void> runRunnable(Executor executor, 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:
      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:
      NullPointerException - if computation is null.
    • of

      static <T> Future<T> of(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:
      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(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(Iterable<? extends Future<? extends T>> futures, 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:
      NullPointerException - if executor, futures or f is null.
    • reduce

      static <T> Future<T> reduce(Executor executor, Iterable<? extends Future<? extends T>> futures, 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:
      NullPointerException - if executor, futures or f is null.
    • run

      static Future<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:
      NullPointerException - if unit is null.
    • run

      static Future<Void> run(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:
      NullPointerException - if one of executor or unit is null.
    • sequence

      static <T> Future<Seq<T>> sequence(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:
      NullPointerException - if futures is null.
    • sequence

      static <T> Future<Seq<T>> sequence(Executor executor, 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:
      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(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:
      NullPointerException - if executor is null
    • toCompletableFuture

      @GwtIncompatible default 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(Iterable<? extends T> values, 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:
      NullPointerException - if values or f is null.
    • traverse

      static <T, U> Future<Seq<U>> traverse(Executor executor, Iterable<? extends T> values, 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:
      NullPointerException - if executor, values or f is null.
    • andThen

      default Future<T> andThen(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:
      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, 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:
      IllegalArgumentException - if timeout is negative
      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:
      SecurityException - if the current thread cannot modify the Future's thread
      See Also:
    • 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:
      SecurityException - if the current thread cannot modify the Future's thread
      See Also:
    • 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:
      NullPointerException - if partialFunction is null
    • executor

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

      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:
      UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.
    • failed

      default Future<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:
      NullPointerException - if that is null
    • filter

      default Future<T> filter(Predicate<? super T> predicate)
      Shortcut for filterTry(predicate::test.
      Parameters:
      predicate - A predicate
      Returns:
      A new Future
      Throws:
      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:
      NullPointerException - if predicate is null
    • getCause

      default Option<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:
      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(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:
      NullPointerException - if action is null.
    • onFailure

      default Future<T> onFailure(Consumer<? super 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:
      NullPointerException - if action is null.
    • onSuccess

      default Future<T> onSuccess(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:
      NullPointerException - if action is null.
    • recover

      default Future<T> recover(Function<? super 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:
      NullPointerException - if f is null
    • recoverWith

      default Future<T> recoverWith(Function<? super 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:
      NullPointerException - if f is null
    • transform

      default <U> U transform(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:
      NullPointerException - if f is null
    • transformValue

      default <U> Future<U> transformValue(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:
      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:
      NullPointerException - if that is null
    • zipWith

      default <U, R> Future<R> zipWith(Future<? extends U> that, 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:
      NullPointerException - if that is null
    • flatMap

      default <U> Future<U> flatMap(Function<? super T,? extends Future<? extends U>> mapper)
    • flatMapTry

      default <U> Future<U> flatMapTry(CheckedFunction1<? super T,? extends Future<? extends U>> mapper)
    • forEach

      default void forEach(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 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 Iterable<T>
      Specified by:
      iterator in interface Value<T>
      Returns:
      A new Iterator
    • map

      default <U> Future<U> map(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
    • mapTry

      default <U> Future<U> mapTry(CheckedFunction1<? super T,? extends U> mapper)
    • orElse

      default Future<T> orElse(Future<? extends T> other)
    • orElse

      default Future<T> orElse(Supplier<? extends Future<? extends T>> supplier)
    • peek

      default Future<T> peek(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 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.