Promise (vavr 1.0.0-alpha-4 API)

Type Parameters:

T - The result type of the underlying Future
```
public interface Promise<T>
```
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:
- create new promises: make()
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.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default Promise<T>`	`complete(Try<? extends T> value)` Completes this `Promise` with the given `value`.
`default Promise<T>`	`completeWith(Future<? extends T> other)` Completes this `Promise` with the given `Future`, once that `Future` is completed.
`default java.util.concurrent.Executor`	`executor()` Returns the `Executor` used by the underlying `Future` of this `Promise`.
`java.util.concurrent.ExecutorService`	`executorService()` Deprecated. Removed starting with Vavr 0.10.0, use `executor()` instead.
`static <T> Promise<T>`	`failed(java.util.concurrent.Executor executor, java.lang.Throwable exception)` Creates a failed `Promise`, backed by the given `Executor`.
`static <T> Promise<T>`	`failed(java.lang.Throwable exception)` Creates a failed `Promise`, backed by the `Future.DEFAULT_EXECUTOR`.
`default Promise<T>`	`failure(java.lang.Throwable exception)` Completes this `Promise` with the given `exception`.
`static <T> Promise<T>`	`fromTry(java.util.concurrent.Executor executor, Try<? extends T> result)` Creates a `Promise` from a `Try`, backed by the given `Executor`.
`static <T> Promise<T>`	`fromTry(Try<? extends T> result)` Creates a `Promise` from a `Try`, backed by the `Future.DEFAULT_EXECUTOR`.
`Future<T>`	`future()` Returns the underlying `Future` of this `Promise`.
`default boolean`	`isCompleted()` Checks if this `Promise` is completed, i.e.
`static <T> Promise<T>`	`make()` Makes a `Promise` that isn't fulfilled yet, backed by the `Future.DEFAULT_EXECUTOR`.
`static <T> Promise<T>`	`make(java.util.concurrent.Executor executor)` Makes a `Promise` that isn't fulfilled yet, backed by the given `Executor`.
`static <T> Promise<T>`	`narrow(Promise<? extends T> promise)` Narrows a widened `Promise<? extends T>` to `Promise<T>` by performing a type-safe cast.
`default Promise<T>`	`success(T value)` Completes this `Promise` with the given `value`.
`static <T> Promise<T>`	`successful(java.util.concurrent.Executor executor, T result)` Creates a succeeded `Promise`, backed by the given `Executor`.
`static <T> Promise<T>`	`successful(T result)` Creates a succeeded `Promise`, backed by the `Future.DEFAULT_EXECUTOR`.
`boolean`	`tryComplete(Try<? extends T> value)` Attempts to completes this `Promise` with the given `value`.
`default Promise<T>`	`tryCompleteWith(Future<? extends T> other)` Attempts to complete this `Promise` with the specified `Future`, once that `Future` is completed.
`default boolean`	`tryFailure(java.lang.Throwable exception)` Completes this `Promise` with the given `exception`.
`default boolean`	`trySuccess(T value)` Completes this `Promise` with the given `value`.

- Method Detail
  - failed
```
static <T> Promise<T> failed(java.lang.Throwable exception)
```
    Creates a failed Promise, backed by the Future.DEFAULT_EXECUTOR.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    exception - The reason why it failed.
    
    Returns:
    
    A failed Promise.
    
    Throws:
    
    java.lang.NullPointerException - if exception is null
  - failed
```
static <T> Promise<T> failed(java.util.concurrent.Executor executor,
                             java.lang.Throwable exception)
```
    Creates a failed Promise, backed by the given Executor.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executor - An Executor passed to the underlying Future.
    
    exception - The reason why it failed.
    
    Returns:
    
    A failed Promise.
    
    Throws:
    
    java.lang.NullPointerException - if executor or exception is null
  - fromTry
```
static <T> Promise<T> fromTry(Try<? extends T> result)
```
    Creates a Promise from a Try, backed by the Future.DEFAULT_EXECUTOR.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    result - The result.
    
    Returns:
    
    A completed Promise which contains either a Success or a Failure.
    
    Throws:
    
    java.lang.NullPointerException - if result is null
  - fromTry
```
static <T> Promise<T> fromTry(java.util.concurrent.Executor executor,
                              Try<? extends T> result)
