Interface Future<T>

Type Parameters:

T - the type of the computation result

All Superinterfaces:

Iterable<T>, Value<T>

All Known Implementing Classes:

FutureImpl

public interface Future<T>
extends Value<T>

Represents the result of an asynchronous computation that becomes available at some point in the future. All operations provided by this Future are non-blocking.

The underlying Executor is used to execute asynchronous handlers, for example via onComplete(...).

A Future has two states:

• Pending: The computation is ongoing. Only a pending future may be completed or cancelled.
• Completed: The computation has finished, either successfully with a result, with an exception, or via cancellation.

Callbacks may be registered on a Future at any time. These callbacks are executed as soon as the Future completes. If a callback is registered on a completed Future, it is executed immediately. Execution may occur on a separate thread, depending on the underlying Executor. Callbacks registered on a cancelled Future are executed with the failed result.

Field Summary

Fields

Modifier and Type	Field	Description
static final Executor	DEFAULT_EXECUTOR	The default executor is ForkJoinPool.commonPool().

Method Summary

Modifier and Type	Method	Description
default Future<T>	andThen(@NonNull Consumer<? super Try<T>> action)	Supports chaining of callbacks that are guaranteed to be executed in order.
Future<T>	await()	Blocks the current thread until this Future is completed, or returns immediately if it is already completed.
Future<T>	await(long timeout, TimeUnit unit)	Blocks the current thread until this Future is completed, or returns immediately if it is already completed.
default boolean	cancel()	Cancels this Future.
boolean	cancel(boolean mayInterruptIfRunning)	Cancels this Future.
default <R> Future<R>	collect(@NonNull PartialFunction<? super T, ? extends R> partialFunction)	Applies a partialFunction to the value of this Future, collecting results only for values where the function is defined.
default Executor	executor()	Returns the Executor that executes asynchronous handlers for this Future.
ExecutorService	executorService()	Deprecated. Removed starting with Vavr 0.10.0, use executor() instead.
default Future<Throwable>	failed()	Returns a projection that inverts the result of this Future.
static <T> Future<T>	failed(@NonNull Throwable exception)	Creates a failed Future with the given exception, using the DEFAULT_EXECUTOR to execute callbacks.
static <T> Future<T>	failed(@NonNull Executor executor, @NonNull Throwable exception)	Creates a failed Future with the given exception, executing callbacks using the specified Executor.
default Future<T>	fallbackTo(@NonNull Future<? extends T> that)	Returns a Future that yields the result of this Future if it succeeds.
default Future<T>	filter(@NonNull Predicate<? super T> predicate)	Shortcut for filterTry(predicate::test), filtering the result of this Future using the given predicate.
default Future<T>	filterTry(@NonNull CheckedPredicate<? super T> predicate)	Filters the result of this Future using the given CheckedPredicate, delegating to Try.filterTry(CheckedPredicate).
static <T> Future<Option<T>>	find(@NonNull Iterable<? extends Future<? extends T>> futures, @NonNull Predicate<? super T> predicate)	Returns a Future that completes with the first result of the given futures that satisfies the specified predicate.
static <T> Future<Option<T>>	find(@NonNull Executor executor, @NonNull Iterable<? extends Future<? extends T>> futures, @NonNull Predicate<? super T> predicate)	Returns a Future that completes with the first result of the given futures that satisfies the specified predicate.
static <T> Future<T>	firstCompletedOf(@NonNull Iterable<? extends Future<? extends T>> futures)	Returns a new Future that completes with the result of the first future in the given iterable that completes, using the DEFAULT_EXECUTOR.
static <T> Future<T>	firstCompletedOf(@NonNull Executor executor, @NonNull Iterable<? extends Future<? extends T>> futures)	Returns a new Future that completes with the result of the first future in the given iterable that completes, using the specified Executor.
default <U> Future<U>	flatMap(@NonNull Function<? super T, ? extends Future<? extends U>> mapper)	Transforms the value of this Future using the given Function if it completes successfully, or returns a Future with the failure if this Future fails.
default <U> Future<U>	flatMapTry(@NonNull CheckedFunction1<? super T, ? extends Future<? extends U>> mapper)	Transforms the value of this Future using the given CheckedFunction1 if it completes successfully, or returns a Future with the failure if this Future fails.
static <T,U> Future<U>	fold(@NonNull Iterable<? extends Future<? extends T>> futures, U zero, @NonNull BiFunction<? super U, ? super T, ? extends U> f)	Returns a Future that contains the result of folding the given future values.
static <T,U> Future<U>	fold(@NonNull Executor executor, @NonNull Iterable<? extends Future<? extends T>> futures, U zero, @NonNull BiFunction<? super U, ? super T, ? extends U> f)	Returns a Future containing the result of folding the given future values.
default void	forEach(@NonNull Consumer<? super T> action)	Performs the given action asynchronously when this Future completes successfully.
static <T> Future<T>	fromCompletableFuture(@NonNull CompletableFuture<T> future)	Creates a Future that wraps the given CompletableFuture, using the DEFAULT_EXECUTOR for executing callbacks.
static <T> Future<T>	fromCompletableFuture(@NonNull Executor executor, @NonNull CompletableFuture<T> future)	Creates a Future that wraps the given CompletableFuture, executing callbacks using the specified Executor.
static <T> Future<T>	fromJavaFuture(@NonNull Executor executor, @NonNull Future<T> future)	Creates a Future that wraps the given Future, executing callbacks using the specified Executor.
static <T> Future<T>	fromJavaFuture(@NonNull Future<T> future)	Creates a Future that wraps the given Future, executing callbacks on the DEFAULT_EXECUTOR.
static <T> Future<T>	fromTry(@NonNull Try<? extends T> result)	Creates a Future from a Try, using the DEFAULT_EXECUTOR.
static <T> Future<T>	fromTry(@NonNull Executor executor, @NonNull Try<? extends T> result)	Creates a Future from a Try, executing callbacks using the specified Executor.
default T	get()	Returns the value of this Future if it completed successfully, or throws the underlying exception if it completed with a failure.
default Option<Throwable>	getCause()	Returns the underlying exception.
Option<Try<T>>	getValue()	Returns the value of this Future.
default boolean	isAsync()	A Futures's value is computed asynchronously.
boolean	isCancelled()	Checks whether this Future was cancelled, i.e., its computation was interrupted before completion.
boolean	isCompleted()	Checks whether this Future is completed, i.e., whether it has finished with a value, failed, or was cancelled.
default boolean	isEmpty()	Checks, if this future has a value.
default boolean	isFailure()	Checks whether 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 whether this Future completed successfully.
default @NonNull Iterator<T>	iterator()	Returns a rich io.vavr.collection.Iterator.
default <U> Future<U>	map(@NonNull Function<? super T, ? extends U> mapper)	Maps the underlying value to a different component type.
default <U> Future<U>	mapTo(U value)	Maps the underlying value to another fixed value.
default Future<Void>	mapToVoid()	Maps the underlying value to Void
default <U> Future<U>	mapTry(@NonNull CheckedFunction1<? super T, ? extends U> mapper)	Maps the value of this Future to a new value using the given CheckedFunction1 if it completes successfully.
static <T> Future<T>	narrow(Future<? extends T> future)	Narrows a Future<? extends T> to Future<T> via a type-safe cast.
static <T> Future<T>	of(@NonNull CheckedFunction0<? extends T> computation)	Starts an asynchronous computation using the DEFAULT_EXECUTOR.
static <T> Future<T>	of(@NonNull Executor executor, @NonNull CheckedFunction0<? extends T> computation)	Starts an asynchronous computation using the specified Executor.
Future<T>	onComplete(@NonNull Consumer<? super Try<T>> action)	Performs the given action once this Future is complete.
default Future<T>	onFailure(@NonNull Consumer<? super Throwable> action)	Performs the given action once this Future is complete and its result is a Try.Failure.
default Future<T>	onSuccess(@NonNull Consumer<? super T> action)	Performs the given action once this Future is complete and its result is a Try.Success.
default Future<T>	orElse(@NonNull Future<? extends T> other)	Returns this Future if it completes successfully, or the given alternative Future if this Future fails.
default Future<T>	orElse(@NonNull Supplier<? extends Future<? extends T>> supplier)	Returns this Future if it completes successfully, or a Future supplied by the given Supplier if this Future fails.
default Future<T>	peek(@NonNull Consumer<? super T> action)	Performs the given action on the first element if this is an eager implementation.
default Future<T>	recover(@NonNull Function<? super Throwable, ? extends T> f)	Handles a failure of this Future by mapping the exception to a new result.
default Future<T>	recoverWith(@NonNull Function<? super Throwable, ? extends Future<? extends T>> f)	Handles a failure of this Future by returning the result of another Future.
static <T> Future<T>	reduce(@NonNull Iterable<? extends Future<? extends T>> futures, @NonNull BiFunction<? super T, ? super T, ? extends T> f)	Returns a Future containing the result of reducing the given future values.
static <T> Future<T>	reduce(@NonNull Executor executor, @NonNull Iterable<? extends Future<? extends T>> futures, @NonNull BiFunction<? super T, ? super T, ? extends T> f)	Returns a Future containing the result of reducing the given future values.
static Future<Void>	run(@NonNull CheckedRunnable unit)	Runs an asynchronous computation using the DEFAULT_EXECUTOR.
static Future<Void>	run(@NonNull Executor executor, @NonNull CheckedRunnable unit)	Starts an asynchronous computation using the specified Executor.
static <T> Future<Seq<T>>	sequence(@NonNull Iterable<? extends Future<? extends T>> futures)	Reduces multiple Future instances into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
static <T> Future<Seq<T>>	sequence(@NonNull Executor executor, @NonNull Iterable<? extends Future<? extends T>> futures)	Reduces multiple Future instances into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.
default String	stringPrefix()	Returns the name of this Value type, which is used by toString().
static <T> Future<T>	successful(@NonNull Executor executor, T result)	Creates a succeeded Future with the given result, executing callbacks using the specified Executor.
static <T> Future<T>	successful(T result)	Creates a succeeded Future with the given result, using the DEFAULT_EXECUTOR to execute callbacks.
default CompletableFuture<T>	toCompletableFuture()	Converts this to a CompletableFuture
default <U> U	transform(@NonNull Function<? super Future<T>, ? extends U> f)	Transforms the result of this Future using the given function.
default <U> Future<U>	transformValue(@NonNull Function<? super Try<T>, ? extends Try<? extends U>> f)	Transforms the value of this Future, regardless of whether it completed successfully or with a failure.
static <T,U> Future<Seq<U>>	traverse(@NonNull Iterable<? extends T> values, @NonNull Function<? super T, ? extends Future<? extends U>> mapper)	Maps the values of an iterable in parallel to a sequence of mapped values, producing a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
static <T,U> Future<Seq<U>>	traverse(@NonNull Executor executor, @NonNull Iterable<? extends T> values, @NonNull Function<? super T, ? extends Future<? extends U>> mapper)	Maps the values of an iterable in parallel to a sequence of mapped values, producing a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.
default <U> Future<Tuple2<T,U>>	zip(@NonNull Future<? extends U> that)	Combines this Future with another Future, returning a Future of a tuple of both results.
default <U,R> Future<R>	zipWith(@NonNull Future<? extends U> that, @NonNull BiFunction<? super T, ? super U, ? extends R> combinator)	Combines this Future with another Future using the given combinator function.

