[内置 kit] 轻量可控的延时任务

[iohao]

新增功能的使用场景

TaskKit 介绍

我们知道，在 TaskKit (yuque.com) 中，提供了一个任务、时间、延时监听、超时监听...等，相结合的一个工具模块。

通过 runOnce 可以执行一些延时任务，如下所示。

// 只执行一次，2 秒后执行 
TaskKit.runOnce(() -> log.info("2 Seconds"), 2, TimeUnit.SECONDS); 
// 只执行一次，1 分钟后执行 
TaskKit.runOnce(() -> log.info("1 Minute"), 1, TimeUnit.MINUTES)

但有时，我们需要一些可控的延时任务；就是延时的时间可以根据后续的业务来变化（比如，增加延时时间、减少延时时间、取消延时任务 ...等）。

---

轻量可控的延时任务简介

轻量可控的延时任务 - 特点

• 任务到达指定时间后会执行
• 任务可取消
• 任务可被覆盖
• 任务可增加延时的时间
• 任务可减少延时的时间
• 可设置任务监听回调

// 伪代码如下
public void test() {
  // 创建轻量可控的延时任务，并设置任务监听回调，当延时任务触发时会执行该回调
  DelayTask delayTask = TaskKit.ofDelayTask(() -> log.info("hello DelayTask"))
                // N 秒后触发
                .addTime(Duration.ofSeconds(1))
                // 启动任务
                .task();

  delayTask.addTimeMillis(500); // 增加 0.5 秒的延时时间
  delayTask.addTimeMillis(-500); // 减少 0.5 秒的延时时间
  delayTask.cancel(); // 取消任务
}

---

轻量可控的延时任务 - 业务使用场景

• 业务场景一：玩家使用某种道具时，减少冷却时间；或者触发某些事件，增加冷却时间...等。在延时任务运行期间，我们可以为玩家做一些临时性的增强，如临时增加双倍攻击 ...等。
• 业务场景二：在游戏开始前，房间创建后需要在1分钟后自动解散房间（将来某个时间执行该任务）。在房间解散前，每当有一个玩家加入房间，则解散房间延迟 30秒（增加延时时间）。当房间人数大于5人时，则取消房间自动解散规则（取消任务）

以上两个业务场景，大体想描述的是，延时任务需要支持延时时间的增减，需要支持取消。

[iohao]

更多示例

// 伪代码如下
public void test() {
    // 创建轻量可控的延时任务，并设置任务监听回调，当延时任务触发时会执行该回调
    DelayTask delayTask = TaskKit.ofDelayTask(() -> log.info("hello DelayTask"))
                // N 秒后触发
                .addTime(Duration.ofSeconds(1))
                // 启动任务
                .task();

    delayTask.addTimeMillis(500); // 增加 0.5 秒的延时时间
    delayTask.addTimeMillis(-500); // 减少 0.5 秒的延时时间
    delayTask.cancel(); // 取消任务

    String taskId = delayTask.getTaskId(); // 得到当前 taskId（自动生成）

    TaskKit.cancelDelayTask(taskId); // 通过 taskId 取消任务，与 cancel 等价

    // --------------------------------------------------------
    // 创建轻量可控的延时任务，并设置 taskId 和任务监听回调。
    String newTaskId = "1";
    TaskKit.ofDelayTask(newTaskId,() -> log.info("hello DelayTask"))
                // 2.5 秒后触发
                .addTime(Duration.ofSeconds(2))
                .addTimeMillis(500)
                // 启动任务
                .task();

    // 在后续的业务中，可以通过 taskId 查找该延时任务
    Optional<DelayTask> optionalDelayTask = DelayTaskKit.optionalDelayTask(newTaskId);
    if (optionalDelayTask.isPresent()) {
        DelayTask delayTask = optionalDelayTask.get();
        log.info("{}", delayTask);
    }

    // 通过 taskId 查找延时任务，存在则执行给定逻辑
    DelayTaskKit.ifPresentDelayTask(newTaskId, delayTask -> {
        delayTask.addTimeMillis(500); // 增加 0.5 秒的延时时间
    });

}