🐳 #291 增加轻量可控的延时任务

common/common-micro-kit/src/main/java/com/iohao/game/common/kit/concurrent/timer/delay/DelayTask.java

@@ -0,0 +1,126 @@
+/*
+ * ioGame
+ * Copyright (C) 2021 - present  渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.
+ * # iohao.com . 渔民小镇
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.iohao.game.common.kit.concurrent.timer.delay;
+
+import com.iohao.game.common.kit.concurrent.TaskListener;
+
+import java.time.Duration;
+
+/**
+ * 轻量可控的延时任务，任务到达指定时间后会执行、任务可取消、任务可增加延时时间
+ *
+ * @author 渔民小镇
+ * @date 2024-09-01
+ * @since 21.16
+ */
+public interface DelayTask {
+
+    /**
+     * get taskId
+     *
+     * @return taskId
+     */
+    String getTaskId();
+
+    /**
+     * 获取任务监听对象
+     *
+     * @param <T> t
+     * @return 任务监听
+     */
+    <T extends TaskListener> T getTaskListener();
+
+    /**
+     * 是否活跃的任务
+     *
+     * @return true 活跃的
+     */
+    boolean isActive();
+
+    /**
+     * 取消任务
+     */
+    void cancel();
+
+    /**
+     * 剩余的延时时间 millis
+     *
+     * @return 剩余的延时时间 millis
+     */
+    long getMillis();
+
+    /**
+     * 增加延时时间
+     *
+     * @param duration duration
+     * @return DelayTask
+     */
+    default DelayTask plusTime(Duration duration) {
+        return this.plusTimeMillis(duration.toMillis());
+    }
+
+    /**
+     * 增加延时时间
+     * <p>
+     * for example
+     * <pre>{@code
+     *     DelayTask delayTask = ...;
+     *     delayTask.plusTimeMillis(500);  // 增加 0.5 秒的延时时间
+     *     delayTask.plusTimeMillis(-500); // 减少 0.5 秒的延时时间
+     * }</pre>
+     *
+     * @param millis millis（当为负数时，表示减少延时时间）
+     * @return DelayTask
+     */
+    DelayTask plusTimeMillis(long millis);
+
+    /**
+     * 减少延时时间
+     * <p>
+     * for example
+     * <pre>{@code
+     *     DelayTask delayTask = ...;
+     *     delayTask.minusTimeMillis(500);  // 减少 0.5 秒的延时时间
+     *     delayTask.minusTimeMillis(-500); // 增加 0.5 秒的延时时间
+     * }</pre>
+     *
+     * @param millis millis（当为负数时，表示增加延时时间）
+     * @return DelayTask
+     */
+    default DelayTask minusTimeMillis(long millis) {
+        return this.plusTimeMillis(-millis);
+    }
+
+    /**
+     * 减少延时时间
+     *
+     * @param duration duration
+     * @return DelayTask
+     */
+    default DelayTask minusTime(Duration duration) {
+        return this.minusTimeMillis(duration.toMillis());
+    }
+
+    /**
+     * 启动延时任务
+     *
+     * @return DelayTask
+     */
+    DelayTask task();
+}

common/common-micro-kit/src/main/java/com/iohao/game/common/kit/concurrent/timer/delay/DelayTaskKit.java

