Scheduler

Avertissement

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

Sponge dispose d’un Scheduler qui vous permet de désigner des tâches à exécuter plus tard. Le Scheduler fournit un Task.Builder avec lequel vous pouvez spécifier les propriétés de la tâche telles que le délai, l’intervalle, le nom, la/l”(a)synchronicité, et le Runnable (voir Propriétés d’une tâche).

Constructeur de Tâche

Tout d’abord, obtenez une instance de Task.Builder:

import org.spongepowered.api.scheduler.Task;

Task.Builder taskBuilder = Task.builder();

La seule propriété requise est le Runnable, que vous pouvez spécifier en utilisant la méthode Task.Builder#execute(Runnable):

taskBuilder.execute(new Runnable() {
    public void run() {
        logger.info("Yay! Schedulers!");
    }
});

ou en utilisant la syntaxe de Java 8 avec Task.Builder#execute(Runnable runnable)

taskBuilder.execute(
    () -> {
        logger.info("Yay! Schedulers!");
    }
);

ou en utilisant la syntaxe de Java 8 avec Task.Builder#execute(Consumer<Task> task)

taskBuilder.execute(
    task -> {
        logger.info("Yay! Schedulers! :" + task.getName());
    }
);

Propriétés d’une tâche

En utilisant le Task.Builder, vous pouvez spécifier d’autres propriétés optionnelles, comme décrit ci-dessous.

Propriété

Méthode Utilisée

Description

delay

delayTicks(long delay)

delay(long delay,

TimeUnit unit)

Le montant optionnel de temps avant que la tâche soit exécutée.

Le temps est spécifié en nombre de ticks avec la méthode delayTicks(), ou il peut être communiqué en unité de temps plus commode en spécifiant un TimeUnit avec la méthode delay().

Chacune de ces méthodes, mais pas les deux, peuvent être spécifiées par tâche.

interval

intervalTicks(

long interval)

interval(long interval,

TimeUnit unit)

Le montant de temps entre la répétition de la tâche. Si une intervalle n’est pas spécifiée, la tâche ne sera pas répétée.

Le temps est spécifié en nombre de ticks avec la méthode intervalTicks(), ou il peut être communiqué en unité de temps plus commode en spécifiant un TimeUnit avec la méthode interval().

Chacune de ces méthodes, mais pas les deux, peuvent être spécifiées par tâche.

synchronization

async()

Une tâche synchrone est lancée dans la boucle principale du jeu en série avec le cycle de tick. Si la méthode Task.Builder#async est utilisée, la tâche sera lancée de manière asynchrone. En conséquence, elle sera effectuée dans son propre thread, indépendamment du cycle de tick, et ne pourrait pas être thread-safe avec les données de jeu. (Voir Tâches asynchrones.)

name

name(String name)

La nom de la tâche. Par défaut, le nom d’une tâche sera PLUGIN_ID « - » ( « A- » | « S- » ) SERIAL_ID. Par exemple, le nom par défaut d’une tâche pourrait ressembler à « fooplugin-A-12 ». Deux tâches actives ne pourront pas avoir le même serial ID pour le même type de synchronisation. Si un nom de tâche est spécifié, il devrait être descriptif et aider les utilisateurs à déboguer votre plugin.

Enfin, validez la tâche dans le scheduler, en utilisant la méthode Task.Builder#submit(Object).

Et c’est tout! Pour résumer, une tâche planifiée totalement fonctionnelle qui se lancerait toutes les 5 minutes après un délai initial de 100 millisecondes pourrait être construite et validée en utilisant le code suivant:

import java.util.concurrent.TimeUnit;

PluginContainer plugin = ...;

Task task = Task.builder().execute(() -> logger.info("Yay! Schedulers!"))
    .async().delay(100, TimeUnit.MILLISECONDS).interval(5, TimeUnit.MINUTES)
    .name("ExamplePlugin - Fetch Stats from Database").submit(plugin);

Pour annuler une tâche, utilisez simplement la méthode Task#cancel():

task.cancel();

Si vous devez annuler la tâche à partir de l’exécutable lui-même, vous pouvez plutôt opter pour l’utilisation d’un Consumer<Task> afin d’accéder à la tâche. L’exemple ci-dessous va planifier une tâche qui va compter à rebours depuis 60 et s’annuler elle-même en arrivant à 0.