Methods inherited from interface Value

collect, collect, contains, corresponds, eq, equals, exists, forAll, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, hashCode, out, out, spliterator, stderr, stdout, toArray, toCharSeq, toEither, toEither, toInvalid, toInvalid, toJavaArray, toJavaArray, toJavaArray, toJavaCollection, toJavaList, toJavaList, toJavaMap, toJavaMap, toJavaMap, toJavaOptional, toJavaParallelStream, toJavaSet, toJavaSet, toJavaStream, toLeft, toLeft, toLinkedMap, toLinkedMap, toLinkedSet, toList, toMap, toMap, toOption, toPriorityQueue, toPriorityQueue, toQueue, toRight, toRight, toSet, toSortedMap, toSortedMap, toSortedMap, toSortedMap, toSortedSet, toSortedSet, toStream, toString, toTree, toTree, toTry, toTry, toValid, toValid, toValidation, toValidation, toVector

Field Details

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:

• ForkJoinPool.awaitQuiescence(long, TimeUnit)

Method Details

failed

static <T> Future<T> failed(@NonNull Throwable exception)

Creates a failed Future with the given exception, using the DEFAULT_EXECUTOR to execute callbacks.

Type Parameters:

T - the type of a successful result

Parameters:

exception - the exception that caused the failure

