io.vavr.concurrent

Interface Future<T>

Type Parameters:

T - Type of the computation result.

All Superinterfaces:

Iterable<T>, Value<T>

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.

Author:

Daniel Dietrich

Field Summary

Fields

Modifier and Type	Field and Description
static Executor	DEFAULT_EXECUTOR The default executor is ForkJoinPool.commonPool().
static ExecutorService	DEFAULT_EXECUTOR_SERVICE Deprecated. Will be removed in Vavr 1.0. Use instead.

Method Summary

Modifier and Type	Method and Description
default Future<T>	andThen(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, 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 Executor	executor() Returns the Executor used by this Future.
ExecutorService	executorService() Deprecated. Removed starting with Vavr 0.10.0, use executor() instead.
default Future<Throwable>	failed() A projection that inverses the result of this Future.
static <T> Future<T>	failed(Executor executor, Throwable exception) Creates a failed Future with the given exception, backed by the given Executor.
static <T> Future<T>	failed(Throwable exception) Creates a failed Future with the given exception, backed by the DEFAULT_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(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(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.
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.
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.
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.
default <U> Future<U>	flatMap(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(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.
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.
default void	forEach(Consumer<? super T> action) Performs the given action asynchronously hence this Future result becomes available.
static <T> Future<T>	fromCompletableFuture(CompletableFuture<T> future) Creates a Future with the given CompletableFuture, backed by the DEFAULT_EXECUTOR
static <T> Future<T>	fromCompletableFuture(Executor executor, CompletableFuture<T> future) Creates a Future with the given CompletableFuture, backed by given Executor
static <T> Future<T>	fromJavaFuture(Executor executor, Future<T> future) Creates a Future with the given java.util.concurrent.Future, backed by given Executor
static <T> Future<T>	fromJavaFuture(Future<T> future) Creates a Future with the given java.util.concurrent.Future, backed by the DEFAULT_EXECUTOR
static <T> Future<T>	fromTry(Executor executor, Try<? extends T> result) Creates a Future from a Try, backed by the given Executor.
static <T> Future<T>	fromTry(Try<? extends T> result) Creates a Future from a Try, backed by the DEFAULT_EXECUTOR.
default T	get() Gets the value if the computation result is a Success or throws if it was a Failure.
default Option<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(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(Executor executor, CheckedFunction0<? extends T> computation) Starts an asynchronous computation, backed by the given Executor.
static <T> Future<T>	ofCallable(Callable<? extends T> computation) Deprecated. Will be removed. Use Future.of(callable::call) instead of Future.ofCallable(callable).
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).
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).
static <T> Future<T>	ofSupplier(Supplier<? extends T> computation) Deprecated. Will be removed. Use Future.of(supplier::get) instead of Future.ofSupplier(supplier).
Future<T>	onComplete(Consumer<? super Try<T>> action) Performs the action once the Future is complete.
default Future<T>	onFailure(Consumer<? super Throwable> action) Performs the action once the Future is complete and the result is a Try.Failure.
default Future<T>	onSuccess(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(Supplier<? extends Future<? extends T>> supplier)
default Future<T>	peek(Consumer<? super T> action) Performs the given action on the first element if this is an eager implementation.
default Future<T>	recover(Function<? super Throwable,? extends T> f) Handles a failure of this Future by returning another result.
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.
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.
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.
static Future<Void>	run(CheckedRunnable unit) Runs an asynchronous computation, backed by the DEFAULT_EXECUTOR.
static Future<Void>	run(Executor executor, CheckedRunnable unit) Starts an asynchronous computation, backed by the given Executor.
static <T> Future<T>	run(Executor executor, Task<? extends T> task) Deprecated. Experimental API
static <T> Future<T>	run(Task<? extends T> task) Deprecated. Experimental API
static Future<Void>	runRunnable(Executor executor, Runnable computation) Deprecated. Will be removed. Use Future.of(executor, runnable::run) instead of Future.runRunnable(executor, runnable).
static Future<Void>	runRunnable(Runnable computation) Deprecated. Will be removed. Use Future.of(runnable::run) instead of Future.runRunnable(runnable).
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>>.
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>>.
default String	stringPrefix() Returns the name of this Value type, which is used by toString().
static <T> Future<T>	successful(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 CompletableFuture<T>	toCompletableFuture() Converts this to a CompletableFuture
default <U> U	transform(Function<? super Future<T>,? extends U> f) Transforms this Future.
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.
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>>.
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>>.
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, BiFunction<? super T,? super U,? extends R> combinator) Returns a this and that Future result combined using a given combinator function.

Methods inherited from interface io.vavr.Value

collect, collect, contains, corresponds, eq, equals, exists, forAll, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, hashCode, narrow, 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 Detail

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:

ForkJoinPool.awaitQuiescence(long, TimeUnit)

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 Detail

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:

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:

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:

NullPointerException - if partialFunction is null

executor

default Executor executor()

Returns the Executor used by 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()

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.