Class ScheduledScope<T>

java.lang.Object
cloud.opencode.base.parallel.structured.ScheduledScope<T>
Type Parameters:
T - the result type - 结果类型
All Implemented Interfaces:
AutoCloseable
public final class ScheduledScope<T> extends Object implements AutoCloseable
Scheduled Scope - Scheduled Structured Concurrency (JDK 25 JEP 499) 定时作用域 - 定时结构化并发 (JDK 25 JEP 499)

Extends structured concurrency with scheduling capabilities including delayed execution, periodic tasks, and deadline-based operations.

扩展结构化并发以支持调度功能，包括延迟执行、周期性任务和基于截止时间的操作。

Features | 特性:

  • Delayed task forking - 延迟任务分叉
  • Periodic task execution within scope - 作用域内的周期性任务执行
  • Deadline-based joining - 基于截止时间的等待
  • Automatic cancellation on scope close - 作用域关闭时自动取消
  • Structured concurrency guarantees maintained - 保持结构化并发保证

Example | 示例:

// Delayed execution
try (var scope = ScheduledScope.<String>create()) {
    scope.fork(() -> fetchA());
    scope.forkDelayed(Duration.ofSeconds(1), () -> fetchB());
    scope.forkAt(Instant.now().plusSeconds(2), () -> fetchC());
    List<String> results = scope.joinAll();
}

// Periodic task with limit
try (var scope = ScheduledScope.<Integer>create()) {
    scope.forkPeriodic(Duration.ofSeconds(1), 5, () -> pollStatus());
    List<Integer> statuses = scope.joinAll();
}

Security | 安全性:

  • Thread-safe: No (use within single scope/thread) - 线程安全: 否（在单个作用域/线程内使用）
Since:
JDK 25, opencode-base-parallel V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static <T> ScheduledScope<T> create()
      Creates a new scheduled scope. 创建新的定时作用域。
      Type Parameters:
      T - the result type - 结果类型
      Returns:
      the scope - 作用域

    • withDeadline

      public static <T> ScheduledScope<T> withDeadline(Instant deadline)
      Creates a scheduled scope with deadline. 创建带截止时间的定时作用域。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      deadline - the deadline - 截止时间
      Returns:
      the scope - 作用域

    • withTimeout

      public static <T> ScheduledScope<T> withTimeout(Duration timeout)
      Creates a scheduled scope with timeout (deadline from now). 创建带超时的定时作用域（从现在开始计算截止时间）。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      timeout - the timeout - 超时
      Returns:
      the scope - 作用域

    • builder

      public static <T> ScheduledScope.Builder<T> builder()
      Creates a builder for more configuration options. 创建构建器以获取更多配置选项。
      Type Parameters:
      T - the result type - 结果类型
      Returns:
      the builder - 构建器

    • fork

      public ScheduledScope<T> fork(Callable<T> task)
      Forks a task immediately. 立即分叉任务。
      Parameters:
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkAll

      @SafeVarargs public final ScheduledScope<T> forkAll(Callable<T>... tasks)
      Forks multiple tasks immediately. 立即分叉多个任务。
      Parameters:
      tasks - the tasks - 任务
      Returns:
      this scope - 此作用域

    • forkAll

      public ScheduledScope<T> forkAll(Iterable<? extends Callable<T>> tasks)
      Forks multiple tasks immediately. 立即分叉多个任务。
      Parameters:
      tasks - the tasks - 任务
      Returns:
      this scope - 此作用域

    • forkDelayed

      public ScheduledScope<T> forkDelayed(Duration delay, Callable<T> task)
      Forks a task after a delay. 延迟后分叉任务。
      Parameters:
      delay - the delay - 延迟
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkAt

      public ScheduledScope<T> forkAt(Instant instant, Callable<T> task)
      Forks a task at a specific instant. 在指定时刻分叉任务。
      Parameters:
      instant - the instant - 时刻
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkPeriodic

      public ScheduledScope<T> forkPeriodic(Duration period, int count, Callable<T> task)
      Forks a periodic task with a maximum number of executions. 分叉周期性任务，指定最大执行次数。

      The task will be executed periodically until the count is reached or the scope is closed.

      任务将周期性执行，直到达到次数或作用域关闭。

      Parameters:
      period - the period between executions - 执行间隔
      count - the maximum number of executions - 最大执行次数
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkPeriodicUntil

      public ScheduledScope<T> forkPeriodicUntil(Duration period, Instant deadline, Callable<T> task)
      Forks a periodic task until deadline or scope close. 分叉周期性任务，直到截止时间或作用域关闭。
      Parameters:
      period - the period between executions - 执行间隔
      deadline - the deadline - 截止时间
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkWithFixedDelay

      public ScheduledScope<T> forkWithFixedDelay(Duration delay, int count, Callable<T> task)
      Forks a periodic task with delay between completion and next execution. 分叉周期性任务，在完成和下次执行之间有延迟。
      Parameters:
      delay - the delay between completion and next execution - 完成和下次执行之间的延迟
      count - the maximum number of executions - 最大执行次数
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • joinAll

      public List<T> joinAll()
      Waits for all scheduled tasks to complete and joins. 等待所有已调度任务完成并等待结果。
      Returns:
      the results - 结果

    • joinAll

      public List<T> joinAll(Duration timeout)
      Waits for all tasks with timeout. 带超时等待所有任务。
      Parameters:
      timeout - the timeout - 超时
      Returns:
      the results - 结果

    • joinAndReduce

      public T joinAndReduce(T identity, BiFunction<T,T,T> reducer)
      Joins and reduces results. 等待并归约结果。
      Parameters:
      identity - the identity value - 恒等值
      reducer - the reducer function - 归约函数
      Returns:
      the reduced result - 归约结果

    • joinAsResults

      public List<TaskResult<T>> joinAsResults()
      Joins and returns results as TaskResults. 等待并返回结果为 TaskResult。
      Returns:
      the task results - 任务结果

    • getTaskCount

      public int getTaskCount()
      Gets the number of forked tasks. 获取分叉的任务数。
      Returns:
      the task count - 任务数

    • getPendingScheduledCount

      public int getPendingScheduledCount()
      Gets the number of pending scheduled futures. 获取待处理的已调度 Future 数量。
      Returns:
      the pending scheduled count - 待调度数

    • getDeadline

      public Instant getDeadline()
      Gets the deadline if set. 获取截止时间（如果设置）。
      Returns:
      the deadline or null - 截止时间或 null

    • getRemainingTime

      public Duration getRemainingTime()
      Gets the remaining time until deadline. 获取距截止时间的剩余时间。
      Returns:
      the remaining time or null if no deadline - 剩余时间，无截止时间时为 null

    • isDeadlinePassed

      public boolean isDeadlinePassed()
      Checks if the deadline has passed. 检查截止时间是否已过。
      Returns:
      true if deadline has passed - 如果已过截止时间返回 true

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable