tommyskeff/futur4j
1
0
Fork 0
mirror of https://github.com/tommyskeff/futur4j.git synced 2026-01-18 07:16:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

a few documentation improvements

Browse Source
This commit is contained in:
tommyskeff
2025-01-06 22:44:45 +00:00
parent 6174193145
commit f2ec06fba7
8 changed files with 183 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -2,10 +2,9 @@
Futur4J is a powerful and intuitive open-source Java library that simplifies asynchronous task scheduling, inspired by the concept of JavaScript promises. Futur4J is a powerful and intuitive open-source Java library that simplifies asynchronous task scheduling, inspired by the concept of JavaScript promises.
**This documentation is outdated. Please don't read it.**
## Dependency ## Dependency
The Futur4J project is composed of multiple modules. It is required to include the `futur-api` module, and the other modules depend on it at runtime, however the others are optional and dependent on your use case. The Futur4J project has a `futur-api` module that provides the core functionality, and a `futur-lazy` module that provides additional static versions of factory methods. It is
recommended to use the main module for customization of logging and execution.
### Gradle ### Gradle
```gradle ```gradle
repositories { repositories {

6
futur-api/src/main/java/dev/tommyjs/futur/executor/PromiseExecutor.java
View File

@@ -10,6 +10,7 @@ public interface PromiseExecutor<T> {
/** /**
* Creates a new {@link PromiseExecutor} that runs tasks on virtual threads. * Creates a new {@link PromiseExecutor} that runs tasks on virtual threads.
*
* @return the new executor * @return the new executor
*/ */
static PromiseExecutor<?> virtualThreaded() { static PromiseExecutor<?> virtualThreaded() {
@@ -18,6 +19,7 @@ public interface PromiseExecutor<T> {
/** /**
* Creates a new {@link PromiseExecutor} that runs tasks on a single thread. * Creates a new {@link PromiseExecutor} that runs tasks on a single thread.
*
* @return the new executor * @return the new executor
*/ */
static PromiseExecutor<?> singleThreaded() { static PromiseExecutor<?> singleThreaded() {
@@ -26,6 +28,7 @@ public interface PromiseExecutor<T> {
/** /**
* Creates a new {@link PromiseExecutor} that runs tasks on multiple threads. * Creates a new {@link PromiseExecutor} that runs tasks on multiple threads.
*
* @param threads the number of threads * @param threads the number of threads
* @return the new executor * @return the new executor
*/ */
@@ -35,6 +38,7 @@ public interface PromiseExecutor<T> {
/** /**
* Creates a new {@link PromiseExecutor} that runs tasks on the given executor service. * Creates a new {@link PromiseExecutor} that runs tasks on the given executor service.
*
* @param service the executor service * @param service the executor service
* @return the new executor * @return the new executor
*/ */
@@ -44,6 +48,7 @@ public interface PromiseExecutor<T> {
/** /**
* Runs the given task. * Runs the given task.
*
* @param task the task * @param task the task
* @return the task * @return the task
* @throws Exception if scheduling the task failed * @throws Exception if scheduling the task failed
@@ -52,6 +57,7 @@ public interface PromiseExecutor<T> {
/** /**
* Runs the given task after the given delay. * Runs the given task after the given delay.
*
* @param task the task * @param task the task
* @param delay the delay * @param delay the delay
* @param unit the time unit * @param unit the time unit

2
futur-api/src/main/java/dev/tommyjs/futur/promise/CompletablePromise.java
View File

@@ -10,12 +10,14 @@ public interface CompletablePromise<T> extends Promise<T> {
/** /**
* Completes the promise successfully with the given result. * Completes the promise successfully with the given result.
*
* @param result the result * @param result the result
*/ */
void complete(@Nullable T result); void complete(@Nullable T result);
/** /**
* Completes the promise exceptionally with the given exception. * Completes the promise exceptionally with the given exception.
*
* @param result the exception * @param result the exception
*/ */
void completeExceptionally(@NotNull Throwable result); void completeExceptionally(@NotNull Throwable result);

116
futur-api/src/main/java/dev/tommyjs/futur/promise/Promise.java
View File

@@ -38,7 +38,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* when this promise completes. * when this promise completes. Cancelling the returned promise will cancel this promise, and
* consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -47,7 +48,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* when this promise completes and will be passed the result of this promise. * when this promise completes and will be passed the result of this promise. Cancelling the returned
* promise will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -56,7 +58,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* when this promise completes, and will supply a value to the next promise in the chain. * when this promise completes, and will supply a value to the next promise in the chain. Cancelling
* the returned promise will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -66,7 +69,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* when this promise completes, and will apply the specified function to the result of this promise * when this promise completes, and will apply the specified function to the result of this promise
* in order to supply a value to the next promise in the chain. * in order to supply a value to the next promise in the chain. Cancelling the returned promise will
* cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -76,7 +80,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* when this promise completes, and will compose the next promise in the chainfrom the result of * when this promise completes, and will compose the next promise in the chainfrom the result of
* this promise. * this promise. Cancelling the returned promise will cancel this promise, and consequently any
* previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, once this promise and the promise returned by * @return a new promise that completes, once this promise and the promise returned by
@@ -87,6 +92,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* sync executor of the factory that created this promise, immediately after this promise completes. * sync executor of the factory that created this promise, immediately after this promise completes.
* Cancelling the returned promise will cancel this promise, and consequently any previous promises
* in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -96,7 +103,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* sync executor of the factory that created this promise, after the specified delay after this * sync executor of the factory that created this promise, after the specified delay after this
* promise completes. * promise completes. Cancelling the returned promise will cancel this promise, and consequently
* any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -108,7 +116,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* sync executor of the factory that created this promise immediately after this promise completes, * sync executor of the factory that created this promise immediately after this promise completes,
* and will be passed the result of this promise. * and will be passed the result of this promise. Cancelling the returned promise will cancel this
* promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -118,7 +127,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* sync executor of the factory that created this promise after the specified delay after this * sync executor of the factory that created this promise after the specified delay after this
* promise completes, and will be passed the result of this promise. * promise completes, and will be passed the result of this promise. Cancelling the returned promise
* will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -130,7 +140,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed immediately * Chains a task to be executed after this promise completes. The task will be executed immediately
* by the sync executor of the factory that created this promise when this promise completes, and * by the sync executor of the factory that created this promise when this promise completes, and
* will supply a value to the next promise in the chain. * will supply a value to the next promise in the chain. Cancelling the returned promise will cancel
* this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -140,7 +151,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the sync * Chains a task to be executed after this promise completes. The task will be executed by the sync
* executor of the factory that created this promise after the specified delay after this promise * executor of the factory that created this promise after the specified delay after this promise
* completes, and will supply a value to the next promise in the chain. * completes, and will supply a value to the next promise in the chain. Cancelling the returned promise
* will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -153,7 +165,8 @@ public interface Promise<T> {
* Chains a task to be executed after this promise completes. The task will be executed by the sync * Chains a task to be executed after this promise completes. The task will be executed by the sync
* executor of the factory that created this promise immediately after this promise completes, and * executor of the factory that created this promise immediately after this promise completes, and
* will apply the specified function to the result of this promise in order to supply a value to the * will apply the specified function to the result of this promise in order to supply a value to the
* next promise in the chain. * next promise in the chain. Cancelling the returned promise will cancel this promise, and consequently
* any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -164,7 +177,8 @@ public interface Promise<T> {
* Chains a task to be executed after this promise completes. The task will be executed by the sync * Chains a task to be executed after this promise completes. The task will be executed by the sync
* executor of the factory that created this promise after the specified delay after this promise * executor of the factory that created this promise after the specified delay after this promise
* completes, and will apply the specified function to the result of this promise in order to supply * completes, and will apply the specified function to the result of this promise in order to supply
* a value to the next promise in the chain. * a value to the next promise in the chain. Cancelling the returned promise will cancel this promise,
* and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -176,7 +190,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the sync * Chains a task to be executed after this promise completes. The task will be executed by the sync
* executor of the factory that created this promise immediately after this promise completes, and * executor of the factory that created this promise immediately after this promise completes, and
* will compose the next promise in the chain from the result of this promise. * will compose the next promise in the chain from the result of this promise. Cancelling the returned
* promise will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, once this promise and the promise returned by the task are * @return a new promise that completes, once this promise and the promise returned by the task are
@@ -187,6 +202,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* async executor of the factory that created this promise, immediately after this promise completes. * async executor of the factory that created this promise, immediately after this promise completes.
* Cancelling the returned promise will cancel this promise, and consequently any previous promises
* in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -196,7 +213,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* async executor of the factory that created this promise after the specified delay after this * async executor of the factory that created this promise after the specified delay after this
* promise completes. * promise completes. Cancelling the returned promise will cancel this promise, and consequently
* any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -208,7 +226,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* async executor of the factory that created this promise immediately after this promise completes, * async executor of the factory that created this promise immediately after this promise completes,
* and will be passed the result of this promise. * and will be passed the result of this promise. Cancelling the returned promise will cancel this
* promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes after the task is executed * @return a new promise that completes after the task is executed
@@ -218,7 +237,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* async executor of the factory that created this promise after the specified delay after this * async executor of the factory that created this promise after the specified delay after this
* promise completes, and will be passed the result of this promise. * promise completes, and will be passed the result of this promise. Cancelling the returned promise
* will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -230,7 +250,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the * Chains a task to be executed after this promise completes. The task will be executed by the
* async executor of the factory that created this promise immediately after this promise completes, * async executor of the factory that created this promise immediately after this promise completes,
* and will supply a value to the next promise in the chain. * and will supply a value to the next promise in the chain. Cancelling the returned promise will
* cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -240,7 +261,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the async * Chains a task to be executed after this promise completes. The task will be executed by the async
* executor of the factory that created this promise after the specified delay after this promise * executor of the factory that created this promise after the specified delay after this promise
* completes, and will supply a value to the next promise in the chain. * completes, and will supply a value to the next promise in the chain. Cancelling the returned promise
* will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -253,7 +275,8 @@ public interface Promise<T> {
* Chains a task to be executed after this promise completes. The task will be executed by the async * Chains a task to be executed after this promise completes. The task will be executed by the async
* executor of the factory that created this promise immediately after this promise completes, and * executor of the factory that created this promise immediately after this promise completes, and
* will apply the specified function to the result of this promise in order to supply a value to the * will apply the specified function to the result of this promise in order to supply a value to the
* next promise in the chain. * next promise in the chain. Cancelling the returned promise will cancel this promise, and consequently
* any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, after the task is executed, with the task result * @return a new promise that completes, after the task is executed, with the task result
@@ -264,7 +287,8 @@ public interface Promise<T> {
* Chains a task to be executed after this promise completes. The task will be executed by the async * Chains a task to be executed after this promise completes. The task will be executed by the async
* executor of the factory that created this promise after the specified delay after this promise * executor of the factory that created this promise after the specified delay after this promise
* completes, and will apply the specified function to the result of this promise in order to supply * completes, and will apply the specified function to the result of this promise in order to supply
* a value to the next promise in the chain. * a value to the next promise in the chain. Cancelling the returned promise will cancel this promise,
* and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @param delay the amount of time to wait before executing the task * @param delay the amount of time to wait before executing the task
@@ -276,7 +300,8 @@ public interface Promise<T> {
/** /**
* Chains a task to be executed after this promise completes. The task will be executed by the async * Chains a task to be executed after this promise completes. The task will be executed by the async
* executor of the factory that created this promise immediately after this promise completes, and * executor of the factory that created this promise immediately after this promise completes, and
* will compose the next promise in the chain from the result of this promise. * will compose the next promise in the chain from the result of this promise. Cancelling the returned
* promise will cancel this promise, and consequently any previous promises in the chain.
* *
* @param task the task to execute * @param task the task to execute
* @return a new promise that completes, once this promise and the promise returned by the task are * @return a new promise that completes, once this promise and the promise returned by the task are
@@ -286,7 +311,8 @@ public interface Promise<T> {
/** /**
* Adds a listener to this promise that will populate the specified reference with the result of this * Adds a listener to this promise that will populate the specified reference with the result of this
* promise upon successful completion. * promise upon successful completion. The reference will not be populated if this promise completes
* exceptionally.
* *
* @param reference the reference to populate * @param reference the reference to populate
* @return continuation of the promise chain * @return continuation of the promise chain
@@ -295,12 +321,25 @@ public interface Promise<T> {
/** /**
* Returns a promise backed by this promise that will complete with {@code null} if this promise * Returns a promise backed by this promise that will complete with {@code null} if this promise
* completes successfully, or with the exception if this promise completes exceptionally. * completes successfully, or with the exception if this promise completes exceptionally. Cancelling
* the returned promise will cancel this promise, and consequently any previous promises in the chain.
*/ */
@NotNull Promise<Void> erase(); @NotNull Promise<Void> erase();
/** /**
* Logs any exceptions that occur in the promise chain. * Logs any exceptions that occur in the promise chain with the specified message. The stack trace
* will be captured immediately when invoking this method, and logged alongside an exception if
* encountered, to allow for easier debugging.
*
* @param message the message to log
* @return continuation of the promise chain
*/
@NotNull Promise<T> logExceptions(@NotNull String message);
/**
* Logs any exceptions that occur in the promise chain. The stack trace will be captured immediately
* when invoking this method, and logged alongside an exception if encountered, to allow for easier
* debugging.
* *
* @return continuation of the promise chain * @return continuation of the promise chain
*/ */
@@ -308,14 +347,6 @@ public interface Promise<T> {
return logExceptions("Exception caught in promise chain"); return logExceptions("Exception caught in promise chain");
} }
/**
* Logs any exceptions that occur in the promise chain with the specified message.
*
* @param message the message to log
* @return continuation of the promise chain
*/
@NotNull Promise<T> logExceptions(@NotNull String message);
/** /**
* Adds a listener to this promise that will be executed immediately when this promise completes, * Adds a listener to this promise that will be executed immediately when this promise completes,
* on the same thread as the completion call. * on the same thread as the completion call.
@@ -412,6 +443,7 @@ public interface Promise<T> {
/** /**
* Cancels the promise if not already completed after the specified timeout. This will result in * Cancels the promise if not already completed after the specified timeout. This will result in
* an exceptional completion with a {@link CancellationException}. * an exceptional completion with a {@link CancellationException}.
*
* @param ms the amount of time to wait before cancelling the promise (in milliseconds) * @param ms the amount of time to wait before cancelling the promise (in milliseconds)
* @return continuation of the promise chain * @return continuation of the promise chain
*/ */
@@ -434,6 +466,7 @@ public interface Promise<T> {
* Times out the promise if not already completed after the specified timeout. This will result * Times out the promise if not already completed after the specified timeout. This will result
* in an exceptional completion with a {@link TimeoutException}. This will not result in the * in an exceptional completion with a {@link TimeoutException}. This will not result in the
* promise being cancelled. * promise being cancelled.
*
* @param ms the amount of time to wait before timing out the promise (in milliseconds) * @param ms the amount of time to wait before timing out the promise (in milliseconds)
* @return continuation of the promise chain * @return continuation of the promise chain
*/ */
@@ -444,6 +477,7 @@ public interface Promise<T> {
/** /**
* Cancels the promise if not already completed after the specified timeout. This will result in * Cancels the promise if not already completed after the specified timeout. This will result in
* an exceptional completion with the specified cancellation. * an exceptional completion with the specified cancellation.
*
* @param exception the cancellation exception to complete the promise with * @param exception the cancellation exception to complete the promise with
*/ */
void cancel(@NotNull CancellationException exception); void cancel(@NotNull CancellationException exception);
@@ -451,6 +485,7 @@ public interface Promise<T> {
/** /**
* Cancels the promise if not already completed after the specified timeout. This will result in * Cancels the promise if not already completed after the specified timeout. This will result in
* an exceptional completion with a {@link CancellationException}. * an exceptional completion with a {@link CancellationException}.
*
* @param reason the reason for the cancellation * @param reason the reason for the cancellation
*/ */
default void cancel(@NotNull String reason) { default void cancel(@NotNull String reason) {
@@ -467,19 +502,21 @@ public interface Promise<T> {
/** /**
* Blocks until this promise has completed, and then returns its result. * Blocks until this promise has completed, and then returns its result.
*
* @return the result of the promise
* @throws CancellationException if the promise was cancelled * @throws CancellationException if the promise was cancelled
* @throws CompletionException if the promise completed exceptionally * @throws CompletionException if the promise completed exceptionally
* @return the result of the promise
*/ */
@Blocking @Blocking
T await(); T await();
/** /**
* Blocks until this promise has completed, and then returns its result. * Blocks until this promise has completed, and then returns its result.
*
* @return the result of the promise
* @throws CancellationException if the promise was cancelled * @throws CancellationException if the promise was cancelled
* @throws ExecutionException if the promise completed exceptionally * @throws ExecutionException if the promise completed exceptionally
* @throws InterruptedException if the current thread was interrupted while waiting * @throws InterruptedException if the current thread was interrupted while waiting
* @return the result of the promise
*/ */
@Blocking @Blocking
T get() throws InterruptedException, ExecutionException; T get() throws InterruptedException, ExecutionException;
@@ -487,19 +524,21 @@ public interface Promise<T> {
/** /**
* Blocks until either this promise has completed or the timeout has been exceeded, and then * Blocks until either this promise has completed or the timeout has been exceeded, and then
* returns its result, if available. * returns its result, if available.
*
* @return the result of the promise
* @throws CancellationException if the promise was cancelled * @throws CancellationException if the promise was cancelled
* @throws ExecutionException if the promise completed exceptionally * @throws ExecutionException if the promise completed exceptionally
* @throws InterruptedException if the current thread was interrupted while waiting * @throws InterruptedException if the current thread was interrupted while waiting
* @throws TimeoutException if the timeout was exceeded * @throws TimeoutException if the timeout was exceeded
* @return the result of the promise
*/ */
@Blocking @Blocking
T get(long timeout, @NotNull TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException; T get(long timeout, @NotNull TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException;
/** /**
* Returns a new promise, backed by this promise, that will not propagate cancellations. This means * Returns a new promise, backed by this promise, that will not propagate cancellations. This means
* that if the returned promise is cancelled, the cancellation will not be propagated to this promise * that if the returned promise is cancelled, the cancellation will not be propagated to this promise,
* or any other promises that share this promise as a parent. * and consequently any previous promises in the chain.
*
* @return continuation the promise chain that will not propagate cancellations * @return continuation the promise chain that will not propagate cancellations
*/ */
@NotNull Promise<T> fork(); @NotNull Promise<T> fork();
@@ -507,12 +546,14 @@ public interface Promise<T> {
/** /**
* Returns the current completion state of this promise. If the promise has not completed, this method * Returns the current completion state of this promise. If the promise has not completed, this method
* will return {@code null}. * will return {@code null}.
*
* @return the completion state of this promise, or {@code null} if the promise has not completed * @return the completion state of this promise, or {@code null} if the promise has not completed
*/ */
@Nullable PromiseCompletion<T> getCompletion(); @Nullable PromiseCompletion<T> getCompletion();
/** /**
* Returns whether this promise has completed. * Returns whether this promise has completed.
*
* @return {@code true} if the promise has completed, {@code false} otherwise * @return {@code true} if the promise has completed, {@code false} otherwise
*/ */
boolean isCompleted(); boolean isCompleted();
@@ -520,6 +561,7 @@ public interface Promise<T> {
/** /**
* Converts this promise to a {@link CompletableFuture}. The returned future will complete with the * Converts this promise to a {@link CompletableFuture}. The returned future will complete with the
* result of this promise when it completes. * result of this promise when it completes.
*
* @return a future that will complete with the result of this promise * @return a future that will complete with the result of this promise
*/ */
@NotNull CompletableFuture<T> toFuture(); @NotNull CompletableFuture<T> toFuture();

7
futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseCompletion.java
View File

@@ -15,6 +15,7 @@ public class PromiseCompletion<T> {
/** /**
* Creates a new successful completion. * Creates a new successful completion.
*
* @param result the result * @param result the result
*/ */
public PromiseCompletion(@Nullable T result) { public PromiseCompletion(@Nullable T result) {
@@ -23,6 +24,7 @@ public class PromiseCompletion<T> {
/** /**
* Creates a new exceptional completion. * Creates a new exceptional completion.
*
* @param exception the exception * @param exception the exception
*/ */
public PromiseCompletion(@NotNull Throwable exception) { public PromiseCompletion(@NotNull Throwable exception) {
@@ -38,6 +40,7 @@ public class PromiseCompletion<T> {
/** /**
* Checks if the completion was successful. * Checks if the completion was successful.
*
* @return {@code true} if the completion was successful, {@code false} otherwise * @return {@code true} if the completion was successful, {@code false} otherwise
*/ */
public boolean isSuccess() { public boolean isSuccess() {
@@ -46,6 +49,7 @@ public class PromiseCompletion<T> {
/** /**
* Checks if the completion was exceptional. * Checks if the completion was exceptional.
*
* @return {@code true} if the completion was exceptional, {@code false} otherwise * @return {@code true} if the completion was exceptional, {@code false} otherwise
*/ */
public boolean isError() { public boolean isError() {
@@ -54,6 +58,7 @@ public class PromiseCompletion<T> {
/** /**
* Checks if the completion was cancelled. * Checks if the completion was cancelled.
*
* @return {@code true} if the completion was cancelled, {@code false} otherwise * @return {@code true} if the completion was cancelled, {@code false} otherwise
*/ */
public boolean wasCancelled() { public boolean wasCancelled() {
@@ -67,6 +72,7 @@ public class PromiseCompletion<T> {
/** /**
* Gets the result of the completion. * Gets the result of the completion.
*
* @return the result, or {@code null} if the completion was exceptional * @return the result, or {@code null} if the completion was exceptional
*/ */
public @Nullable T getResult() { public @Nullable T getResult() {
@@ -75,6 +81,7 @@ public class PromiseCompletion<T> {
/** /**
* Gets the exception of the completion. * Gets the exception of the completion.
*
* @return the exception, or {@code null} if the completion was successful * @return the exception, or {@code null} if the completion was successful
*/ */
public @Nullable Throwable getException() { public @Nullable Throwable getException() {

44
futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseFactory.java
View File

@@ -16,6 +16,7 @@ public interface PromiseFactory {
/** /**
* Creates a new {@link PromiseFactory} with the given logger and executors. * Creates a new {@link PromiseFactory} with the given logger and executors.
*
* @param logger the logger * @param logger the logger
* @param syncExecutor the synchronous executor * @param syncExecutor the synchronous executor
* @param asyncExecutor the asynchronous executor * @param asyncExecutor the asynchronous executor
@@ -28,6 +29,7 @@ public interface PromiseFactory {
/** /**
* Creates a new {@link PromiseFactory} with the given logger and dual executor. * Creates a new {@link PromiseFactory} with the given logger and dual executor.
*
* @param logger the logger * @param logger the logger
* @param executor the executor * @param executor the executor
* @return the new promise factory * @return the new promise factory
@@ -38,6 +40,7 @@ public interface PromiseFactory {
/** /**
* Creates a new {@link PromiseFactory} with the given logger and executor. * Creates a new {@link PromiseFactory} with the given logger and executor.
*
* @param logger the logger * @param logger the logger
* @param executor the executor * @param executor the executor
* @return the new promise factory * @return the new promise factory
@@ -48,12 +51,14 @@ public interface PromiseFactory {
/** /**
* Creates a new uncompleted promise. * Creates a new uncompleted promise.
*
* @return the new promise * @return the new promise
*/ */
<T> @NotNull CompletablePromise<T> unresolved(); <T> @NotNull CompletablePromise<T> unresolved();
/** /**
* Creates a new promise, completed with the given value. * Creates a new promise, completed with the given value.
*
* @param value the value to complete the promise with * @param value the value to complete the promise with
* @return the new promise * @return the new promise
*/ */
@@ -61,8 +66,9 @@ public interface PromiseFactory {
/** /**
* Creates a new promise, completed with {@code null}. * Creates a new promise, completed with {@code null}.
* @apiNote This method is often useful for starting promise chains. *
* @return the new promise * @return the new promise
* @apiNote This method is often useful for starting promise chains.
*/ */
default @NotNull Promise<Void> start() { default @NotNull Promise<Void> start() {
return resolve(null); return resolve(null);
@@ -70,6 +76,7 @@ public interface PromiseFactory {
/** /**
* Creates a new promise, completed exceptionally with the given error. * Creates a new promise, completed exceptionally with the given error.
*
* @param error the error to complete the promise with * @param error the error to complete the promise with
* @return the new promise * @return the new promise
*/ */
@@ -78,6 +85,7 @@ public interface PromiseFactory {
/** /**
* Creates a new promise backed by the given future. The promise will be completed upon completion * Creates a new promise backed by the given future. The promise will be completed upon completion
* of the future. * of the future.
*
* @param future the future to wrap * @param future the future to wrap
* @return the new promise * @return the new promise
*/ */
@@ -88,6 +96,7 @@ public interface PromiseFactory {
* {@code link} is {@code true} and either input promise completes exceptionally (including * {@code link} is {@code true} and either input promise completes exceptionally (including
* cancellation), the other promise will be cancelled and the output promise will complete * cancellation), the other promise will be cancelled and the output promise will complete
* exceptionally. * exceptionally.
*
* @param p1 the first promise * @param p1 the first promise
* @param p2 the second promise * @param p2 the second promise
* @param link whether to cancel the other promise on error * @param link whether to cancel the other promise on error
@@ -100,6 +109,7 @@ public interface PromiseFactory {
* Combines two promises into a single promise that completes when both promises complete. If either * Combines two promises into a single promise that completes when both promises complete. If either
* input promise completes exceptionally, the other promise will be cancelled and the output promise * input promise completes exceptionally, the other promise will be cancelled and the output promise
* will complete exceptionally. * will complete exceptionally.
*
* @param p1 the first promise * @param p1 the first promise
* @param p2 the second promise * @param p2 the second promise
* @return the combined promise * @return the combined promise
@@ -115,6 +125,7 @@ public interface PromiseFactory {
* promise will complete exceptionally. If an exception handler is present, promises that fail * promise will complete exceptionally. If an exception handler is present, promises that fail
* will not cause this behaviour, and instead the exception handler will be called with the key * will not cause this behaviour, and instead the exception handler will be called with the key
* that failed and the exception. * that failed and the exception.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
@@ -129,6 +140,7 @@ public interface PromiseFactory {
* pairs of inputs to outputs when all promises complete. If any promise completes exceptionally, * pairs of inputs to outputs when all promises complete. If any promise completes exceptionally,
* the exception handler will be called with the key that failed and the exception. The output promise * the exception handler will be called with the key that failed and the exception. The output promise
* will always complete successfully regardless of whether input promises fail. * will always complete successfully regardless of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @return the combined promise * @return the combined promise
@@ -143,6 +155,7 @@ public interface PromiseFactory {
* pairs of inputs to outputs when all promises complete. If {@code link} is {@code true} * pairs of inputs to outputs when all promises complete. If {@code link} is {@code true}
* and any promise completes exceptionally, the other promises will be cancelled and the output * and any promise completes exceptionally, the other promises will be cancelled and the output
* promise will complete exceptionally. * promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -155,6 +168,7 @@ public interface PromiseFactory {
* Combines key-value pairs of inputs to promises into a single promise that completes with key-value * Combines key-value pairs of inputs to promises into a single promise that completes with key-value
* pairs of inputs to outputs when all promises complete. If any promise completes exceptionally, * pairs of inputs to outputs when all promises complete. If any promise completes exceptionally,
* the output promise will complete exceptionally. * the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -168,6 +182,7 @@ public interface PromiseFactory {
* other promises will be cancelled and the output promise will complete exceptionally. If an exception * other promises will be cancelled and the output promise will complete exceptionally. If an exception
* handler is present, promises that fail will not cause this behaviour, and instead the exception * handler is present, promises that fail will not cause this behaviour, and instead the exception
* handler will be called with the index that failed and the exception. * handler will be called with the index that failed and the exception.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
@@ -182,6 +197,7 @@ public interface PromiseFactory {
* promises complete. If any promise completes exceptionally, the exception handler will be called with * promises complete. If any promise completes exceptionally, the exception handler will be called with
* the index that failed and the exception. The output promise will always complete successfully regardless * the index that failed and the exception. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @return the combined promise * @return the combined promise
@@ -197,6 +213,7 @@ public interface PromiseFactory {
* promises complete. If any promise completes exceptionally, the exception handler will be called with * promises complete. If any promise completes exceptionally, the exception handler will be called with
* the index that failed and the exception. The output promise will always complete successfully regardless * the index that failed and the exception. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @return the combined promise * @return the combined promise
@@ -210,6 +227,7 @@ public interface PromiseFactory {
* Combines a collection of promises into a single promise that completes with a list of results when all * Combines a collection of promises into a single promise that completes with a list of results when all
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled and the output promise will complete exceptionally. * other promises will be cancelled and the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -221,6 +239,7 @@ public interface PromiseFactory {
/** /**
* Combines a collection of promises into a single promise that completes with a list of results when all * Combines a collection of promises into a single promise that completes with a list of results when all
* promises complete. If any promise completes exceptionally, the output promise will complete exceptionally. * promises complete. If any promise completes exceptionally, the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -234,6 +253,7 @@ public interface PromiseFactory {
* other promises will be cancelled and the output promise will complete exceptionally. If an exception * other promises will be cancelled and the output promise will complete exceptionally. If an exception
* handler is present, promises that fail will not cause this behaviour, and instead the exception * handler is present, promises that fail will not cause this behaviour, and instead the exception
* handler will be called with the index that failed and the exception. * handler will be called with the index that failed and the exception.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
@@ -250,6 +270,7 @@ public interface PromiseFactory {
* promises complete. If any promise completes exceptionally, the exception handler will be called with * promises complete. If any promise completes exceptionally, the exception handler will be called with
* the index that failed and the exception. The output promise will always complete successfully regardless * the index that failed and the exception. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param exceptionHandler the exception handler * @param exceptionHandler the exception handler
* @return the combined promise * @return the combined promise
@@ -263,6 +284,7 @@ public interface PromiseFactory {
* Combines a stream of promises into a single promise that completes with a list of results when all * Combines a stream of promises into a single promise that completes with a list of results when all
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled and the output promise will complete exceptionally. * other promises will be cancelled and the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -274,6 +296,7 @@ public interface PromiseFactory {
/** /**
* Combines a stream of promises into a single promise that completes with a list of results when all * Combines a stream of promises into a single promise that completes with a list of results when all
* promises complete. If any promise completes exceptionally, the output promise will complete exceptionally. * promises complete. If any promise completes exceptionally, the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -286,6 +309,7 @@ public interface PromiseFactory {
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled. The output promise will always complete successfully regardless * other promises will be cancelled. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param expectedSize the expected size of the list (used for optimization) * @param expectedSize the expected size of the list (used for optimization)
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
@@ -299,6 +323,7 @@ public interface PromiseFactory {
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled. The output promise will always complete successfully regardless * other promises will be cancelled. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -311,6 +336,7 @@ public interface PromiseFactory {
/** /**
* Combines a collection of promises into a single promise that completes with a list of results when all * Combines a collection of promises into a single promise that completes with a list of results when all
* promises complete. If any promise completes exceptionally, all other promises will be cancelled. * promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -323,6 +349,7 @@ public interface PromiseFactory {
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled. The output promise will always complete successfully regardless * other promises will be cancelled. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -335,6 +362,7 @@ public interface PromiseFactory {
/** /**
* Combines a stream of promises into a single promise that completes with a list of results when all * Combines a stream of promises into a single promise that completes with a list of results when all
* promises complete. If any promise completes exceptionally, all other promises will be cancelled. * promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -347,6 +375,7 @@ public interface PromiseFactory {
* promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all * promises complete. If {@code link} is {@code true} and any promise completes exceptionally, all
* other promises will be cancelled. The output promise will always complete successfully regardless * other promises will be cancelled. The output promise will always complete successfully regardless
* of whether input promises fail. * of whether input promises fail.
*
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
@@ -359,6 +388,7 @@ public interface PromiseFactory {
/** /**
* Combines an array of promises into a single promise that completes with a list of results when all * Combines an array of promises into a single promise that completes with a list of results when all
* promises complete. If any promise completes exceptionally, all other promises will be cancelled. * promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -370,6 +400,7 @@ public interface PromiseFactory {
* Combines an iterator of promises into a single promise that completes when all promises complete. * Combines an iterator of promises into a single promise that completes when all promises complete.
* If {@code link} is {@code true} and any promise completes exceptionally, all other promises will * If {@code link} is {@code true} and any promise completes exceptionally, all other promises will
* be cancelled and the output promise will complete exceptionally. * be cancelled and the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -380,6 +411,7 @@ public interface PromiseFactory {
* Combines an iterable of promises into a single promise that completes when all promises complete. * Combines an iterable of promises into a single promise that completes when all promises complete.
* If {@code link} is {@code true} and any promise completes exceptionally, all other promises will * If {@code link} is {@code true} and any promise completes exceptionally, all other promises will
* be cancelled and the output promise will complete exceptionally. * be cancelled and the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -392,6 +424,7 @@ public interface PromiseFactory {
* Combines an iterable of promises into a single promise that completes when all promises complete. * Combines an iterable of promises into a single promise that completes when all promises complete.
* If any promise completes exceptionally, all other promises will be cancelled and the output * If any promise completes exceptionally, all other promises will be cancelled and the output
* promise will complete exceptionally. * promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -403,6 +436,7 @@ public interface PromiseFactory {
* Combines a stream of promises into a single promise that completes when all promises complete. * Combines a stream of promises into a single promise that completes when all promises complete.
* If {@code link} is {@code true} and any promise completes exceptionally, all other promises will * If {@code link} is {@code true} and any promise completes exceptionally, all other promises will
* be cancelled and the output promise will complete exceptionally. * be cancelled and the output promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @return the combined promise * @return the combined promise
@@ -415,6 +449,7 @@ public interface PromiseFactory {
* Combines a stream of promises into a single promise that completes when all promises complete. * Combines a stream of promises into a single promise that completes when all promises complete.
* If any promise completes exceptionally, all other promises will be cancelled and the output * If any promise completes exceptionally, all other promises will be cancelled and the output
* promise willcomplete exceptionally. * promise willcomplete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -427,6 +462,7 @@ public interface PromiseFactory {
* If {@code link} is {@code true} and any promise completes exceptionally, all other promises will * If {@code link} is {@code true} and any promise completes exceptionally, all other promises will
* be cancelled * be cancelled
* and the output promise will complete exceptionally. * and the output promise will complete exceptionally.
*
* @param link whether to cancel all promises on any exceptional completions * @param link whether to cancel all promises on any exceptional completions
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
@@ -439,6 +475,7 @@ public interface PromiseFactory {
* Combines an array of promises into a single promise that completes when all promises complete. * Combines an array of promises into a single promise that completes when all promises complete.
* If any promise completes exceptionally, all other promises will be cancelled and the output * If any promise completes exceptionally, all other promises will be cancelled and the output
* promise will complete exceptionally. * promise will complete exceptionally.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -451,6 +488,7 @@ public interface PromiseFactory {
* completes (successfully or exceptionally). If {@code cancelLosers} is {@code true}, all other * completes (successfully or exceptionally). If {@code cancelLosers} is {@code true}, all other
* promises will be cancelled when the first promise * promises will be cancelled when the first promise
* completes. * completes.
*
* @param promises the input promises * @param promises the input promises
* @param cancelLosers whether to cancel the other promises when the first completes * @param cancelLosers whether to cancel the other promises when the first completes
* @return the combined promise * @return the combined promise
@@ -461,6 +499,7 @@ public interface PromiseFactory {
* Combines an iterable of promises into a single promise that completes when the first promise * Combines an iterable of promises into a single promise that completes when the first promise
* completes (successfully or exceptionally). All other promises will be cancelled when the first * completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes. * promise completes.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */
@@ -472,6 +511,7 @@ public interface PromiseFactory {
* Combines an iterable of promises into a single promise that completes when the first promise * Combines an iterable of promises into a single promise that completes when the first promise
* completes (successfully or exceptionally). All other promises will be cancelled when the first * completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes. * promise completes.
*
* @param promises the input promises * @param promises the input promises
*/ */
default <V> @NotNull Promise<V> race(@NotNull Iterable<Promise<V>> promises) { default <V> @NotNull Promise<V> race(@NotNull Iterable<Promise<V>> promises) {
@@ -482,6 +522,7 @@ public interface PromiseFactory {
* Combines a stream of promises into a single promise that completes when the first promise * Combines a stream of promises into a single promise that completes when the first promise
* completes (successfully or exceptionally). If {@code cancelLosers} is {@code true}, all other * completes (successfully or exceptionally). If {@code cancelLosers} is {@code true}, all other
* promises will be cancelled when the first promise completes. * promises will be cancelled when the first promise completes.
*
* @param promises the input promises * @param promises the input promises
* @param cancelLosers whether to cancel the other promises when the first completes * @param cancelLosers whether to cancel the other promises when the first completes
* @return the combined promise * @return the combined promise
@@ -494,6 +535,7 @@ public interface PromiseFactory {
* Combines a stream of promises into a single promise that completes when the first promise * Combines a stream of promises into a single promise that completes when the first promise
* completes (successfully or exceptionally). All other promises will be cancelled when the first * completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes. * promise completes.
*
* @param promises the input promises * @param promises the input promises
* @return the combined promise * @return the combined promise
*/ */

1
futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseListener.java
View File

@@ -9,6 +9,7 @@ public interface PromiseListener<T> {
/** /**
* Handles the completion of the promise. * Handles the completion of the promise.
*
* @param completion the promise completion * @param completion the promise completion
*/ */
void handle(@NotNull PromiseCompletion<T> completion); void handle(@NotNull PromiseCompletion<T> completion);

4
futur-api/src/main/java/dev/tommyjs/futur/util/PromiseUtil.java
View File

@@ -10,6 +10,7 @@ public class PromiseUtil {
/** /**
* Propagates the completion, once completed, of the given promise to the given promise. * Propagates the completion, once completed, of the given promise to the given promise.
*
* @param from the promise to propagate the completion from * @param from the promise to propagate the completion from
* @param to the completable promise to propagate the completion to * @param to the completable promise to propagate the completion to
*/ */
@@ -19,6 +20,7 @@ public class PromiseUtil {
/** /**
* Propagates the cancellation, once cancelled, of the given promise to the given promise. * Propagates the cancellation, once cancelled, of the given promise to the given promise.
*
* @param from the promise to propagate the cancellation from * @param from the promise to propagate the cancellation from
* @param to the promise to propagate the cancellation to * @param to the promise to propagate the cancellation to
*/ */
@@ -28,6 +30,7 @@ public class PromiseUtil {
/** /**
* Cancels the given promise once the given promise is completed. * Cancels the given promise once the given promise is completed.
*
* @param from the promise to propagate the completion from * @param from the promise to propagate the completion from
* @param to the promise to cancel upon completion * @param to the promise to cancel upon completion
*/ */
@@ -37,6 +40,7 @@ public class PromiseUtil {
/** /**
* Estimates the size of the given stream. * Estimates the size of the given stream.
*
* @param stream the stream * @param stream the stream
* @return the estimated size * @return the estimated size
*/ */