Returns:

a failed Future containing the given exception

Throws:

NullPointerException - if exception is null

failed

static <T> Future<T> failed(@NonNull Executor executor,
 @NonNull Throwable exception)

Creates a failed Future with the given exception, executing callbacks using the specified Executor.

Type Parameters:

T - the type of a successful result

Parameters:

executor - the Executor to run asynchronous handlers

exception - the exception that caused the failure

Returns:

a failed Future containing the given exception

Throws:

NullPointerException - if executor or exception is null

find

static <T> Future<Option<T>> find(@NonNull Iterable<? extends Future<? extends T>> futures,
 @NonNull Predicate<? super T> predicate)

Returns a Future that completes with the first result of the given futures that satisfies the specified predicate. If no result matches, the Future will contain Option.None.

The returned Future uses the DEFAULT_EXECUTOR to execute callbacks.

Type Parameters:

T - the type of the future results

Parameters:

futures - an iterable of futures to inspect

predicate - a predicate to test successful future results

Returns:

a Future of an Option containing the first matching result, or Option.None if none match

Throws:

NullPointerException - if futures or predicate is null

find

static <T> Future<Option<T>> find(@NonNull Executor executor,
 @NonNull Iterable<? extends Future<? extends T>> futures,
 @NonNull Predicate<? super T> predicate)

