feat: Added docs to async stuff

Author: julian-siebert

src/main/java/gentle/async/AsyncError.java

@@ -4,11 +4,22 @@
 import lombok.NonNull;
 
 public record AsyncError(@NonNull Throwable throwable) implements Error {
+
+    /**
+     * Returns a numeric code for this error.
+     *
+     * @return error code
+     */
     @Override
     public int code() {
         return 1;
     }
 
+    /**
+     * Returns a human-readable message describing the error.
+     *
+     * @return error message
+     */
     @Override
     public @NonNull String message() {
         return throwable.getMessage();

src/main/java/gentle/async/Scope.java

@@ -1,40 +1,143 @@
 package gentle.async;
 
+import gentle.Result;
 import lombok.AccessLevel;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.concurrent.Callable;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
+import java.util.concurrent.*;
 
+/**
+ * A structured concurrency scope for managing asynchronous tasks.
+ * <p>
+ * The {@code Scope} allows creating and managing multiple asynchronous {@link Task tasks} in a single
+ * logical scope. All tasks are automatically cancelled when the scope is closed.
+ *
+ * <p>Typical usage:
+ * <pre>{@code
+ * try (Scope scope = Scope.open()) {
+ *     Task<String> t1 = scope.async(() -> "Hello");
+ *     Task<Integer> t2 = scope.async(() -> 42);
+ *
+ *     System.out.println(t1.await());
+ *     System.out.println(t2.await());
+ * }
+ * }</pre>
+ */
 @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
 public final class Scope implements AutoCloseable {
+    private static final ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(Utils.cores);
+
+    /** ExecutorService used for running tasks in this scope. */
     private final ExecutorService executor;
+
+    /** List of tasks created in this scope. */
     private final List<Task<?>> tasks = new ArrayList<>();
+
+    /** Indicates whether this scope has been closed. */
     private volatile boolean closed = false;
 
+    /**
+     * Opens a new scope with a cached thread pool.
+     *
+     * @return a new {@code Scope}
+     */
     public static Scope open() {
         return new Scope(Executors.newCachedThreadPool());
     }
 
+    /**
+     * Opens a new scope using a custom {@link ExecutorService}.
+     *
+     * @param executor the executor to run tasks
+     * @return a new {@code Scope}
+     */
     public static Scope open(@NonNull ExecutorService executor) {
         return new Scope(executor);
     }
 
+    /**
+     * Submits a new asynchronous {@link Task} to this scope.
+     * <p>
+     * The task is automatically cancelled when the scope is closed.
+     *
+     * @param supplier the task to execute
+     * @param <T>      the type of the task result
+     * @return a {@link Task} representing the asynchronous computation
+     * @throws IllegalStateException if the scope is already closed
+     */
     public synchronized <T> Task<T> async(@NonNull Callable<T> supplier) {
         if (closed) throw new IllegalStateException("Scope already closed");
         Task<T> task = new Task<>(executor.submit(supplier));
         tasks.add(task);
         return task;
     }
 
+    /**
+     * Submits a new asynchronous {@link Task} to this scope that will start after a specified delay.
+     * <p>
+     * The task is scheduled using a shared {@link ScheduledExecutorService}. When the delay elapses,
+     * the {@code supplier} is executed and the result is completed in the returned {@link Task}.
+     * The task is automatically cancelled if the scope is closed before it executes.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * try (Scope scope = Scope.open()) {
+     *     Task<String> delayedTask = scope.delayed(Duration.ofSeconds(2), () -> "Hello after 2s");
+     *     System.out.println(delayedTask.await());
+     * }
+     * }</pre>
+     *
+     * @param delay    the delay after which the task should execute
+     * @param supplier the task to execute after the delay
+     * @param <T>      the type of the task result
+     * @return a {@link Task} representing the delayed asynchronous computation
+     * @throws IllegalStateException if the scope has already been closed
+     */
+    public synchronized  <T> Task<T> delayed(@NonNull Duration delay, @NonNull Callable<T> supplier) {
+        if (closed) throw new IllegalStateException("Scope already closed");
+
+        CompletableFuture<T> future = new CompletableFuture<>();
+        ScheduledFuture<?> scheduled = scheduler.schedule(() -> {
+            try {
+                future.complete(supplier.call());
+            } catch (Throwable t) {
+                future.completeExceptionally(t);
+            }
+        }, delay.toMillis(), TimeUnit.MILLISECONDS);
+
+        Task<T> task = new Task<>(future) {
+            @Override
+            public void cancel() {
+                scheduled.cancel(true);
+                super.cancel();
+            }
+        };
+
+        tasks.add(task);
+        return task;
+    }
+
+    /**
+     * Returns the number of tasks currently tracked by this scope.
+     *
+     * @return number of tasks
+     */
     public synchronized int size() {
         return tasks.size();
     }
 
+    /**
+     * Closes the scope.
+     * <p>
+     * Cancels all tasks and shuts down the executor. If multiple tasks throw exceptions during
+     * cancellation, the first exception is rethrown and subsequent exceptions are suppressed.
+     *
+     * @throws Exception if any task cancellation or shutdown fails
+     */
     @Override
     public void close() throws Exception {
         List<Throwable> errors = new ArrayList<>();

src/main/java/gentle/async/Task.java

@@ -13,23 +13,52 @@
 import static gentle.Result.err;
 import static gentle.Result.ok;
 
+/**
+ * Represents a single asynchronous task running inside a {@link Scope}.
+ *
+ * <p>Provides methods to cancel the task, check status, and retrieve results
+ * in a type-safe {@link Result} wrapper.
+ *
+ * @param <T> type of the task's result
+ */
 @RequiredArgsConstructor (access = AccessLevel.PACKAGE)
-public final class Task<T> {
+public class Task<T> {
+
+    /** The underlying future representing the task computation. */
     private final Future<T> future;
 
+    /**
+     * Cancels the task.
+     */
     public void cancel() {
         future.cancel(true);
     }
 
+    /**
+     * Returns {@code true} if the task was cancelled.
+     *
+     * @return whether the task is cancelled
+     */
     public boolean isCancelled() {
         return future.isCancelled();
     }
 
+    /**
+     * Returns {@code true} if the task is done (completed or cancelled).
+     *
+     * @return whether the task is done
+     */
     public boolean isDone() {
         return future.isDone();
     }
 
-    public Result<T, AsyncError> await() {
+    /**
+     * Waits for the task to complete and returns a {@link Result} containing either the value
+     * or an {@link AsyncError}.
+     *
+     * @return the result of the task
+     */
+    public final Result<T, AsyncError> await() {
         try {
             return ok(future.get());
         } catch (CancellationException | ExecutionException exception) {
@@ -40,11 +69,25 @@ public Result<T, AsyncError> await() {
         }
     }
 
-    public <U> Result<U, AsyncError> map(@NonNull Function<? super T, ? extends U> f) {
+    /**
+     * Transforms the result of this task using the provided function if successful.
+     *
+     * @param f   mapping function
+     * @param <U> result type of the mapping
+     * @return a {@link Result} with the transformed value or the original error
+     */
+    public final <U> Result<U, AsyncError> map(@NonNull Function<? super T, ? extends U> f) {
         return await().map(f);
     }
 
-    public <U> Result<U, AsyncError> flatMap(@NonNull Function<? super T, ? extends Result<U, AsyncError>> f) {
+    /**
+     * Transforms the result of this task using a function returning a {@link Result}.
+     *
+     * @param f   mapping function
+     * @param <U> result type of the mapping
+     * @return the {@link Result} returned by the mapping function or the original error
+     */
+    public final <U> Result<U, AsyncError> flatMap(@NonNull Function<? super T, ? extends Result<U, AsyncError>> f) {
         return await().flatMap(f);
     }
 }

src/main/java/gentle/async/Utils.java

@@ -0,0 +1,13 @@
+package gentle.async;
+
+import lombok.experimental.UtilityClass;
+
+@UtilityClass
+class Utils {
+
+    final int cores;
+
+    static {
+        cores = Runtime.getRuntime().availableProcessors();
+    }
+}