diff --git a/README.md b/README.md index 1b09a96..8e94b11 100644 --- a/README.md +++ b/README.md @@ -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. -**This documentation is outdated. Please don't read it.** - ## 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 repositories { @@ -51,4 +50,4 @@ dependencies { 2.4.0 -``` +``` \ No newline at end of file diff --git a/futur-api/src/main/java/dev/tommyjs/futur/executor/PromiseExecutor.java b/futur-api/src/main/java/dev/tommyjs/futur/executor/PromiseExecutor.java index bb9fe03..a66d07f 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/executor/PromiseExecutor.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/executor/PromiseExecutor.java @@ -10,6 +10,7 @@ public interface PromiseExecutor { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { * * @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); diff --git a/futur-api/src/main/java/dev/tommyjs/futur/promise/CompletablePromise.java b/futur-api/src/main/java/dev/tommyjs/futur/promise/CompletablePromise.java index 3baff14..998566a 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/promise/CompletablePromise.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/promise/CompletablePromise.java @@ -10,12 +10,14 @@ public interface CompletablePromise extends Promise { /** * 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); diff --git a/futur-api/src/main/java/dev/tommyjs/futur/promise/Promise.java b/futur-api/src/main/java/dev/tommyjs/futur/promise/Promise.java index 1cab047..4cbba54 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/promise/Promise.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/promise/Promise.java @@ -38,7 +38,8 @@ public interface Promise { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { * 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 { * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * 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 { * 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 { * 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 { /** * 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 { /** * 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 { /** * 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 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 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 { 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 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 { /** * 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 { * 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 { /** * 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 { /** * 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 { /** * 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 fork(); @@ -507,12 +546,14 @@ public interface Promise { /** * 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 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 { /** * 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 toFuture(); diff --git a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseCompletion.java b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseCompletion.java index 2af014f..7ca6e9f 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseCompletion.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseCompletion.java @@ -15,6 +15,7 @@ public class PromiseCompletion { /** * Creates a new successful completion. + * * @param result the result */ public PromiseCompletion(@Nullable T result) { @@ -23,6 +24,7 @@ public class PromiseCompletion { /** * Creates a new exceptional completion. + * * @param exception the exception */ public PromiseCompletion(@NotNull Throwable exception) { @@ -38,6 +40,7 @@ public class PromiseCompletion { /** * 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 { /** * 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 { /** * 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 { /** * 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 { /** * Gets the exception of the completion. + * * @return the exception, or {@code null} if the completion was successful */ public @Nullable Throwable getException() { diff --git a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseFactory.java b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseFactory.java index 8aac38f..33ed594 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseFactory.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseFactory.java @@ -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 */ @NotNull CompletablePromise 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 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 */ @NotNull Promise> combine(@NotNull Map> 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 @NotNull Promise> combine(@NotNull Map> 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 */ @NotNull Promise> combine(@NotNull Iterator> 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 @NotNull Promise> combine(@NotNull Collection> 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 @NotNull Promise> combine(@NotNull Stream> 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 @NotNull Promise> combine(@NotNull Stream> 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>> allSettled(@NotNull Iterator> 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>> allSettled(@NotNull Collection> 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>> allSettled(@NotNull Stream> 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 all(@NotNull Iterator> 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 all(@NotNull Iterable> 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 all(@NotNull Stream> 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 @NotNull Promise race(@NotNull Iterable> 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 */ diff --git a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseListener.java b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseListener.java index 85b09af..18666f1 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseListener.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/promise/PromiseListener.java @@ -9,6 +9,7 @@ public interface PromiseListener { /** * Handles the completion of the promise. + * * @param completion the promise completion */ void handle(@NotNull PromiseCompletion completion); diff --git a/futur-api/src/main/java/dev/tommyjs/futur/util/PromiseUtil.java b/futur-api/src/main/java/dev/tommyjs/futur/util/PromiseUtil.java index 152c67c..25895b8 100644 --- a/futur-api/src/main/java/dev/tommyjs/futur/util/PromiseUtil.java +++ b/futur-api/src/main/java/dev/tommyjs/futur/util/PromiseUtil.java @@ -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 void propagateCompletion(@NotNull Promise from, @NotNull CompletablePromise 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 */