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