Interface Promise<T>
- Type Parameters:
T
- The result type of the underlyingFuture
.
- All Known Implementing Classes:
PromiseImpl
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()
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 Thread
s may complete our Promise
, we typically use one of these methods. Calls will
gracefully return false
if the Promise
is already completed.
-
Method Summary
Modifier and TypeMethodDescriptionCompletes thisPromise
with the givenvalue
.completeWith
(Future<? extends T> other) Completes thisPromise
with the givenFuture
, once thatFuture
is completed.default Executor
executor()
Deprecated.static <T> Promise
<T> Creates a failedPromise
, backed by theFuture.DEFAULT_EXECUTOR
.static <T> Promise
<T> Creates a failedPromise
, backed by the givenExecutor
.Completes thisPromise
with the givenexception
.static <T> Promise
<T> static <T> Promise
<T> future()
Returns the underlyingFuture
of thisPromise
.default boolean
Checks if thisPromise
is completed, i.e.static <T> Promise
<T> make()
Makes aPromise
that isn't fulfilled yet, backed by theFuture.DEFAULT_EXECUTOR
.static <T> Promise
<T> Makes aPromise
that isn't fulfilled yet, backed by the givenExecutor
.static <T> Promise
<T> Narrows a widenedPromise<? extends T>
toPromise<T>
by performing a type-safe cast.Completes thisPromise
with the givenvalue
.static <T> Promise
<T> successful
(Executor executor, T result) Creates a succeededPromise
, backed by the givenExecutor
.static <T> Promise
<T> successful
(T result) Creates a succeededPromise
, backed by theFuture.DEFAULT_EXECUTOR
.boolean
tryComplete
(Try<? extends T> value) Attempts to completes thisPromise
with the givenvalue
.tryCompleteWith
(Future<? extends T> other) Attempts to complete thisPromise
with the specifiedFuture
, once thatFuture
is completed.default boolean
tryFailure
(Throwable exception) Completes thisPromise
with the givenexception
.default boolean
trySuccess
(T value) Completes thisPromise
with the givenvalue
.
-
Method Details
-
failed
Creates a failedPromise
, backed by theFuture.DEFAULT_EXECUTOR
.- Type Parameters:
T
- The value type of a successful result.- Parameters:
exception
- The reason why it failed.- Returns:
- A failed
Promise
. - Throws:
NullPointerException
- if exception is null
-
failed
Creates a failedPromise
, backed by the givenExecutor
.- Type Parameters:
T
- The value type of a successful result.- Parameters:
executor
- AnExecutor
passed to the underlyingFuture
.exception
- The reason why it failed.- Returns:
- A failed
Promise
. - Throws:
NullPointerException
- if executor or exception is null
-
fromTry
- Type Parameters:
T
- The value type of a successful result.- Parameters:
result
- The result.- Returns:
- A completed
Promise
which contains either aSuccess
or aFailure
. - Throws:
NullPointerException
- if result is null
-
fromTry
- Type Parameters:
T
- The value type of a successful result.- Parameters:
executor
- AnExecutor
passed to the underlyingFuture
.result
- The result.- Returns:
- A completed
Promise
which contains either aSuccess
or aFailure
. - Throws:
NullPointerException
- if executor or result is null
-
make
Makes aPromise
that isn't fulfilled yet, backed by theFuture.DEFAULT_EXECUTOR
.ForkJoinPool.commonPool()
.- Type Parameters:
T
- Result type of thePromise
.- Returns:
- A new
Promise
.
-
make
Makes aPromise
that isn't fulfilled yet, backed by the givenExecutor
.- Type Parameters:
T
- Result type of thePromise
.- Parameters:
executor
- AnExecutor
passed to the underlyingFuture
.- Returns:
- A new
Promise
. - Throws:
NullPointerException
- if executor is null
-
narrow
Narrows a widenedPromise<? extends T>
toPromise<T>
by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.- Type Parameters:
T
- Component type of thePromise
.- Parameters:
promise
- APromise
.- Returns:
- the given
promise
instance as narrowed typePromise<T>
.
-
successful
Creates a succeededPromise
, backed by theFuture.DEFAULT_EXECUTOR
.- Type Parameters:
T
- The value type of a successful result.- Parameters:
result
- The result.- Returns:
- A succeeded
Promise
.
-
successful
Creates a succeededPromise
, backed by the givenExecutor
.- Type Parameters:
T
- The value type of a successful result.- Parameters:
executor
- AnExecutor
passed to the underlyingFuture
.result
- The result.- Returns:
- A succeeded
Promise
. - Throws:
NullPointerException
- if executor is null
-
executor
- Returns:
- The underlying
Executor
.
-
executorService
Deprecated.Removed starting with Vavr 0.10.0, useexecutor()
instead.This method is deprecated.THE DEFAULT IMPLEMENTATION (obtained by one of the
Promise
factory methods) MIGHT THROW ANUnsupportedOperationException
AT RUNTIME, DEPENDING ON WHATFuture.executorService()
returns.- Returns:
- (never)
- Throws:
UnsupportedOperationException
- if the underlyingExecutor
isn't anExecutorService
.
-
future
Returns the underlyingFuture
of thisPromise
.- Returns:
- The
Future
.
-
isCompleted
default boolean isCompleted()Checks if thisPromise
is completed, i.e. has a value.- Returns:
- true, if the computation successfully finished or failed, false otherwise.
-
complete
Completes thisPromise
with the givenvalue
.- Parameters:
value
- Either aTry.Success
containing the result or aTry.Failure
containing an exception.- Returns:
- This
Promise
. - Throws:
IllegalStateException
- if thisPromise
has already been completed.
-
tryComplete
Attempts to completes thisPromise
with the givenvalue
.- Parameters:
value
- Either aTry.Success
containing the result or aTry.Failure
containing an exception.- Returns:
false
if thisPromise
has already been completed,true
otherwise.- Throws:
IllegalStateException
- if thisPromise
has already been completed.
-
completeWith
Completes thisPromise
with the givenFuture
, once thatFuture
is completed.- Parameters:
other
- AnotherFuture
to react on.- Returns:
- This
Promise
.
-
tryCompleteWith
Attempts to complete thisPromise
with the specifiedFuture
, once thatFuture
is completed.- Parameters:
other
- AnotherFuture
to react on.- Returns:
- This
Promise
.
-
success
Completes thisPromise
with the givenvalue
.- Parameters:
value
- A value.- Returns:
- This
Promise
. - Throws:
IllegalStateException
- if thisPromise
has already been completed.
-
trySuccess
Completes thisPromise
with the givenvalue
.- Parameters:
value
- A value.- Returns:
false
if thisPromise
has already been completed,true
otherwise.
-
failure
Completes thisPromise
with the givenexception
.- Parameters:
exception
- An exception.- Returns:
- This
Promise
. - Throws:
IllegalStateException
- if thisPromise
has already been completed.
-
tryFailure
Completes thisPromise
with the givenexception
.- Parameters:
exception
- An exception.- Returns:
false
if thisPromise
has already been completed,true
otherwise.
-
executor()
instead.