Returns a Future that completes with the first result of the given futures that satisfies the specified predicate. If no result matches, the Future will contain Option.None.

The returned Future executes using the provided Executor.

Type Parameters:

T - the type of the future results

Parameters:

executor - the Executor to run asynchronous handlers

futures - an iterable of futures to inspect

predicate - a predicate to test successful future results

Returns:

a Future of an Option containing the first matching result, or Option.None if none match

Throws:

NullPointerException - if any argument is null

firstCompletedOf

static <T> Future<T> firstCompletedOf(@NonNull Iterable<? extends Future<? extends T>> futures)

Returns a new Future that completes with the result of the first future in the given iterable that completes, using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of the future results

Parameters:

futures - an iterable of futures to observe

Returns:

a new Future containing the result of the first completed future

Throws:

NullPointerException - if futures is null

firstCompletedOf

static <T> Future<T> firstCompletedOf(@NonNull Executor executor,
 @NonNull Iterable<? extends Future<? extends T>> futures)

Returns a new Future that completes with the result of the first future in the given iterable that completes, using the specified Executor.

Type Parameters:

T - the type of the future results

Parameters:

executor - the Executor to run asynchronous handlers

futures - an iterable of futures to observe

Returns:

a new Future containing the result of the first completed future

Throws:

NullPointerException - if executor or futures is null

fold

static <T,U> Future<U> fold(@NonNull Iterable<? extends Future<? extends T>> futures,
 U zero,
 @NonNull BiFunction<? super U, ? super T, ? extends U> f)

Returns a Future that contains the result of folding the given future values. If any future fails or the fold operation throws an exception, the resulting Future will also fail.

The resulting Future executes using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of the values in the given futures

U - the result type of the fold

Parameters:

futures - an iterable of futures to fold

zero - the initial value for the fold

f - the fold operation

Returns:

a new Future containing the fold result

Throws:

NullPointerException - if futures or f is null

fold

static <T,U> Future<U> fold(@NonNull Executor executor,
 @NonNull Iterable<? extends Future<? extends T>> futures,
 U zero,
 @NonNull BiFunction<? super U, ? super T, ? extends U> f)

Returns a Future containing the result of folding the given future values. If any future fails or the fold operation throws an exception, the resulting Future will also fail.

The resulting Future executes using the specified Executor.

Type Parameters:

T - the type of the values in the given futures

U - the result type of the fold

Parameters:

executor - the Executor to run asynchronous handlers

futures - an iterable of futures to fold

zero - the initial value for the fold

f - the fold operation

Returns:

a new Future containing the fold result

Throws:

NullPointerException - if executor, futures, or f is null

fromJavaFuture

static <T> Future<T> fromJavaFuture(@NonNull Future<T> future)

Creates a Future that wraps the given Future, executing callbacks on the DEFAULT_EXECUTOR.

Type Parameters:

T - the result type of the future

Parameters:

future - the Future to wrap

Returns:

a new Future containing the result of the given Java future

Throws:

NullPointerException - if future is null

fromJavaFuture

static <T> Future<T> fromJavaFuture(@NonNull Executor executor,
 @NonNull Future<T> future)

Creates a Future that wraps the given Future, executing callbacks using the specified Executor.

Type Parameters:

T - the result type of the future

Parameters:

executor - the Executor to run asynchronous handlers

future - the Future to wrap

Returns:

a new Future containing the result of the given Java future

Throws:

NullPointerException - if executor or future is null

fromCompletableFuture

@GwtIncompatible
static <T> Future<T> fromCompletableFuture(@NonNull CompletableFuture<T> future)

Creates a Future that wraps the given CompletableFuture, using the DEFAULT_EXECUTOR for executing callbacks.

Type Parameters:

T - the result type of the future

Parameters:

future - the CompletableFuture to wrap

Returns:

a new Future containing the result of the given CompletableFuture

Throws:

NullPointerException - if future is null

fromCompletableFuture

@GwtIncompatible
static <T> Future<T> fromCompletableFuture(@NonNull Executor executor,
 @NonNull CompletableFuture<T> future)

Creates a Future that wraps the given CompletableFuture, executing callbacks using the specified Executor.

Type Parameters:

T - the result type of the future

Parameters:

executor - the Executor to run asynchronous handlers

future - the CompletableFuture to wrap

Returns:

