Using the Scheduler - rodrigoo-r/Harmony GitHub Wiki

Explanation

Harmony uses its own scheduler for tasks. This is because it adds support for Folia's scheduler.

To get the scheduler, just use the findScheduler() method inside the BackendPlugin instance.

Example:

public final class GreenShield extends BackendPlugin {

    @Override
    public void whenInitialize() {
        final NormalizedScheduler schedudler = findScheduler();
        // Do something
    }

    @Override
    public void whenUnloaded() {
        // Plugin shutdown logic
    }
}

This scheduler is kinda different to the normal scheduler, if you're running Folia, all tasks will execute asynchronously. However, if you're using Spigot/Paper or any server that isn't Folia, the tasks are going to be executed synchronously if you don't run them asynchronously.

Equivalents

Normalized Schedulers have the following methods:

run() - Runs a task (Sync)
runLater() - Runs a task with a delay (Sync)
runTimer() - Runs a timer (Sync)
runAsync() - Runs a task (Async)
runAsyncLater() - Runs a task with a delay (Async)
runAsyncTimer() - Runs a timer (Async)

For you to understand how this works, here are the equivalents with Spigot Scheduler API

run() is runTask() from Spigot Scheduler
runLater() is runTaskLater() from Spigot Scheduler
runTimer() is runTaskTimer() from Spigot Scheduler
runAsync() is runTaskAsynchronously() from Spigot Scheduler
runAsyncLater() is runTaskLaterAsynchronously() from Spigot Scheduler
runAsyncTimer() is runTaskTimerAsynchronously() from Spigot Scheduler

You can also read the Scheduler Programming tutorial from Spigot

As said, all of those methods will execute asynchronously if the server is running Folia, but they won't if the server isn't running Folia.

Examples

Run a task (Synchronously, but Async if the server is Folia)

final NormalizedScheduler scheduler = findScheduler();
scheduler.run(() -> logger.info("Hello World!"));

Run a task (Asynchronously)

final NormalizedScheduler scheduler = findScheduler();
scheduler.runAsync(() -> logger.info("Hello World!"));

Run a delayed task (Synchronously, but Async if the server is Folia)

final NormalizedScheduler scheduler = findScheduler();
scheduler.runLater(() -> logger.info("Hello World!"), 20);

Considerations: The numeric parameter is the delay in ticks. Where every 20 ticks means 1 real second. (In this example, the task will run after a second)

Run a delayed task (Asynchronously)

final NormalizedScheduler scheduler = findScheduler();
scheduler.runAsyncLater(() -> logger.info("Hello World!"), 20);

Considerations: The numeric parameter is the delay in ticks. Where every 20 ticks means 1 real second. (In this example, the task will run after a second)

Run a timer task (Synchronously, but Async if the server is Folia)

final NormalizedScheduler scheduler = findScheduler();
scheduler.runTimer(() -> logger.info("Hello World!"), 20, 20);

Considerations: The numeric parameters are ticks as said. The first parameter is the ticks the task will be delayed (i.e. if it is 20 ticks, the task will start running after 1 second), and the second parameter is the interval for the task (in ticks too).

Run a timer task (Asynchronously)

final NormalizedScheduler scheduler = findScheduler();
scheduler.runAsyncTimer(() -> logger.info("Hello World!"), 20, 20);

Cancelling tasks

Every method returns a NormalizedTask, where you can call the cancel method or checking if the task is cancelled with the isCancelled method. Example:

final NormalizedScheduler scheduler = findScheduler();
final NormalizedTask task = scheduler.runAsync(() -> logger.info("Hello World!"));

task.cancel();