@@ -0,0 +1,107 @@
+/*
+ * ioGame
+ * Copyright (C) 2021 - present  渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.
+ * # iohao.com . 渔民小镇
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.iohao.game.common.kit.concurrent.timer.delay;
+
+import com.iohao.game.common.kit.concurrent.TaskListener;
+import lombok.Getter;
+import lombok.experimental.UtilityClass;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Consumer;
+
+/**
+ * 轻量可控的延时任务工具类
+ *
+ * @author 渔民小镇
+ * @date 2024-09-01
+ * @since 21.16
+ */
+@UtilityClass
+public class DelayTaskKit {
+
+    @Getter
+    DelayTaskRegion delayTaskRegion = new SimpleDelayTaskRegion();
+
+    /**
+     * 设置轻量可控的延时任务域
+     *
+     * @param delayTaskRegion delayTaskRegion
+     */
+    public void setDelayTaskRegion(DelayTaskRegion delayTaskRegion) {
+        Objects.requireNonNull(delayTaskRegion);
+
+        DelayTaskRegion delayTaskRegionOld = DelayTaskKit.delayTaskRegion;
+        DelayTaskKit.delayTaskRegion = delayTaskRegion;
+
+        if (delayTaskRegionOld instanceof DelayTaskRegionEnhance stop) {
+            stop.stop();
+        }
+    }
+
+    /**
+     * 通过 taskId 取消任务
+     *
+     * @param taskId taskId
+     */
+    public void cancelDelayTask(String taskId) {
+        delayTaskRegion.cancelDelayTask(taskId);
+    }
+
+    /**
+     * get Optional DelayTask by taskId
+     *
+     * @param taskId taskId
+     * @return Optional DelayTask
+     */
+    public Optional<DelayTask> optionalDelayTask(String taskId) {
+        return delayTaskRegion.optionalDelayTask(taskId);
+    }
+
+    /**
+     * 如果 taskId 存在，就执行给定操作
+     *
+     * @param taskId   taskId
+     * @param consumer 给定操作
+     */
+    public void ifPresentDelayTask(String taskId, Consumer<DelayTask> consumer) {
+        DelayTaskKit.optionalDelayTask(taskId).ifPresent(consumer);
+    }
+
+    /**
+     * 创建一个轻量可控的延时任务
+     *
+     * @param taskListener 任务监听回调
+     * @return 轻量可控的延时任务
+     */
+    public DelayTask of(TaskListener taskListener) {
+        return delayTaskRegion.of(taskListener);
+    }
+
+    /**
+     * 创建一个轻量可控的延时任务
+     *
+     * @param taskId       taskId （如果 taskId 相同，会覆盖之前的延时任务）
+     * @param taskListener 任务监听回调
+     * @return 轻量可控的延时任务
+     */
+    public DelayTask of(String taskId, TaskListener taskListener) {
+        return delayTaskRegion.of(taskId, taskListener);
+    }
+}

common/common-micro-kit/src/main/java/com/iohao/game/common/kit/concurrent/timer/delay/DelayTaskRegion.java

@@ -0,0 +1,84 @@
+/*
+ * ioGame
+ * Copyright (C) 2021 - present  渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.
+ * # iohao.com . 渔民小镇
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.iohao.game.common.kit.concurrent.timer.delay;
+
+import com.iohao.game.common.kit.concurrent.TaskListener;
+
+import java.util.Optional;
+
+/**
+ * 轻量可控延时任务域接口，负责轻量可控延时任务的创建、获取、取消、统计任务数量 ...等相关操作。
+ *
+ * @author 渔民小镇
+ * @date 2024-09-01
+ * @since 21.16
+ */
+public interface DelayTaskRegion {
+
+    /**
+     * 通过 taskId 获取一个可控的延时任务 Optional
+     *
+     * @param taskId taskId
+     * @return DelayTask Optional
+     */
+    Optional<DelayTask> optionalDelayTask(String taskId);
+
+    /**
+     * 根据 taskId 取消可控延时任务的执行。
+     *
+     * @param taskId taskId
+     */
+    void cancelDelayTask(String taskId);
+
+    /**
+     * 统计当前延时任务的数量
+     *
+     * @return 当前延时任务数量
+     */
+    int countDelayTask();
+
+    /**
+     * 创建一个可控的延时任务，并设置任务监听回调。
+     * <pre>{@code
+     * DelayTask delayTask = of(taskListener);
+     * // 启动延时任务
+     * delayTask.task();
+     * }
+     * </pre>
+     *
+     * @param taskListener 任务监听回调
+     * @return 可控的延时任务
+     */
+    DelayTask of(TaskListener taskListener);
+
+    /**
+     * 创建一个可控的延时任务，并设置 taskId 和任务监听回调
+     * <pre>{@code
+     * DelayTask delayTask = of(taskId, taskListener);
+     * // 启动延时任务
+     * delayTask.task();
+     * }
+     * </pre>
+     *
+     * @param taskId       taskId
+     * @param taskListener 任务监听回调
+     * @return 可控的延时任务
+     */
+    DelayTask of(String taskId, TaskListener taskListener);
+}