a new Future containing the result of the given CompletableFuture

Throws:

NullPointerException - if executor or future is null

fromTry

static <T> Future<T> fromTry(@NonNull Try<? extends T> result)

Creates a Future from a Try, using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of a successful result

Parameters:

result - the Try result to wrap

Returns:

a completed Future containing either a Success or a Failure

Throws:

NullPointerException - if result is null

fromTry

static <T> Future<T> fromTry(@NonNull Executor executor,
 @NonNull Try<? extends T> result)

Creates a Future from a Try, executing callbacks using the specified Executor.

Type Parameters:

T - the type of successful result

Parameters:

executor - the Executor to run asynchronous handlers

result - the Try result to wrap

Returns:

a completed Future containing 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 Future<? extends T> to Future<T> via a type-safe cast. This is safe because immutable or read-only collections are covariant.

Type Parameters:

T - the type of the value contained in the future

Parameters:

future - the Future to narrow

Returns:

the given future instance as a Future<T>

of

static <T> Future<T> of(@NonNull CheckedFunction0<? extends T> computation)

Starts an asynchronous computation using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of the computation result

Parameters:

computation - the computation to execute asynchronously

Returns:

a new Future containing the result of the computation

Throws:

NullPointerException - if computation is null

of

static <T> Future<T> of(@NonNull Executor executor,
 @NonNull CheckedFunction0<? extends T> computation)

Starts an asynchronous computation using the specified Executor.

Type Parameters:

T - the type of the computation result

Parameters:

executor - the Executor to run asynchronous handlers

computation - the computation to execute asynchronously

Returns:

a new Future containing the result of the computation

Throws:

NullPointerException - if executor or computation is null

reduce

static <T> Future<T> reduce(@NonNull Iterable<? extends Future<? extends T>> futures,
 @NonNull BiFunction<? super T, ? super T, ? extends T> f)

Returns a Future containing the result of reducing the given future values. The first completed future serves as the initial (zero) value. If any future or the reduce operation fails, the resulting Future will also fail.

The resulting Future executes using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of the values in the given futures

Parameters:

futures - an iterable of futures to reduce

f - the reduce operation

Returns:

a new Future containing the reduce result

Throws:

NullPointerException - if futures or f is null

reduce

static <T> Future<T> reduce(@NonNull Executor executor,
 @NonNull Iterable<? extends Future<? extends T>> futures,
 @NonNull BiFunction<? super T, ? super T, ? extends T> f)

Returns a Future containing the result of reducing the given future values. The first completed future serves as the initial (zero) value. If any future or the reduce operation fails, the resulting Future will also fail.

The resulting Future executes using the specified Executor.

Type Parameters:

T - the type of the values in the given futures

Parameters:

executor - the Executor to run asynchronous handlers

futures - an iterable of futures to reduce

f - the reduce operation

Returns:

a new Future containing the reduce result

Throws:

NullPointerException - if executor, futures, or f is null

run

static Future<Void> run(@NonNull CheckedRunnable unit)

Runs an asynchronous computation using the DEFAULT_EXECUTOR.

Parameters:

unit - a unit of work to execute asynchronously

Returns:

a new Future representing the completion of the computation, with no result

Throws:

NullPointerException - if unit is null

run

static Future<Void> run(@NonNull Executor executor,
 @NonNull CheckedRunnable unit)

Starts an asynchronous computation using the specified Executor.

Parameters:

executor - the Executor to run asynchronous handlers

unit - a unit of work to execute asynchronously

Returns:

a new Future representing the completion of the computation, with no result

Throws:

NullPointerException - if executor or unit is null

sequence

static <T> Future<Seq<T>> sequence(@NonNull Iterable<? extends Future<? extends T>> futures)

Reduces multiple Future instances into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

The resulting Future executes using the DEFAULT_EXECUTOR.

• If all given futures succeed, the resulting future also succeeds:

  // = Future(Success(Seq(1, 2)))
  sequence(
      List.of(
          Future.of(() -> 1),
          Future.of(() -> 2)
      )
  );
          

• If any given future fails, the resulting future fails as well:

  // = Future(Failure(Error))
  sequence(
      List.of(
          Future.of(() -> 1),
          Future.of(() -> { throw new Error(); })
      )
  );
          

Type Parameters:

T - the result type of the futures

Parameters:

futures - an Iterable of Futures

Returns:

a Future containing a Seq of results

Throws:

NullPointerException - if futures is null

sequence

static <T> Future<Seq<T>> sequence(@NonNull Executor executor,
 @NonNull Iterable<? extends Future<? extends T>> futures)

