Top Description Methods
io.vavr.concurrent

public Interface Promise<T>

Additional top-level class in compilation unit: PromiseImpl.

Known Direct Implementers
io.vavr.concurrent.PromiseImpl
Type Parameters
<T>
The result type of the underlying Future.
Imports
io.vavr.control.Try, java.util.Objects, java.util.concurrent.Executor, .ExecutorService, .ForkJoinPool
A Promise is a write-once wrapper around a read-only Future which can complete the underlying Future with a value or an exception.

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

Creation

Promise offers static factory methods to create new promises which hasn't been fulfilled yet:

And we may create new promises that are already finished: All the static factory methods mentioned above have additional versions which take an Executor as argument. This gives us more control over thread creation and thread pool sizes.

One-shot API

The main purpose of a Promise is to complete its underlying Future. When only a single Thread will eventually complete the Promise, we use one of these methods. Calls will throw if the Promise is already completed.

API for competing threads

When multiple Threads may complete our Promise, we typically use one of these methods. Calls will gracefully return false if the Promise is already completed.

Author
Daniel Dietrich

Method Summary

Modifier and TypeMethod and Description
public default Promise<T>

Returns:

This Promise.
complete(Try<? extends T>
Either a Try.Success containing the result or a Try.Failure containing an exception.
value)

Completes this Promise with the given value.

public default Promise<T>

Returns:

This Promise.
completeWith(Future<? extends T>
Another Future to react on.
other)

Completes this Promise with the given Future, once that Future is completed.

public default Executor

Returns:

The underlying Executor.
executor()

Returns the Executor used by the underlying Future of this Promise.

public ExecutorService

Returns:

(never)
executorService()
Deprecated Removed starting with Vavr 0.10.0, use executor() instead.

This method is deprecated.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A failed Promise.
failed(Throwable
The reason why it failed.
exception)

Creates a failed Promise, backed by the Future#DEFAULT_EXECUTOR.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A failed Promise.
failed(Executor
An Executor passed to the underlying Future.
executor, Throwable
The reason why it failed.
exception)

Creates a failed Promise, backed by the given Executor.

public default Promise<T>

Returns:

This Promise.
failure(Throwable
An exception.
exception)

Completes this Promise with the given exception.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A completed Promise which contains either a Success or a Failure.
fromTry(Try<? extends T>
The result.
result)

Creates a Promise from a Try, backed by the Future#DEFAULT_EXECUTOR.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A completed Promise which contains either a Success or a Failure.
fromTry(Executor
An Executor passed to the underlying Future.
executor, Try<? extends T>
The result.
result)

Creates a Promise from a Try, backed by the given Executor.

public Future<T>

Returns:

The Future.
future()

Returns the underlying Future of this Promise.

public default boolean

Returns:

true, if the computation successfully finished or failed, false otherwise.
isCompleted()

Checks if this Promise is completed, i.e. has a value.

public static <
Result type of the Promise.
T> Promise<T>

Returns:

A new Promise.
make()

Makes a Promise that isn't fulfilled yet, backed by the Future#DEFAULT_EXECUTOR.

public static <
Result type of the Promise.
T> Promise<T>

Returns:

A new Promise.
make(Executor
An Executor passed to the underlying Future.
executor)

Makes a Promise that isn't fulfilled yet, backed by the given Executor.

public static <
Component type of the Promise.
T> Promise<T>

Returns:

the given promise instance as narrowed type Promise<T>.
narrow(Promise<? extends T>
A Promise.
promise)

Narrows a widened Promise<?

public default Promise<T>

Returns:

This Promise.
success(T
A value.
value)

Completes this Promise with the given value.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A succeeded Promise.
successful(T
The result.
result)

Creates a succeeded Promise, backed by the Future#DEFAULT_EXECUTOR.

public static <
The value type of a successful result.
T> Promise<T>

Returns:

A succeeded Promise.
successful(Executor
An Executor passed to the underlying Future.
executor, T
The result.
result)

Creates a succeeded Promise, backed by the given Executor.

public boolean

Returns:

false if this Promise has already been completed, true otherwise.
tryComplete(Try<? extends T>
Either a Try.Success containing the result or a Try.Failure containing an exception.
value)

Attempts to completes this Promise with the given value.

public default Promise<T>

Returns:

This Promise.
tryCompleteWith(Future<? extends T>
Another Future to react on.
other)

Attempts to complete this Promise with the specified Future, once that Future is completed.

public default boolean

Returns:

false if this Promise has already been completed, true otherwise.
tryFailure(Throwable
An exception.
exception)

Completes this Promise with the given exception.

public default boolean

Returns:

false if this Promise has already been completed, true otherwise.
trySuccess(T
A value.
value)

Completes this Promise with the given value.

Method Detail

completeback to summary
public default Promise<T> complete(Try<? extends T> value)

Completes this Promise with the given value.

Parameters
value:Try<? extends T>

Either a Try.Success containing the result or a Try.Failure containing an exception.

Returns:Promise<T>

This Promise.

Exceptions
IllegalStateException:
if this Promise has already been completed.
completeWithback to summary
public default Promise<T> completeWith(Future<? extends T> other)

Completes this Promise with the given Future, once that Future is completed.

Parameters
other:Future<? extends T>

Another Future to react on.

Returns:Promise<T>

This Promise.

executorback to summary
public default Executor executor()

Returns the Executor used by the underlying Future of this Promise.

Returns:Executor

The underlying Executor.

executorServiceback to summary
public ExecutorService executorService()