@Listener
public void onGameInit(GameInitializationEvent event) {
    Task task = Task.builder().execute(new CancellingTimerTask())
        .interval(1, TimeUnit.SECONDS)
        .name("Self-Cancelling Timer Task").submit(plugin);
}

private class CancellingTimerTask implements Consumer<Task> {
    private int seconds = 60;
    @Override
    public void accept(Task task) {
        seconds--;
        Sponge.getServer()
            .getBroadcastChannel()
            .send(Component.text("Remaining Time: "+seconds+"s"));
        if (seconds < 1) {
            task.cancel();
        }
    }
}

Avertissement

Toutes les tâches planifiées doivent soit regarder l”état actuel du Game, ou doit être désinscrit du registre si ils ne sont plus nécessaires (ex : lors d’un GameStoppingServerEvent). C’est d’une importance particulière pour le client car il peut démarrer et arrêter le serveur plusieurs fois.

Tâches asynchrones

Les tâches asynchrones devraient être principalement utilisées pour un code qui mettrait un temps significatif à s’exécuter, à savoir des requêtes vers un autre serveur ou vers une base de données. Si cela est fait sur le thread principal, une requête vers un autre serveur pourrait grandement impacter les performances du jeu, puisque le prochain tick ne pourra être lancé/exécuté avant que la requête soit finie.

Puisque Minecraft s’exécute dans sa majorité sous un seul thread, il y a peu de choses que vous pouvez faire de manière asynchrone. Si vous devez exécuter une tâche asynchrone, vous devriez y exécuter tout le code qui n’utilise pas SpongeAPI ou n’affecte pas Minecraft, puis enregistrer une autre tâche synchrone qui gérera le code nécessitant l’API. Il y a quelque parties de Minecraft avec lesquelles vous pouvez travailler de manière asynchrone, incluant :

  • Chat

  • Gestion des Permissions intégrée à Sponge

  • Scheduler de Sponge

En plus, il y a d’autres opérations qui sont sûres pour être faites de manière asynchrone:

  • Requêtes de réseaux indépendants

  • Système de fichier Entrée/Sortie (sauf les fichiers utilisés par Sponge)

Avertissement

Accéder aux objets du jeu en dehors du thread principal peut causer des crashs, des inconsistances et d’autres problèmes qu’il serait préférable d’éviter. Si cela est mal fait, vous pouvez rencontrer une ConcurrentModificationException avec ou sans crash du serveur au mieux, ou d’une potentielle corruption de joueur/monde/serveur au pire.

Avertissement

Toutes les tâches planifiées doivent soit regarder l”état actuel du Game, ou doit être désinscrit du registre si ils ne sont plus nécessaires (ex : lors d’un GameStoppingServerEvent). C’est d’une importance particulière pour le client car il peut démarrer et arrêter le serveur plusieurs fois.

Compatibilité avec les autres librairies

Pour que votre plugin augmente en taille et en possibilité, vous pouvez commencer à utiliser une des nombreuse librairies en concurrences, valable pour Java et sa JVM. Ces librairies ont tendances à s’appuyer sur l”ExecutorService de Java afin de mieux diriger sur quel Thread il faut exécuter la tâche correspondante.

Pour permettre à ces librairies de fonctionner avec le Scheduler de Sponge la méthode suivante peut être utilisée:

Une chose à garder à l’esprit est que chaque tâche qui interagit avec Sponge en dehors des interactions listées dans Tâches Asynchrones doit être exécuté sur le ExecutorService crée avec Scheduler#createSyncExecutor(Object) pour être thread-safe.

import org.spongepowered.api.scheduler.SpongeExecutorService;

PluginContainer plugin = ...;

SpongeExecutorService minecraftExecutor = Sponge.getScheduler().createSyncExecutor(plugin);

minecraftExecutor.submit(() -> { ... });

minecraftExecutor.schedule(() -> { ... }, 10, TimeUnit.SECONDS);

Presque toutes les librairies ont une manière de s’adapter à l”ExecutorService pour planifier de manière native les tâches. À titre d’exemple les paragraphe suivants vont expliquer comment l”ExecutorService est utilisé dans bon nombre de librairies.

CompletableFuture (Java 8)