Reduces multiple Future instances into a single Future by transforming an Iterable<Future<? extends T>> into a Future<Seq<T>>.

The resulting Future executes using the specified Executor.

Type Parameters:

T - the result type of the futures

Parameters:

executor - the Executor to run asynchronous handlers

futures - an Iterable of Futures to reduce

Returns:

a Future containing a Seq of results

Throws:

NullPointerException - if executor or futures is null

successful

static <T> Future<T> successful(T result)

Creates a succeeded Future with the given result, using the DEFAULT_EXECUTOR to execute callbacks.

Type Parameters:

T - the type of the result

Parameters:

result - the successful result

Returns:

a succeeded Future containing the given result

successful

static <T> Future<T> successful(@NonNull Executor executor,
 T result)

Creates a succeeded Future with the given result, executing callbacks using the specified Executor.

Type Parameters:

T - the type of the result

Parameters:

executor - the Executor to run asynchronous handlers

result - the successful result

Returns:

a succeeded Future containing the given result

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(@NonNull Iterable<? extends T> values,
 @NonNull Function<? super T, ? extends Future<? extends U>> mapper)

Maps the values of an iterable in parallel to a sequence of mapped values, producing a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

The resulting Future executes using the DEFAULT_EXECUTOR.

Type Parameters:

T - the type of the input values

U - the type of the mapped values

Parameters:

values - an Iterable of input values

mapper - a function mapping values to Futures

Returns:

a Future containing a Seq of mapped results

Throws:

NullPointerException - if values or mapper is null

traverse

static <T,U> Future<Seq<U>> traverse(@NonNull Executor executor,
 @NonNull Iterable<? extends T> values,
 @NonNull Function<? super T, ? extends Future<? extends U>> mapper)

Maps the values of an iterable in parallel to a sequence of mapped values, producing a single Future by transforming an Iterable<? extends T> into a Future<Seq<U>>.

The resulting Future executes using the specified Executor.

Type Parameters:

T - the type of the input values

U - the type of the mapped values

Parameters:

executor - the Executor to run asynchronous handlers

values - an Iterable of input values

mapper - a function mapping values to Futures

Returns:

a Future containing a Seq of mapped results

Throws:

NullPointerException - if executor, values, or mapper is null

andThen

default Future<T> andThen(@NonNull Consumer<? super Try<T>> action)

Supports chaining of callbacks that are guaranteed to be executed in order.

Exceptions thrown by the given action are not propagated. Subsequent actions are executed 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 to perform after the future completes

Returns:

a new Future containing the original result, completed after the action executes

Throws:

NullPointerException - if action is null

await

Future<T> await()

Blocks the current thread until this Future is completed, or returns immediately if it is already completed.

If the current thread is 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 is completed, or returns immediately if it is already completed.

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

If the specified timeout is reached before completion, 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 this Future. If it is running, the executing thread is interrupted.

If the future is successfully cancelled, its result becomes a Failure(CancellationException).

Returns:

false if this Future is already completed or could not be cancelled, true otherwise

Throws:

SecurityException - if the current thread is not permitted to modify the Future's thread

See Also:

• isCancelled()

cancel

boolean cancel(boolean mayInterruptIfRunning)

Cancels this Future. A pending future may be interrupted depending on the underlying Executor.

If the future is successfully cancelled, its result becomes a Failure(CancellationException).

Parameters:

mayInterruptIfRunning - true if a running thread should be interrupted; false allows it to complete

Returns:

false if this Future is already completed or could not be cancelled, true otherwise

Throws:

SecurityException - if the current thread is not permitted to modify the Future's thread

See Also:

• isCancelled()
• Future.cancel(boolean)

collect

default <R> Future<R> collect(@NonNull PartialFunction<? super T, ? extends R> partialFunction)

Applies a partialFunction to the value of this Future, collecting results only for values where the function is defined. The mapped result is wrapped in a new Future.

Example:

if (partialFunction.isDefinedAt(value)) {
    R newValue = partialFunction.apply(value);
}

Type Parameters:

R - the type of the mapped result

Parameters:

partialFunction - a function that may not be defined for every value of this future

Returns:

a new Future containing the mapped value

Throws:

NullPointerException - if partialFunction is null

executor

default Executor executor()

Returns the Executor that executes asynchronous handlers for this Future.

Returns:

the underlying Executor

executorService

@Deprecated
ExecutorService executorService()
                         throws 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:

UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.

failed

default Future<Throwable> failed()

Returns a projection that inverts the result of this Future.

If this Future succeeds, the resulting failed projection contains a NoSuchElementException.

If this Future fails, the resulting failed projection succeeds with the exception as its value.

Returns:

a new Future representing the inverted result

