Task docs

Author: Avanatiker

common/src/main/kotlin/com/lambda/Lambda.kt

@@ -27,8 +27,9 @@ object Lambda {
             taskContext {
                 HelloWorldTask()
                     .withDelay(500L)
-                    .withTimeout(5000L)
-                    .withRepeats(2)
+                    .withTimeout(200L)
+                    .withRepeats(10)
+                    .withMaxAttempts(5)
                     .onSuccess {
                         LOG.info("Hello, World! Task completed")
                     }.onRepeat { repeats ->

common/src/main/kotlin/com/lambda/event/listener/SafeListener.kt

@@ -64,6 +64,39 @@ class SafeListener(
             return listener
         }
 
+        /**
+         * Registers a new [SafeListener] for a generic [Event] type [T] within the context of a [Task].
+         * The [function] is executed on the same thread where the [Event] was dispatched.
+         * The [function] will only be executed when the context satisfies certain safety conditions.
+         * These conditions are met when none of the following [SafeContext] properties are null:
+         * - [SafeContext.world]
+         * - [SafeContext.player]
+         * - [SafeContext.interaction]
+         * - [SafeContext.connection]
+         *
+         * This listener is special for tasks, as its behavior is
+         * to only listen while the [Task.onAction] function is active / while the task is running.
+         *
+         * Usage:
+         * ```kotlin
+         * myTask.listener<MyEvent> { event ->
+         *     player.sendMessage("Event received: $event")
+         * }
+         *
+         * myTask.listener<MyEvent>(priority = 1) { event ->
+         *     player.sendMessage("Event received before the previous listener: $event")
+         * }
+         * ```
+         *
+         * @param T The type of the event to listen for.
+         * This should be a subclass of Event.
+         * @param priority The priority of the listener.
+         * Listeners with higher priority will be executed first.
+         * Default value is 0.
+         * @param function The function to be executed when the event is posted.
+         * This function should take a SafeContext and an event of type T as parameters.
+         * @return The newly created and registered [SafeListener].
+         */
         inline fun <reified T : Event> Task<*>.listener(priority: Int = 0, noinline function: SafeContext.(T) -> Unit): SafeListener {
             val listener = SafeListener(priority, this) { event ->
                 function(event as T)

common/src/main/kotlin/com/lambda/task/Task.kt

@@ -10,6 +10,33 @@ import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.withTimeout
 
+/**
+ * A [Task] represents a time-critical activity that executes a suspending action function.
+ * It is designed to automate in-game activities without the need for strict event-based programming,
+ * thanks to the use of suspending functions which allow for linear coding.
+ *
+ * A [Task] can have event listeners, but they are only active while the action function is running.
+ *
+ * It supports a builder pattern, allowing you to chain configuration methods like [withDelay],
+ * [withTimeout], [withMaxAttempts], [withRepeats], [onSuccess], [onRetry], [onTimeout], [onFailure], and [onRepeat]
+ * to construct a [Task] instance.
+ * This makes it easy to build complex flows of nested tasks.
+ *
+ * CAUTION: When implementing the `onAction` function,
+ * ensure that the function adheres to thread safety measures.
+ * This includes avoiding write operations on non-synchronized in-game data
+ * unless explicitly running on the game thread using `runSafeOnGameThread { ... }`.
+ *
+ * @property delay The delay before the task starts, in milliseconds.
+ * @property timeout The maximum time that the task is allowed to run, in milliseconds.
+ * @property maxAttempts The maximum number of attempts to execute the task before it is considered failed.
+ * @property repeats The number of times the task should be repeated.
+ * @property onSuccess The action to be performed when the task completes successfully.
+ * @property onRetry The action to be performed when the task is retried after a failure or timeout.
+ * @property onTimeout The action to be performed when the task times out.
+ * @property onRepeat The action to be performed each time the task is repeated.
+ * @property onException The action to be performed when the task encounters an exception.
+ */
 abstract class Task<Result>(
     private var delay: Long = 0L,
     private var timeout: Long = Long.MAX_VALUE,
@@ -21,18 +48,43 @@ abstract class Task<Result>(
     private var onRepeat: (suspend Task<Result>.(Int) -> Unit) = {},
     private var onException: (suspend Task<Result>.(Throwable) -> Unit) = {},
 ) {
+    private val creationTimestamp = System.currentTimeMillis()
+    private val age: Long get() = System.currentTimeMillis() - creationTimestamp
+    open val name: String get() = this::class.simpleName ?: "Task"
+
     val syncListeners = Subscriber()
     private val concurrentListeners = Subscriber()
 
     /**
-     * Make sure to only do read operations on the game thread!
-     * Use `runSafeOnGameThread { ... }` to execute safe write operations on the game thread.
-     * @return The [Result] of the action
+     * Executes the main action of the task.
+     *
+     * This function should only perform read operations on the game thread due to potential concurrency issues.
+     * If write operations are necessary, they should be wrapped in the `runSafeOnGameThread { ... }` function to ensure thread safety.
+     *
+     * @return The result of the action, of type [Result].
      */
     abstract suspend fun SafeContext.onAction(): Result
 
+    /**
+     * This function is called when the task is cancelled.
+     * It should be overridden for tasks that need to perform cleanup operations,
+     * such as cancelling a block breaking progress, releasing resources,
+     * or stopping any ongoing operations that were started by the task.
+     */
     open fun SafeContext.onCancel() {}
 
+    /**
+     * Executes the task with the configured parameters.
+     *
+     * This function will attempt to execute the task for a specified number of attempts and repeats.
+     * It handles delays before task execution, task timeouts, and task cancellations.
+     * It also manages the lifecycle of event listeners associated with the task.
+     *
+     * @return The result of the task execution, represented as a [TaskResult].
+     * This could be a successful result ([TaskResult.Success]), a cancellation ([TaskResult.Cancelled]),
+     * a failure ([TaskResult.Failure]) due to an exception, or a timeout
+     * ([TaskResult.Timeout]).
+     */
     suspend fun execute(): TaskResult<Result> {
         var attempt = 1
         var iteration = 0
@@ -107,50 +159,100 @@ abstract class Task<Result>(
         }
     }
 
-    private val creationTimestamp = System.currentTimeMillis()
-    val age: Long get() = System.currentTimeMillis() - creationTimestamp
-    val name: String get() = this::class.simpleName ?: "Task"
-
+    /**
+     * Sets the delay before the task starts.
+     *
+     * @param delay The delay in milliseconds.
+     * @return This task instance with the updated delay.
+     */
     fun withDelay(delay: Long): Task<Result> {
         this.delay = delay
         return this
     }
 
+    /**
+     * Sets the timeout for a single attempt of the task
+     *
+     * @param timeout The timeout in milliseconds
+     * @return This task instance with the updated timeout.
+     */
     fun withTimeout(timeout: Long): Task<Result> {
         this.timeout = timeout
         return this
     }
 
+    /**
+     * Sets the maximum number of attempts to execute the task before it is considered failed.
+     *
+     * @param maxAttempts The maximum number of attempts.
+     * @return This task instance with the updated maximum attempts.
+     */
     fun withMaxAttempts(maxAttempts: Int): Task<Result> {
         this.maxAttempts = maxAttempts
         return this
     }
 
+    /**
+     * Sets the number of times the task should be repeated.
+     *
+     * @param repeats The number of repeats.
+     * @return This task instance with the updated number of repeats.
+     */
     fun withRepeats(repeats: Int): Task<Result> {
         this.repeats = repeats
         return this
     }
 
+    /**
+     * Sets the action to be performed when the task completes successfully.
+     *
+     * @param action The action to be performed.
+     * @return The task instance with the updated success action.
+     */
     fun onSuccess(action: suspend (Result) -> Unit): Task<Result> {
         this.onSuccess = action
         return this
     }
 
+    /**
+     * Sets the action to be performed when the task is retried after a failure or timeout.
+     *
+     * @param action The action to be performed.
+     * @return The task instance with the updated retry action.
+     */
     fun onRetry(action: suspend Task<Result>.() -> Unit): Task<Result> {
         this.onRetry = action
         return this
     }
 
+    /**
+     * Sets the action to be performed when the task times out.
+     *
+     * @param action The action to be performed.
+     * @return The task instance with the updated timeout action.
+     */
     fun onTimeout(action: suspend Task<Result>.() -> Unit): Task<Result> {
         this.onTimeout = action
         return this
     }
 
+    /**
+     * Sets the action to be performed when the task encounters an exception.
+     *
+     * @param action The action to be performed.
+     * @return The task instance with the updated exception action.
+     */
     fun onFailure(action: suspend Task<Result>.(Throwable) -> Unit): Task<Result> {
         this.onException = action
         return this
     }
 
+    /**
+     * Sets the action to be performed each time the task is repeated.
+     *
+     * @param action The action to be performed.
+     * @return The task instance with the updated repeat action.
+     */
     fun onRepeat(action: suspend Task<Result>.(Int) -> Unit): Task<Result> {
         this.onRepeat = action
         return this

common/src/main/kotlin/com/lambda/task/TaskResult.kt

@@ -1,8 +1,37 @@
 package com.lambda.task
 
+/**
+ * Represents the result of a task.
+ *
+ * @param Result The type of the result value for successful tasks. Covariant type parameter.
+ */
 sealed class TaskResult<out Result> {
+
+    /**
+     * Represents a successful task result.
+     *
+     * @param T The type of the result value.
+     * @property value The result value.
+     */
     data class Success<out T>(val value: T) : TaskResult<T>()
+
+    /**
+     * Represents a failed task result.
+     *
+     * @property throwable The exception that caused the task to fail.
+     */
     data class Failure(val throwable: Throwable) : TaskResult<Nothing>()
+
+    /**
+     * Represents a task result that timed out.
+     *
+     * @property timeout The timeout duration in milliseconds.
+     * @property triesUsed The number of attempts made before the task timed out.
+     */
     data class Timeout(val timeout: Long, val triesUsed: Int) : TaskResult<Nothing>()
+
+    /**
+     * Represents a cancelled task result.
+     */
     data object Cancelled : TaskResult<Nothing>()
 }