feat(core): Added distributor 3 scheduler (partial)

distributor-core/src/main/java/com/xpdustry/distributor/core/DistributorCorePlugin.java

@@ -30,9 +30,9 @@
 public final class DistributorCorePlugin extends AbstractMindustryPlugin implements Distributor {
 
  private final ServiceManager services = ServiceManager.simple();
+ private final MultiLocalizationSource source = MultiLocalizationSource.create();
  private CommandFacade.@Nullable Factory factory = null;
  private @Nullable PermissionManager permissions = null;
- private final MultiLocalizationSource source = MultiLocalizationSource.create();
 
  @Override
  public ServiceManager getServiceManager() {

distributor-core/src/main/java/com/xpdustry/distributor/core/annotation/TaskHandler.java

@@ -0,0 +1,60 @@
+/*
+ * Distributor, a feature-rich framework for Mindustry plugins.
+ *
+ * Copyright (C) 2024 Xpdustry
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.xpdustry.distributor.core.annotation;
+
+import com.xpdustry.distributor.core.scheduler.Cancellable;
+import com.xpdustry.distributor.core.scheduler.MindustryTimeUnit;
+import com.xpdustry.distributor.core.scheduler.PluginScheduler;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method as a task handler, meaning it will be registered and called as a scheduled task in the
+ * {@link PluginScheduler}.
+ * <br>
+ * The annotated method can have one {@link Cancellable} parameter to allow the task to cancel itself.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface TaskHandler {
+
+ /**
+ * The interval between each execution of the task.
+ * The task will be executed once if the interval is set to a value below -1.
+ */
+ long interval() default -1;
+
+ /**
+ * The initial delay before the first execution of the task.
+ * The task will be executed immediately if the delay is set to a value below -1.
+ */
+ long delay() default -1;
+
+ /**
+ * The time unit of the interval and initial delay.
+ */
+ MindustryTimeUnit unit() default MindustryTimeUnit.SECONDS;
+
+ /**
+ * Whether the task should be executed asynchronously.
+ */
+ boolean async() default false;
+}

distributor-core/src/main/java/com/xpdustry/distributor/core/scheduler/Cancellable.java

@@ -0,0 +1,30 @@
+/*
+ * Distributor, a feature-rich framework for Mindustry plugins.
+ *
+ * Copyright (C) 2024 Xpdustry
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.xpdustry.distributor.core.scheduler;
+
+/**
+ * A {@code Cancellable} is used to cancel a task.
+ */
+public interface Cancellable {
+
+ /**
+ * Cancels the task bound to this {@code Cancellable}.
+ */
+ void cancel();
+}

distributor-core/src/main/java/com/xpdustry/distributor/core/scheduler/MindustryTimeUnit.java

@@ -0,0 +1,109 @@
+/*
+ * Distributor, a feature-rich framework for Mindustry plugins.
+ *
+ * Copyright (C) 2024 Xpdustry
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.xpdustry.distributor.core.scheduler;
+
+import java.util.Optional;
+import java.util.concurrent.TimeUnit;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Time units used by the {@link PluginTaskBuilder} and {@link PluginTask} classes to represent time.
+ */
+public enum MindustryTimeUnit {
+
+ /**
+ * Time unit representing one thousandth of a second.
+ */
+ MILLISECONDS(TimeUnit.MILLISECONDS),
+
+ /**
+ * Time unit representing one game loop, which is 60 times per second.
+ */
+ TICKS(null),
+
+ /**
+ * Time unit representing one thousandth of a millisecond.
+ */
+ SECONDS(TimeUnit.SECONDS),
+
+ /**
+ * Time unit representing sixty seconds.
+ */
+ MINUTES(TimeUnit.MINUTES),
+
+ /**
+ * Time unit representing sixty minutes.
+ */
+ HOURS(TimeUnit.HOURS),
+
+ /**
+ * Time unit representing twenty-four hours.
+ */
+ DAYS(TimeUnit.DAYS);
+
+ private final @Nullable TimeUnit unit;
+
+ MindustryTimeUnit(final @Nullable TimeUnit unit) {
+ this.unit = unit;
+ }
+
+ /**
+ * Converts the given duration in the given time unit to this time unit.
+ * <p>
+ * Since this method is equivalent to {@link TimeUnit#convert(long, TimeUnit)}:
+ * <ul>
+ * <li>If it overflows, the result will be {@link Long#MAX_VALUE} if the duration is positive,
+ * or {@link Long#MIN_VALUE} if it is negative.</li>
+ * <li>Conversions are floored so converting 999 milliseconds to seconds results in 0.</li>
+ * </ul>
+ *
+ * @param sourceDuration the duration to convert
+ * @param sourceUnit the time unit of the duration
+ * @return the converted duration
+ * @see TimeUnit#convert(long, TimeUnit)
+ */
+ public long convert(final long sourceDuration, final MindustryTimeUnit sourceUnit) {
+ if (this == sourceUnit) {
+ return sourceDuration;
+ }
+ final var sourceJavaUnit = sourceUnit.getJavaTimeUnit();
+ final var targetJavaUnit = this.getJavaTimeUnit();
+
+ if (sourceJavaUnit.isPresent() && targetJavaUnit.isPresent()) {
+ return targetJavaUnit.get().convert(sourceDuration, sourceJavaUnit.get());
+ } else if (sourceJavaUnit.isEmpty()) {
+ return targetJavaUnit
+ .orElseThrow()
+ .convert((long) Math.nextUp(sourceDuration * (1000F / 60F)), TimeUnit.MILLISECONDS);
+ } else {
+ final var millis = TimeUnit.MILLISECONDS.convert(sourceDuration, sourceJavaUnit.orElseThrow());
+ if (millis == Long.MAX_VALUE || millis == Long.MIN_VALUE) {
+ return millis;
+ }
+ return (long) (millis * (60F / 1000L));
+ }
+ }
+
+ /**
+ * Returns the Java time unit associated with this Mindustry time unit, if any.
+ */
+ public Optional<TimeUnit> getJavaTimeUnit() {
+ return Optional.ofNullable(this.unit);
+ }
+}

distributor-core/src/main/java/com/xpdustry/distributor/core/scheduler/PluginScheduler.java

@@ -0,0 +1,35 @@
+/*
+ * Distributor, a feature-rich framework for Mindustry plugins.
+ *
+ * Copyright (C) 2024 Xpdustry
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.xpdustry.distributor.core.scheduler;
+
+import com.xpdustry.distributor.core.plugin.MindustryPlugin;
+
+/**
+ * A {@code PluginScheduler} is used to schedule tasks for a plugin. A better alternative to {@link arc.util.Timer}.
+ */
+public interface PluginScheduler {
+
+ /**
+ * Returns a new {@link PluginTaskBuilder} instance scheduling a task.
+ *
+ * @param plugin the plugin to schedule the task for.
+ * @return a new {@link PluginTaskBuilder} instance.
+ */
+ PluginTaskBuilder schedule(final MindustryPlugin plugin);
+}

distributor-core/src/main/java/com/xpdustry/distributor/core/scheduler/PluginSchedulerImpl.java

@@ -0,0 +1,118 @@
+/*
+ * Distributor, a feature-rich framework for Mindustry plugins.
+ *
+ * Copyright (C) 2024 Xpdustry
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.xpdustry.distributor.core.scheduler;
+
+import com.xpdustry.distributor.core.plugin.MindustryPlugin;
+import com.xpdustry.distributor.core.plugin.PluginListener;
+import java.util.Arrays;
+import java.util.Comparator;
+import java.util.Queue;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ForkJoinPool;
+import java.util.concurrent.ForkJoinWorkerThread;
+import java.util.concurrent.PriorityBlockingQueue;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+final class PluginSchedulerImpl implements PluginScheduler, PluginListener {
+
+ static final String DISTRIBUTOR_WORKER_BASE_NAME = "distributor-worker-";
+ private static final Logger logger = LoggerFactory.getLogger("PluginScheduler");
+
+ private final Queue<PluginTaskImpl<?>> tasks =
+ new PriorityBlockingQueue<>(16, Comparator.comparing(PluginTaskImpl::getNextExecutionTime));
+ private final ForkJoinPool pool;
+ private final Executor syncExecutor;
+ private final TimeSource source;
+
+ public PluginSchedulerImpl(final TimeSource source, final Executor syncExecutor, final int parallelism) {
+ this.pool = new ForkJoinPool(parallelism, new PluginSchedulerWorkerThreadFactory(), null, false);
+ this.syncExecutor = syncExecutor;
+ this.source = source;
+ }
+
+ @Override
+ public PluginTaskBuilder schedule(final MindustryPlugin plugin) {
+ return new PluginTaskImpl.Builder(this, plugin);
+ }
+
+ @Override
+ public void onPluginUpdate() {
+ while (!this.tasks.isEmpty()) {
+ final var task = this.tasks.peek();
+ if (task.isCancelled()) {
+ this.tasks.remove();
+ } else if (task.getNextExecutionTime() < this.source.getCurrentTicks()) {
+ this.tasks.remove();
+ final Executor executor = task.isAsync() ? this.pool : this.syncExecutor;
+ executor.execute(task);
+ } else {
+ break;
+ }
+ }
+ }
+
+ @Override
+ public void onPluginExit() {
+ logger.info("Shutdown scheduler.");
+ this.pool.shutdown();
+ try {
+ if (!this.pool.awaitTermination(20, TimeUnit.SECONDS)) {
+ logger.error("Timed out waiting for the scheduler to terminate properly");
+ Thread.getAllStackTraces().forEach((thread, stack) -> {
+ if (thread.getName().startsWith(DISTRIBUTOR_WORKER_BASE_NAME)) {
+ logger.error(
+ "Worker thread {} may be blocked, possibly the reason for the slow shutdown:\n{}",
+ thread.getName(),
+ Arrays.stream(stack).map(e -> " " + e).collect(Collectors.joining("\n")));
+ }
+ });
+ }
+ } catch (final InterruptedException e) {
+ logger.error("The plugin scheduler shutdown have been interrupted.", e);
+ }
+ }
+
+ void schedule(final PluginTaskImpl<?> task) {
+ this.tasks.add(task);
+ }
+
+ TimeSource getTimeSource() {
+ return this.source;
+ }
+
+ boolean isShutdown() {
+ return this.pool.isShutdown();
+ }
+
+ private static final class PluginSchedulerWorkerThreadFactory implements ForkJoinPool.ForkJoinWorkerThreadFactory {
+
+ private static final AtomicInteger COUNT = new AtomicInteger(0);
+
+ @Override
+ public ForkJoinWorkerThread newThread(final ForkJoinPool pool) {
+ final var thread = ForkJoinPool.defaultForkJoinWorkerThreadFactory.newThread(pool);
+ thread.setName(DISTRIBUTOR_WORKER_BASE_NAME + COUNT.getAndIncrement());
+ return thread;
+ }
+ }
+}