fallbackTo

default Future<T> fallbackTo(@NonNull Future<? extends T> that)

Returns a Future that yields the result of this Future if it succeeds. If this Future fails, the result of the given that Future is returned if it succeeds. 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 Success(1)
result.onComplete(System.out::println);

Parameters:

that - a fallback Future to use if this one fails

Returns:

a new Future representing the result or fallback

Throws:

NullPointerException - if that is null

filter

default Future<T> filter(@NonNull Predicate<? super T> predicate)

Shortcut for filterTry(predicate::test), filtering the result of this Future using the given predicate.

Parameters:

predicate - a predicate to test the value of the future

Returns:

a new Future containing the value if the predicate passes, or a failure otherwise

Throws:

NullPointerException - if predicate is null

filterTry

default Future<T> filterTry(@NonNull CheckedPredicate<? super T> predicate)

Filters the result of this Future using the given CheckedPredicate, delegating to Try.filterTry(CheckedPredicate).

Parameters:

predicate - a checked predicate to test the value of the future

Returns:

a new Future containing the value if the predicate passes, or a failure otherwise

Throws:

NullPointerException - if predicate is null

getCause

default Option<Throwable> getCause()

Returns the underlying exception. This is syntactic sugar for future.getValue().map(Try::getCause).

Returns:

None if the Future is not yet completed, or Some(Throwable) if it completed with a failure

Throws:

UnsupportedOperationException - if the Future completed successfully with a value

getValue

Option<Try<T>> getValue()

Returns the value of this Future.

Returns:

None if the Future is not yet completed or was cancelled; otherwise, Some(Try) containing the result or failure

isCancelled

boolean isCancelled()

Checks whether this Future was cancelled, i.e., its computation was interrupted before completion.

Returns:

true if the computation was cancelled, false otherwise

isCompleted

boolean isCompleted()

Checks whether this Future is completed, i.e., whether it has finished with a value, failed, or was cancelled.

Returns:

true if the computation has completed in any state, false otherwise

isSuccess

default boolean isSuccess()

Checks whether this Future completed successfully.

Returns:

true if this Future has completed with a successful result, false otherwise

isFailure

default boolean isFailure()

Checks whether this Future completed with a failure.

Returns:

true if this Future has completed with a failure, false otherwise

onComplete

Future<T> onComplete(@NonNull Consumer<? super Try<T>> action)

Performs the given action once this Future is complete.

Parameters:

action - an action to execute when the future completes

Returns:

this Future

Throws:

NullPointerException - if action is null

onFailure

default Future<T> onFailure(@NonNull Consumer<? super Throwable> action)

Performs the given action once this Future is complete and its result is a Try.Failure.

Note that a cancelled Future is also considered a failure.

Parameters:

action - an action to execute when this future fails

Returns:

this Future

Throws:

NullPointerException - if action is null

onSuccess

default Future<T> onSuccess(@NonNull Consumer<? super T> action)

Performs the given action once this Future is complete and its result is a Try.Success.

Parameters:

action - an action to execute when this future succeeds

Returns:

this Future

Throws:

NullPointerException - if action is null

recover

default Future<T> recover(@NonNull Function<? super Throwable, ? extends T> f)

Handles a failure of this Future by mapping the exception to a new result.

Example:

// = "oh!"
Future.of(() -> { throw new Error("oh!"); })
      .recover(Throwable::getMessage);

Parameters:

f - a function that maps the failure exception to a new value

Returns:

a new Future containing either the original success or the recovered value

Throws:

NullPointerException - if f is null

recoverWith