Avec Java 8 l’objet CompletableFuture a été ajouté à la library standard. Comparé à l’objet Future, celui-ci permet au développeur de fournir un callback appelé quand le futur se complète plutôt que de bloquer le thread jusqu’à ce que le future se réalise éventuellement.

CompletableFuture est une interface qui possède généralement trois variations pour chacune de ses fonctions:

  • CompletableFuture#<function>Async(..., Executor ex) Exécute cette fonction en passant par ex

  • CompletableFuture#<function>Async(...) Exécute cette fonction en passant par ForkJoinPool.commonPool()

  • CompletableFuture#<function>(...) Exécute cette fonction sur un des thread du CompletableFuture précédemment complété.

import java.util.concurrent.CompletableFuture;

PluginContainer plugin = ...;

SpongeExecutorService minecraftExecutor = Sponge.getScheduler().createSyncExecutor(plugin);

CompletableFuture.supplyAsync(() -> {
    // ASYNC: ForkJoinPool.commonPool()
    return 42;
}).thenAcceptAsync((awesomeValue) -> {
    // SYNC: minecraftExecutor
}, minecraftExecutor).thenRun(() -> {
    // SYNC: minecraftExecutor
});

RxJava

RxJava est une implémentation du concept de Reactive Extensions pour la JVM.

Le multithreading avec Rx est géré par plusieurs Schedulers. En utilisant la fonction Schedulers#from(Executor executor), l”Executor fournit par Sponge peut être transformé en Scheduler.

Un peu comme CompletableFuture, par défaut les actions sont exécutées sur le même thread qui a complété la partie précédente de la chaîne. Utilisez Observable#observeOn(Scheduler scheduler) pour changer de thread.

Une chose importante à garder à l’esprit est que l”Observable racine est invoqué sur le thread sur lequel Observable#subscribe() a été appelé. Si l’observable racine interagit avec Sponge, il doit être obligé d’être exécuté de manière synchrone en utilisant Observable#subscribeOn(Scheduler scheduler).

import rx.Observable;
import rx.Scheduler;
import rx.schedulers.Schedulers;

PluginContainer plugin = ...;

SpongeExecutorService executor = Sponge.getScheduler().createSyncExecutor(plugin);
Scheduler minecraftScheduler = Schedulers.from(executor);

Observable.defer(() -> Observable.from(Sponge.getServer().getOnlinePlayers()))
          .subscribeOn(minecraftScheduler) // defer -> SYNC: minecraftScheduler
          .observeOn(Schedulers.io()) // -> ASYNC: Schedulers.io()
          .filter(player -> {
              // ASYNC: Schedulers.io()
              return "Flards".equals(player.getName());
          })
          .observeOn(minecraftScheduler) // -> SYNC: minecraftScheduler
          .subscribe(player -> {
              // SYNC: minecraftScheduler
              player.kick(Component.text("Computer says no"));
          });

Scala

Scala vient avec un objet Future intégré que beaucoup de frameworks scala reflètent dans la conception. La plupart des méthodes du Future acceptent un ExecutionContext qui détermine où cette partie de l’opération doit être exécutée. C’est différent du CompletableFuture ou de RxJava puisque, eux, s’exécutent sur le même thread que celui où l’opération précédente s’est terminée.

Le fait que toutes ces opérations tentent implicitement de trouver un ExecutionContext signifie que vous pouvez facilement utiliser le ExecutionContext.global par défaut et exécuter plus précisément les parties qui doivent être thread-safe sur le thread du serveur Sponge.

Pour éviter d’accidentellement planifier du travail à travers l”ExecutorContext de Sponge, un autre contexte doit être implicitement défini pour qu’il devienne le choix par défaut. Pour maintenir la sécurité des threads seulement sur les fonctions qui interagissent avec Sponge vous devrez avoir l’exécuteur de Sponge spécifié.

import scala.concurrent.ExecutionContext

val executor = Sponge.getScheduler().createSyncExecutor(plugin)

import ExecutionContext.Implicits.global
val ec = ExecutionContext.fromExecutorService(executor)

val future = Future {
    // ASYNC: ExecutionContext.Implicits.global
}

future foreach {
    case value => // SYNC: ec
}(ec)

future map {
    case value => 42 // SYNC: ec
}(ec).foreach {
    case value => println(value) // ASYNC: ExecutionContext.Implicits.global
}