Deprecated

Removed starting with Vavr 0.10.0, use executor() instead.

This method is deprecated.

THE DEFAULT IMPLEMENTATION (obtained by one of the Promise factory methods) MIGHT THROW AN UnsupportedOperationException AT RUNTIME, DEPENDING ON WHAT Future#executorService() returns.

Returns:ExecutorService

(never)

Annotations
@Deprecated
Exceptions
UnsupportedOperationException:
if the underlying Executor isn't an ExecutorService.
failedback to summary
public static <T> Promise<T> failed(Throwable exception)

Creates a failed Promise, backed by the Future#DEFAULT_EXECUTOR.

Parameters
<T>
The value type of a successful result.
exception:Throwable

The reason why it failed.

Returns:Promise<T>

A failed Promise.

Exceptions
NullPointerException:
if exception is null
failedback to summary
public static <T> Promise<T> failed(Executor executor, Throwable exception)

Creates a failed Promise, backed by the given Executor.

Parameters
<T>
The value type of a successful result.
executor:Executor

An Executor passed to the underlying Future.

exception:Throwable

The reason why it failed.

Returns:Promise<T>

A failed Promise.

Exceptions
NullPointerException:
if executor or exception is null
failureback to summary
public default Promise<T> failure(Throwable exception)

Completes this Promise with the given exception.

Parameters
exception:Throwable

An exception.

Returns:Promise<T>

This Promise.

Exceptions
IllegalStateException:
if this Promise has already been completed.
fromTryback to summary
public static <T> Promise<T> fromTry(Try<? extends T> result)

Creates a Promise from a Try, backed by the Future#DEFAULT_EXECUTOR.

Parameters
<T>
The value type of a successful result.
result:Try<? extends T>

The result.

Returns:Promise<T>

A completed Promise which contains either a Success or a Failure.

Exceptions
NullPointerException:
if result is null
fromTryback to summary
public static <T> Promise<T> fromTry(Executor executor, Try<? extends T> result)

Creates a Promise from a Try, backed by the given Executor.

Parameters
<T>
The value type of a successful result.
executor:Executor

An Executor passed to the underlying Future.

result:Try<? extends T>

The result.

Returns:Promise<T>

A completed Promise which contains either a Success or a Failure.

Exceptions
NullPointerException:
if executor or result is null
futureback to summary
public Future<T> future()

Returns the underlying Future of this Promise.

Returns:Future<T>

The Future.

isCompletedback to summary
public default boolean isCompleted()

Checks if this Promise is completed, i.e. has a value.

Returns:boolean

true, if the computation successfully finished or failed, false otherwise.

makeback to summary
public static <T> Promise<T> make()

Makes a Promise that isn't fulfilled yet, backed by the Future#DEFAULT_EXECUTOR. ForkJoinPool#commonPool().

Parameters
<T>
Result type of the Promise.
Returns:Promise<T>

A new Promise.

makeback to summary
public static <T> Promise<T> make(Executor executor)

Makes a Promise that isn't fulfilled yet, backed by the given Executor.

Parameters
<T>
Result type of the Promise.
executor:Executor

An Executor passed to the underlying Future.

Returns:Promise<T>

A new Promise.

Exceptions
NullPointerException:
if executor is null
narrowback to summary
public static <T> Promise<T> narrow(Promise<? extends T> promise)

Narrows a widened Promise<? extends T> to Promise<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.

Parameters
<T>
Component type of the Promise.
promise:Promise<? extends T>

A Promise.

Returns:Promise<T>

the given promise instance as narrowed type Promise<T>.

Annotations
@SuppressWarnings:unchecked
successback to summary
public default Promise<T> success(T value)

Completes this Promise with the given value.

Parameters
value:T

A value.

Returns:Promise<T>

This Promise.

Exceptions
IllegalStateException:
if this Promise has already been completed.
successfulback to summary
public static <T> Promise<T> successful(T result)

Creates a succeeded Promise, backed by the Future#DEFAULT_EXECUTOR.

Parameters
<T>
The value type of a successful result.
result:T

The result.

Returns:Promise<T>

A succeeded Promise.

successfulback to summary
public static <T> Promise<T> successful(Executor executor, T result)

Creates a succeeded Promise, backed by the given Executor.

Parameters
<T>
The value type of a successful result.
executor:Executor

An Executor passed to the underlying Future.

result:T

The result.

Returns:Promise<T>

A succeeded Promise.

Exceptions
NullPointerException:
if executor is null
tryCompleteback to summary
public boolean tryComplete(Try<? extends T> value)

Attempts to completes this Promise with the given value.

Parameters
value:Try<? extends T>

Either a Try.Success containing the result or a Try.Failure containing an exception.

Returns:boolean

false if this Promise has already been completed, true otherwise.

Exceptions
IllegalStateException:
if this Promise has already been completed.
tryCompleteWithback to summary
public default Promise<T> tryCompleteWith(Future<? extends T> other)

Attempts to complete this Promise with the specified Future, once that Future is completed.

Parameters
other:Future<? extends T>

Another Future to react on.

Returns:Promise<T>

This Promise.

tryFailureback to summary
public default boolean tryFailure(Throwable exception)

Completes this Promise with the given exception.

Parameters
exception:Throwable

An exception.

Returns:boolean

false if this Promise has already been completed, true otherwise.

trySuccessback to summary
public default boolean trySuccess(T value)

Completes this Promise with the given value.

Parameters
value:T

A value.

Returns:boolean

false if this Promise has already been completed, true otherwise.