default Future<T> recoverWith(@NonNull 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(ex -> Future.of(() -> ex.getMessage()));

Parameters:

f - a function that maps the failure exception to a new Future

Returns:

a new Future containing either the original success or the result of the recovered Future

Throws:

NullPointerException - if f is null

transform

default <U> U transform(@NonNull Function<? super Future<T>, ? extends U> f)

Transforms the result of this Future using the given function.

Type Parameters:

U - the type of the transformed result

Parameters:

f - a function to transform the result

Returns:

a new Future containing the transformed result

Throws:

NullPointerException - if f is null

transformValue

default <U> Future<U> transformValue(@NonNull Function<? super Try<T>, ? extends Try<? extends U>> f)

Transforms the value of this Future, regardless of whether it completed successfully or with a failure.

Type Parameters:

U - the type of the transformed Try result

Parameters:

f - a function to transform the Try result

Returns:

a new Future containing the transformed result

Throws:

NullPointerException - if f is null

zip

default <U> Future<Tuple2<T,U>> zip(@NonNull Future<? extends U> that)

Combines this Future with another Future, returning a Future of a tuple of both results.

If this Future fails, the resulting Future contains this failure. Otherwise, it contains the failure of that Future, or a tuple of both successful results if both succeed.

Type Parameters:

U - the result type of that

Parameters:

that - another Future to combine with

Returns:

a new Future containing either a failure or a tuple of both results

Throws:

NullPointerException - if that is null

zipWith

default <U,R> Future<R> zipWith(@NonNull Future<? extends U> that,
 @NonNull BiFunction<? super T, ? super U, ? extends R> combinator)

Combines this Future with another Future using the given combinator function.

If this Future fails, the resulting Future contains this failure. Otherwise, it contains the failure of that Future, or the result of applying the combinator function to both successful results.

Type Parameters:

U - the result type of that

R - the result type of the combined value

Parameters:

that - another Future to combine with

combinator - a function to combine the successful results of both futures

Returns:

a new Future containing either a failure or the combined result

Throws:

NullPointerException - if that or combinator is null

flatMap

default <U> Future<U> flatMap(@NonNull Function<? super T, ? extends Future<? extends U>> mapper)

Transforms the value of this Future using the given Function if it completes successfully, or returns a Future with the failure if this Future fails.

This is a shortcut for flatMapTry(CheckedFunction1).

Type Parameters:

U - the type of the resulting Future

Parameters:

mapper - a function mapping the value to another Future

Returns:

a new Future resulting from applying the mapper, or a Future with the failure if this Future fails

Throws:

NullPointerException - if mapper is null

flatMapTry

default <U> Future<U> flatMapTry(@NonNull CheckedFunction1<? super T, ? extends Future<? extends U>> mapper)

Transforms the value of this Future using the given CheckedFunction1 if it completes successfully, or returns a Future with the failure if this Future fails.

If applying the mapper throws an exception, a Future containing the exception is returned.

Type Parameters:

U - the type of the resulting Future

Parameters:

mapper - a checked function mapping the value to another Future

Returns:

a new Future resulting from applying the mapper, or a Future with the failure if this Future fails

Throws:

NullPointerException - if mapper is null

forEach

default void forEach(@NonNull Consumer<? super T> action)

Performs the given action asynchronously when this Future completes successfully.

The action is not executed if the Future completes with a failure.

Specified by:

forEach in interface Iterable<T>

Specified by:

forEach in interface Value<T>

Parameters:

action - a Consumer to be executed with the successful result

Throws:

NullPointerException - if action is null

get

default T get()

Returns the value of this Future if it completed successfully, or throws the underlying exception if it completed with a failure. Blocks the current thread if the computation is not yet finished.

Note: If the computation failed, the underlying Throwable cause is thrown.

Specified by:

get in interface Value<T>

Returns:

the successful result 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 @NonNull 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(@NonNull 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

mapTo

default <U> Future<U> mapTo(U value)

Description copied from interface: Value

Maps the underlying value to another fixed value.

Specified by:

mapTo in interface Value<T>

Type Parameters:

U - The new component type

Parameters:

value - value to replace the contents with

Returns:

A new value

mapToVoid

default Future<Void> mapToVoid()

Description copied from interface: Value

Maps the underlying value to Void

Specified by:

mapToVoid in interface Value<T>

Returns:

A new value of type Void

mapTry

default <U> Future<U> mapTry(@NonNull CheckedFunction1<? super T, ? extends U> mapper)

Maps the value of this Future to a new value using the given CheckedFunction1 if it completes successfully.

If applying the mapper throws an exception, a Future containing the exception is returned.

Example:

Future.of(() -> 0)
      .mapTry(x -> 1 / x); // division by zero will result in a failed Future

Type Parameters:

U - the type of the result

Parameters:

mapper - a checked function to apply to the value

Returns:

a new Future containing the mapped value if this Future completes successfully, otherwise a Future with the failure

Throws:

NullPointerException - if mapper is null

orElse

default Future<T> orElse(@NonNull Future<? extends T> other)

Returns this Future if it completes successfully, or the given alternative Future if this Future fails.

Parameters:

other - the alternative Future to return if this Future fails

Returns:

this Future if it completes successfully, otherwise other

Throws:

NullPointerException - if other is null

orElse

default Future<T> orElse(@NonNull Supplier<? extends Future<? extends T>> supplier)

Returns this Future if it completes successfully, or a Future supplied by the given Supplier if this Future fails.

The supplier is only invoked if this Future fails.

Parameters:

supplier - a supplier of an alternative Future

Returns:

this Future if it completes successfully, otherwise the Future returned by supplier

Throws:

NullPointerException - if supplier is null

peek

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