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

12
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.
*
* @return the new executor
*/
static PromiseExecutor<?> virtualThreaded() {
@@ -18,6 +19,7 @@ public interface PromiseExecutor<T> {
/**
* Creates a new {@link PromiseExecutor} that runs tasks on a single thread.
*
* @return the new executor
*/
static PromiseExecutor<?> singleThreaded() {
@@ -26,6 +28,7 @@ public interface PromiseExecutor<T> {
/**
* Creates a new {@link PromiseExecutor} that runs tasks on multiple threads.
*
* @param threads the number of threads
* @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.
*
* @param service the executor service
* @return the new executor
*/
@@ -44,6 +48,7 @@ public interface PromiseExecutor<T> {
/**
* Runs the given task.
*
* @param task the task
* @return the task
* @throws Exception if scheduling the task failed
@@ -52,9 +57,10 @@ public interface PromiseExecutor<T> {
/**
* Runs the given task after the given delay.
* @param task the task
*
* @param task the task
* @param delay the delay
* @param unit the time unit
* @param unit the time unit
* @return the task
* @throws Exception if scheduling the task failed
*/
@@ -65,7 +71,7 @@ public interface PromiseExecutor<T> {
*
* @param task the task
* @return {@code true} if the task was cancelled. {@code false} if the task was already completed
* or could not be cancelled.
* or could not be cancelled.
*/
boolean cancel(T task);

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.
*
* @param result the result
*/
void complete(@Nullable T result);
/**
* Completes the promise exceptionally with the given exception.
*
* @param result the exception
*/
void completeExceptionally(@NotNull Throwable result);

120
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
* 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
* @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
* 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
* @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
* 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
* @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
* 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
* @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
* 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
* @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
* 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
* @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
* 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 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
* 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
* @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
* 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 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
* 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
* @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
* 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 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
* 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
* 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
* @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
* 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
* 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 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
* 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
* @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
* 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
* @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
* 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 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
* 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
* @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
* 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 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
* 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
* @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
* 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 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
* 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
* 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
* @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
* 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
* 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 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
* 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
* @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
* 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
* @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
* 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();
/**
* 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
*/
@@ -308,14 +347,6 @@ public interface Promise<T> {
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,
* 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
* an exceptional completion with a {@link CancellationException}.
*
* @param ms the amount of time to wait before cancelling the promise (in milliseconds)
* @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
* in an exceptional completion with a {@link TimeoutException}. This will not result in the
* promise being cancelled.
*
* @param ms the amount of time to wait before timing out the promise (in milliseconds)
* @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
* an exceptional completion with the specified cancellation.
*
* @param exception the cancellation exception to complete the promise with
*/
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
* an exceptional completion with a {@link CancellationException}.
*
* @param reason the reason for the cancellation
*/
default void cancel(@NotNull String reason) {
@@ -467,39 +502,43 @@ public interface Promise<T> {
/**
* 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 CompletionException if the promise completed exceptionally
* @return the result of the promise
*/
@Blocking
T await();
/**
* 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 ExecutionException if the promise completed exceptionally
* @throws InterruptedException if the current thread was interrupted while waiting
* @return the result of the promise
*/
@Blocking
T get() throws InterruptedException, ExecutionException;
/**
* Blocks until either this promise has completed or the timeout has been exceeded, and then
* returns its result, if available.
* Blocks until either this promise has completed or the timeout has been exceeded, and then
* returns its result, if available.
*
* @return the result of the promise
* @throws CancellationException if the promise was cancelled
* @throws ExecutionException if the promise completed exceptionally
* @throws InterruptedException if the current thread was interrupted while waiting
* @throws TimeoutException if the timeout was exceeded
* @return the result of the promise
*/
@Blocking
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
* 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.
* that if the returned promise is cancelled, the cancellation will not be propagated to this promise,
* and consequently any previous promises in the chain.
*
* @return continuation the promise chain that will not propagate cancellations
*/
@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
* will return {@code null}.
*
* @return the completion state of this promise, or {@code null} if the promise has not completed
*/
@Nullable PromiseCompletion<T> getCompletion();
/**
* Returns whether this promise has completed.
*
* @return {@code true} if the promise has completed, {@code false} otherwise
*/
boolean isCompleted();
@@ -520,6 +561,7 @@ public interface Promise<T> {
/**
* Converts this promise to a {@link CompletableFuture}. The returned future will complete with the
* result of this promise when it completes.
*
* @return a future that will complete with the result of this promise
*/
@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.
*
* @param result the result
*/
public PromiseCompletion(@Nullable T result) {
@@ -23,6 +24,7 @@ public class PromiseCompletion<T> {
/**
* Creates a new exceptional completion.
*
* @param exception the exception
*/
public PromiseCompletion(@NotNull Throwable exception) {
@@ -38,6 +40,7 @@ public class PromiseCompletion<T> {
/**
* Checks if the completion was successful.
*
* @return {@code true} if the completion was successful, {@code false} otherwise
*/
public boolean isSuccess() {
@@ -46,6 +49,7 @@ public class PromiseCompletion<T> {
/**
* Checks if the completion was exceptional.
*
* @return {@code true} if the completion was exceptional, {@code false} otherwise
*/
public boolean isError() {
@@ -54,6 +58,7 @@ public class PromiseCompletion<T> {
/**
* Checks if the completion was cancelled.
*
* @return {@code true} if the completion was cancelled, {@code false} otherwise
*/
public boolean wasCancelled() {
@@ -67,6 +72,7 @@ public class PromiseCompletion<T> {
/**
* Gets the result of the completion.
*
* @return the result, or {@code null} if the completion was exceptional
*/
public @Nullable T getResult() {
@@ -75,6 +81,7 @@ public class PromiseCompletion<T> {
/**
* Gets the exception of the completion.
*
* @return the exception, or {@code null} if the completion was successful
*/
public @Nullable Throwable getException() {

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

@@ -16,8 +16,9 @@ public interface PromiseFactory {
/**
* Creates a new {@link PromiseFactory} with the given logger and executors.
* @param logger the logger
* @param syncExecutor the synchronous executor
*
* @param logger the logger
* @param syncExecutor the synchronous executor
* @param asyncExecutor the asynchronous executor
* @return the new promise factory
*/
@@ -28,7 +29,8 @@ public interface PromiseFactory {
/**
* Creates a new {@link PromiseFactory} with the given logger and dual executor.
* @param logger the logger
*
* @param logger the logger
* @param executor the executor
* @return the new promise factory
*/
@@ -38,7 +40,8 @@ public interface PromiseFactory {
/**
* Creates a new {@link PromiseFactory} with the given logger and executor.
* @param logger the logger
*
* @param logger the logger
* @param executor the executor
* @return the new promise factory
*/
@@ -48,12 +51,14 @@ public interface PromiseFactory {
/**
* Creates a new uncompleted promise.
*
* @return the new promise
*/
<T> @NotNull CompletablePromise<T> unresolved();
/**
* Creates a new promise, completed with the given value.
*
* @param value the value to complete the promise with
* @return the new promise
*/
@@ -61,8 +66,9 @@ public interface PromiseFactory {
/**
* Creates a new promise, completed with {@code null}.
* @apiNote This method is often useful for starting promise chains.
*
* @return the new promise
* @apiNote This method is often useful for starting promise chains.
*/
default @NotNull Promise<Void> start() {
return resolve(null);
@@ -70,6 +76,7 @@ public interface PromiseFactory {
/**
* Creates a new promise, completed exceptionally with the given error.
*
* @param error the error to complete the promise with
* @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
* of the future.
*
* @param future the future to wrap
* @return the new promise
*/
@@ -88,8 +96,9 @@ public interface PromiseFactory {
* {@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
* exceptionally.
* @param p1 the first promise
* @param p2 the second promise
*
* @param p1 the first promise
* @param p2 the second promise
* @param link whether to cancel the other promise on error
* @return the combined promise
*/
@@ -100,6 +109,7 @@ public interface PromiseFactory {
* 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
* will complete exceptionally.
*
* @param p1 the first promise
* @param p2 the second promise
* @return the combined promise
@@ -115,9 +125,10 @@ public interface PromiseFactory {
* 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
* that failed and the exception.
* @param promises the input promises
*
* @param promises the input promises
* @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
* @return the combined promise
*/
<K, V> @NotNull Promise<Map<K, V>> combine(@NotNull Map<K, Promise<V>> promises,
@@ -129,7 +140,8 @@ public interface PromiseFactory {
* 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
* 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
* @return the combined promise
*/
@@ -143,8 +155,9 @@ public interface PromiseFactory {
* 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
* promise will complete exceptionally.
*
* @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
*/
default <K, V> @NotNull Promise<Map<K, V>> combine(@NotNull Map<K, Promise<V>> promises, boolean link) {
@@ -155,6 +168,7 @@ public interface PromiseFactory {
* 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,
* the output promise will complete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -168,9 +182,10 @@ public interface PromiseFactory {
* 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 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 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
*/
<V> @NotNull Promise<List<V>> combine(@NotNull Iterator<Promise<V>> promises, int expectedSize,
@@ -182,7 +197,8 @@ public interface PromiseFactory {
* 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
* of whether input promises fail.
* @param promises the input promises
*
* @param promises the input promises
* @param exceptionHandler the exception handler
* @return the combined promise
*/
@@ -197,7 +213,8 @@ public interface PromiseFactory {
* 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
* of whether input promises fail.
* @param promises the input promises
*
* @param promises the input promises
* @param exceptionHandler the exception handler
* @return the combined promise
*/
@@ -210,8 +227,9 @@ public interface PromiseFactory {
* 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
* other promises will be cancelled and the output promise will complete exceptionally.
*
* @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
*/
default <V> @NotNull Promise<List<V>> combine(@NotNull Collection<Promise<V>> promises, boolean link) {
@@ -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
* promises complete. If any promise completes exceptionally, the output promise will complete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -234,9 +253,10 @@ public interface PromiseFactory {
* 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 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 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
*/
default <V> @NotNull Promise<List<V>> combine(@NotNull Stream<Promise<V>> promises,
@@ -250,7 +270,8 @@ public interface PromiseFactory {
* 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
* of whether input promises fail.
* @param promises the input promises
*
* @param promises the input promises
* @param exceptionHandler the exception handler
* @return the combined promise
*/
@@ -263,8 +284,9 @@ public interface PromiseFactory {
* 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
* other promises will be cancelled and the output promise will complete exceptionally.
*
* @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
*/
default <V> @NotNull Promise<List<V>> combine(@NotNull Stream<Promise<V>> promises, boolean link) {
@@ -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
* promises complete. If any promise completes exceptionally, the output promise will complete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -286,9 +309,10 @@ public interface PromiseFactory {
* 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
* 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 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
*/
@NotNull Promise<List<PromiseCompletion<?>>> allSettled(@NotNull Iterator<Promise<?>> promises,
@@ -299,8 +323,9 @@ public interface PromiseFactory {
* 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
* of whether input promises fail.
*
* @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
*/
default @NotNull Promise<List<PromiseCompletion<?>>> allSettled(@NotNull Collection<Promise<?>> promises,
@@ -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
* promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -323,8 +349,9 @@ public interface PromiseFactory {
* 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
* of whether input promises fail.
*
* @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
*/
default @NotNull Promise<List<PromiseCompletion<?>>> allSettled(@NotNull Stream<Promise<?>> promises,
@@ -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
* promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -347,7 +375,8 @@ public interface PromiseFactory {
* 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
* 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
* @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
* promises complete. If any promise completes exceptionally, all other promises will be cancelled.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -370,8 +400,9 @@ public interface PromiseFactory {
* 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
* be cancelled and the output promise will complete exceptionally.
*
* @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
*/
@NotNull Promise<Void> all(@NotNull Iterator<Promise<?>> promises, boolean link);
@@ -380,8 +411,9 @@ public interface PromiseFactory {
* 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
* be cancelled and the output promise will complete exceptionally.
*
* @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
*/
default @NotNull Promise<Void> all(@NotNull Iterable<Promise<?>> promises, boolean link) {
@@ -392,6 +424,7 @@ public interface PromiseFactory {
* 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
* promise will complete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -403,8 +436,9 @@ public interface PromiseFactory {
* 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
* be cancelled and the output promise will complete exceptionally.
*
* @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
*/
default @NotNull Promise<Void> all(@NotNull Stream<Promise<?>> promises, boolean link) {
@@ -415,6 +449,7 @@ public interface PromiseFactory {
* 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
* promise willcomplete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -427,7 +462,8 @@ public interface PromiseFactory {
* If {@code link} is {@code true} and any promise completes exceptionally, all other promises will
* be cancelled
* 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
* @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.
* If any promise completes exceptionally, all other promises will be cancelled and the output
* promise will complete exceptionally.
*
* @param promises the input promises
* @return the combined promise
*/
@@ -451,7 +488,8 @@ public interface PromiseFactory {
* completes (successfully or exceptionally). If {@code cancelLosers} is {@code true}, all other
* 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
* @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
* completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes.
*
* @param promises the input promises
* @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
* completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes.
*
* @param promises the input promises
*/
default <V> @NotNull Promise<V> race(@NotNull Iterable<Promise<V>> promises) {
@@ -482,7 +522,8 @@ public interface PromiseFactory {
* 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
* 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
* @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
* completes (successfully or exceptionally). All other promises will be cancelled when the first
* promise completes.
*
* @param promises the input promises
* @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.
*
* @param completion the promise completion
*/
void handle(@NotNull PromiseCompletion<T> completion);

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

@@ -10,8 +10,9 @@ public class PromiseUtil {
/**
* Propagates the completion, once completed, of the given promise to the given promise.
*
* @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
*/
public static <V> void propagateCompletion(@NotNull Promise<V> from, @NotNull CompletablePromise<V> to) {
from.addDirectListener(to::complete, to::completeExceptionally);
@@ -19,8 +20,9 @@ public class PromiseUtil {
/**
* Propagates the cancellation, once cancelled, of the given promise to the given promise.
*
* @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
*/
public static void propagateCancel(@NotNull Promise<?> from, @NotNull Promise<?> to) {
from.onCancel(to::cancel);
@@ -28,8 +30,9 @@ public class PromiseUtil {
/**
* Cancels the given promise once the given promise is completed.
*
* @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
*/
public static void cancelOnComplete(@NotNull Promise<?> from, @NotNull Promise<?> to) {
from.addDirectListener(_ -> to.cancel());
@@ -37,6 +40,7 @@ public class PromiseUtil {
/**
* Estimates the size of the given stream.
*
* @param stream the stream
* @return the estimated size
*/