Contenido generado con IA — puede contener errores.

ExyliaLib/Fundamentos

Tareas e hilos

Un scheduler que corre en Spigot, Paper y Folia sin una sola rama en tu código.

Página 14 de 543 min de lectura

Folia no tiene hilo principal. Tiene hilos por región, y una tarea que toca una entidad tiene que correr en el hilo dueño de esa entidad. Escribir para ambos significa escribir cada llamada dos veces — o llamar a este módulo, que decide por ti.

java
TaskScheduler tasks = Tasks.of(this);
 
tasks.run(() -> broadcast());
tasks.runLater(20L, () -> start());
tasks.runTimer(0L, 20L, () -> tick());

Dónde corre una tarea#

LlamadaCorre en
run, runLater, runTimerEl hilo global — el principal de Bukkit, o la región global de Folia.
runAsync, runAsyncLater, runAsyncTimerUn hilo del pool. Nunca toques la API de Bukkit desde uno.
runAtEntity, runAtEntityLater, runAtEntityTimerEl hilo dueño de esa entidad. En Folia, su región.
runAtLocation, runAtLocationLater, runAtLocationTimerEl hilo dueño de esa ubicación.
executeAhora si ya estás en el hilo correcto, programado si no.
Todo lo que va sobre un jugador es `runAtEntity`

Teletransportar, cambiar inventario, mandar un título, leer su ubicación: todo eso pertenece al hilo del propio jugador. run es para trabajo sobre el servidor entero — un broadcast, un contador global. Equivocarse es invisible en Paper y un crash en Folia.

Cancelar#

Cada llamada devuelve un TaskHandle:

java
TaskHandle timer = tasks.runTimer(0L, 20L, () -> tick());
timer.cancel();

Una tarea repetitiva que necesita cancelarse a sí misma recibe el handle como argumento:

java
tasks.runTimer(0L, 20L, handle -> {
    if (--countdown <= 0) {
        handle.cancel();
        return;
    }
    show(countdown);
});

runAtEntity acepta además un callback retired, que se ejecuta si la entidad desapareció antes que la tarea:

java
tasks.runAtEntity(player, () -> give(player, kit), () -> queueForLater(player));

Un temporizador de entidad se para solo cuando su entidad desaparece. Un jugador cuenta como desaparecido solo cuando se desconecta, así que un temporizador por jugador sigue corriendo a través de la muerte y el respawn — en Paper exactamente igual que en Folia.

tasks.cancelAll() cancela todo lo que programó el plugin, y tasks.activeTasks() dice cuántas siguen en marcha.

Preguntar dónde estás#

java
if (!tasks.isOwnedBy(player)) {
    tasks.runAtEntity(player, () -> act(player));
    return;
}
act(player);
LlamadaResponde
isGlobalThread()Si este es el hilo global.
isOwnedBy(entity) / isOwnedBy(location)Si este hilo puede tocar esa entidad o esa posición.

Volver de una consulta a la base de datos es el motivo habitual de preguntar: el future se completa en un hilo del pool, y todo lo que quieras hacer con la respuesta pertenece al jugador.

java
kits.find(id).thenAccept(found ->
        tasks.runAtEntity(player, () -> found.ifPresent(kit -> give(player, kit))));

Las respuestas escritas en una entrada llegan en el hilo que usara el transporte. answered devuelve ambos desenlaces al hilo del jugador, y reabre la pantalla anterior solo cuando el jugador canceló — no por un timeout, una desconexión o una petición más nueva:

java
PluginInputs inputs = Inputs.of(this);
 
inputs.answered(player, inputs.text(player, "Nombra la casa").open(),
        name -> homes.create(player, name),   // en el hilo del jugador
        () -> homesMenu.open(player));        // solo si canceló; puede ser null

Ticks#

Retrasos y periodos van en ticks: 20 ticks es un segundo. La librería mantiene ticks donde una API de Bukkit los mantendría, así que un número copiado de una config antigua sigue significando lo mismo.

Limpieza#

Las tareas de un plugin se cancelan cuando se desactiva. Los menús se cierran primero, para que un botón no pueda responder un último clic hacia un classloader moribundo.

Programar desde un plugin que ya está desactivado — a lo que el scheduler del propio servidor responde lanzando una excepción — ejecuta una tarea única (runAsync incluido) en línea, en el hilo que la pidió, para que un guardado o una limpieza lanzados desde onDisable sigan ocurriendo. Un temporizador se descarta y su handle vuelve cancelado.

¿Falta algo en esta página? Dínoslo en Discord