Tasks

The Astra framework provides a robust task management system through the TaskManager class. This system allows you to create, schedule, and manage both synchronous and asynchronous tasks with features like priorities, dependencies, and adaptive concurrency.

Basic Usage

Accessing the TaskManager

You can access the TaskManager through the Implements system:

TaskManager taskManager = Implements.fetch(TaskManager.class);

Creating Tasks

// Create a synchronous task
SyncAstraTask syncTask = taskManager.createSyncTask(() -> {
    // Task code here
});

// Create an asynchronous task
AsyncAstraTask asyncTask = taskManager.createAsyncTask(() -> {
    // Task code here
});

// Create tasks with specific IDs
SyncAstraTask namedSyncTask = taskManager.createSyncTask("my-sync-task", () -> {
    // Task code here
});

AsyncAstraTask namedAsyncTask = taskManager.createAsyncTask("my-async-task", () -> {
    // Task code here
});

Running Tasks

// Run a synchronous task immediately
SyncAstraTask task1 = taskManager.runSync(() -> {
    // Task code here
});

// Run an asynchronous task immediately
AsyncAstraTask task2 = taskManager.runAsync(() -> {
    // Task code here
});

// Run a synchronous task with delay
SyncAstraTask task3 = taskManager.runSyncDelayed(() -> {
    // Task code here
}, 20L); // 1 second delay (20 ticks)

// Run an asynchronous task with delay
AsyncAstraTask task4 = taskManager.runAsyncDelayed(() -> {
    // Task code here
}, 20L); // 1 second delay

// Run a repeating synchronous task
SyncAstraTask task5 = taskManager.runSyncRepeating(() -> {
    // Task code here
}, 20L, 40L); // 1 second delay, repeat every 2 seconds

// Run a repeating asynchronous task
AsyncAstraTask task6 = taskManager.runAsyncRepeating(() -> {
    // Task code here
}, 20L, 40L); // 1 second delay, repeat every 2 seconds

Scheduling Tasks

// Create a task
AsyncAstraTask task = taskManager.createAsyncTask(() -> {
    // Task code here
});

// Schedule the task for execution
taskManager.scheduleTask(task);

// Register a task without scheduling
taskManager.registerTask(task);

// Register and optionally schedule a task
taskManager.registerTask(task, true); // true to schedule immediately

Task Callbacks

AsyncAstraTask task = taskManager.createAsyncTask(() -> {
    // Task code here
});

// Add completion callback
task.onComplete(() -> {
    // This runs when the task completes successfully
});

// Add error handler
task.onError(throwable -> {
    // This runs if the task throws an exception
    throwable.printStackTrace();
});

taskManager.scheduleTask(task);

Task Priorities

Tasks can be assigned different priorities to control their execution order:

AsyncAstraTask task = taskManager.createAsyncTask(() -> {
    // Task code here
});

// Set priority (default is NORMAL)
task.setPriority(TaskPriority.HIGH);

taskManager.scheduleTask(task);

Available priorities (from highest to lowest):

• TaskPriority.CRITICAL (value: 0)
• TaskPriority.HIGH (value: 1)
• TaskPriority.NORMAL (value: 2)
• TaskPriority.LOW (value: 3)

Task Dependencies

Tasks can depend on other tasks, ensuring they only execute after their dependencies complete:

// Create first task
AsyncAstraTask firstTask = taskManager.createAsyncTask("first-task", () -> {
    // Task code here
});

// Create second task that depends on the first
AsyncAstraTask secondTask = taskManager.createAsyncTask("second-task", () -> {
    // This will only run after firstTask completes
});

// Add dependency
secondTask.addDependency("first-task");

// Schedule both tasks
taskManager.scheduleTask(firstTask);
taskManager.scheduleTask(secondTask);

Managing Tasks

// Get a task by ID
AstraTask task = taskManager.getTask("my-task-id");

// Execute a specific task by ID
taskManager.executeTask("my-task-id");

// Execute a task directly
taskManager.executeTask(task);

// Cancel a specific task
taskManager.cancelTask("my-task-id");

// Cancel all tasks
taskManager.cancelAllTasks();

Task System Configuration

// Set the server load threshold (0.0 - 1.0)
taskManager.setServerLoadThreshold(0.8);

// Enable/disable adaptive concurrency
taskManager.setAdaptiveConcurrency(true);

// Set maximum concurrent async tasks
taskManager.setMaxConcurrentAsyncTasks(15);

Task Statistics

// Get task system statistics
Map<String, Object> stats = taskManager.getStatistics();

// Available statistics:
// - completedTasks: Number of completed tasks
// - failedTasks: Number of failed tasks
// - pendingTasks: Number of tasks waiting to be executed
// - runningAsyncTasks: Number of currently running async tasks
// - maxConcurrentAsyncTasks: Maximum allowed concurrent async tasks
// - tasksByPriority: Map of task counts by priority
// - serverLoad: Current server load percentage

Adaptive Concurrency

The task system automatically adjusts the number of concurrent asynchronous tasks based on server load:

• When server load is low, more concurrent tasks are allowed (up to 20)
• When server load is high, fewer concurrent tasks are allowed (minimum 2)
• The adjustment is gradual, changing by at most 2 slots at a time

This behavior can be disabled with setAdaptiveConcurrency(false).