```
    Creates a Promise from a Try, backed by the given Executor.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executor - An Executor passed to the underlying Future.
    
    result - The result.
    
    Returns:
    
    A completed Promise which contains either a Success or a Failure.
    
    Throws:
    
    java.lang.NullPointerException - if executor or result is null
  - make
```
static <T> Promise<T> make()
```
    Makes a Promise that isn't fulfilled yet, backed by the Future.DEFAULT_EXECUTOR. ForkJoinPool.commonPool().
    
    Type Parameters:
    
    T - Result type of the Promise.
    
    Returns:
    
    A new Promise.
  - make
```
static <T> Promise<T> make(java.util.concurrent.Executor executor)
```
    Makes a Promise that isn't fulfilled yet, backed by the given Executor.
    
    Type Parameters:
    
    T - Result type of the Promise.
    
    Parameters:
    
    executor - An Executor passed to the underlying Future.
    
    Returns:
    
    A new Promise.
    
    Throws:
    
    java.lang.NullPointerException - if executor is null
  - narrow
```
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.
    
    Type Parameters:
    
    T - Component type of the Promise.
    
    Parameters:
    
    promise - A Promise.
    
    Returns:
    
    the given promise instance as narrowed type Promise<T>.
  - successful
```
static <T> Promise<T> successful(T result)
```
    Creates a succeeded Promise, backed by the Future.DEFAULT_EXECUTOR.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    result - The result.
    
    Returns:
    
    A succeeded Promise.
  - successful
```
static <T> Promise<T> successful(java.util.concurrent.Executor executor,
                                 T result)
```
    Creates a succeeded Promise, backed by the given Executor.
    
    Type Parameters:
    
    T - The value type of a successful result.
    
    Parameters:
    
    executor - An Executor passed to the underlying Future.
    
    result - The result.
    
    Returns:
    
    A succeeded Promise.
    
    Throws:
    
    java.lang.NullPointerException - if executor is null
  - executor
```
default java.util.concurrent.Executor executor()
```
    Returns the Executor used by the underlying Future of this Promise.
    
    Returns:
    
    The underlying Executor.
  - executorService
```
@Deprecated
java.util.concurrent.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:
    
    (never)
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the underlying Executor isn't an ExecutorService.
  - future
```
Future<T> future()
```
    Returns the underlying Future of this Promise.
    
    Returns:
    
    The Future.
  - isCompleted
```
default boolean isCompleted()
```
    Checks if this Promise is completed, i.e. has a value.
    
    Returns:
    
    true, if the computation successfully finished or failed, false otherwise.
  - complete
```
default Promise<T> complete(Try<? extends T> value)
```
    Completes this Promise with the given value.
    
    Parameters:
    
    value - Either a Try.Success containing the result or a Try.Failure containing an exception.
    
    Returns:
    
    This Promise.
    
    Throws:
    
    java.lang.IllegalStateException - if this Promise has already been completed.
  - tryComplete
```
boolean tryComplete(Try<? extends T> value)
```
    Attempts to completes this Promise with the given value.
    
    Parameters:
    
    value - Either a Try.Success containing the result or a Try.Failure containing an exception.
    
    Returns:
    
    false if this Promise has already been completed, true otherwise.
    
    Throws:
    
    java.lang.IllegalStateException - if this Promise has already been completed.
  - completeWith
```
default Promise<T> completeWith(Future<? extends T> other)
```
    Completes this Promise with the given Future, once that Future is completed.
    
    Parameters:
    
    other - Another Future to react on.
    
    Returns:
    
    This Promise.
  - tryCompleteWith
```
default Promise<T> tryCompleteWith(Future<? extends T> other)
```
    Attempts to complete this Promise with the specified Future, once that Future is completed.
    
    Parameters:
    
    other - Another Future to react on.
    
    Returns:
    
    This Promise.
  - success
```
default Promise<T> success(T value)
```
    Completes this Promise with the given value.
    
    Parameters:
    
    value - A value.
    
    Returns:
    
    This Promise.
    
    Throws:
    
    java.lang.IllegalStateException - if this Promise has already been completed.
  - trySuccess
```
default boolean trySuccess(T value)
```
    Completes this Promise with the given value.
    
    Parameters:
    
    value - A value.
    
    Returns:
    
    false if this Promise has already been completed, true otherwise.
  - failure
```
default Promise<T> failure(java.lang.Throwable exception)
```
    Completes this Promise with the given exception.
    
    Parameters:
    
    exception - An exception.
    
    Returns:
    
    This Promise.
    
    Throws:
    
    java.lang.IllegalStateException - if this Promise has already been completed.
  - tryFailure
```
default boolean tryFailure(java.lang.Throwable exception)
```
    Completes this Promise with the given exception.
    
    Parameters:
    
    exception - An exception.
    
    Returns:
    
    false if this Promise has already been completed, true otherwise.

Interface Promise<T>

Creation

One-shot API

API for competing threads

Method Summary

Method Detail

failed

failed

fromTry

fromTry

make

make

narrow

successful

successful

executor

executorService

future

isCompleted

complete

tryComplete

completeWith

tryCompleteWith

success

trySuccess

failure

tryFailure