Class StructuredScope<T>

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

Provides a fluent API for structured concurrency with automatic lifecycle management of child tasks.

为结构化并发提供流式 API，自动管理子任务的生命周期。

Features | 特性:

  • Child tasks bound to parent scope - 子任务绑定到父作用域
  • Automatic cancellation on failure - 失败时自动取消
  • Timeout support - 超时支持
  • Result aggregation - 结果聚合

Example | 示例:

List<String> results = StructuredScope.shutdownOnFailure()
    .fork(() -> fetchA())
    .fork(() -> fetchB())
    .fork(() -> fetchC())
    .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

    • shutdownOnFailure

      public static <T> StructuredScope<T> shutdownOnFailure()
      Creates a scope that shuts down on first failure. 创建首次失败时关闭的作用域。
      Type Parameters:
      T - the result type - 结果类型
      Returns:
      the scope - 作用域

    • shutdownOnSuccess

      public static <T> StructuredScope<T> shutdownOnSuccess()
      Creates a scope that shuts down on first success. 创建首次成功时关闭的作用域。
      Type Parameters:
      T - the result type - 结果类型
      Returns:
      the scope - 作用域

    • fork

      public StructuredScope<T> fork(Callable<T> task)
      Forks a task in this scope. 在此作用域中分叉任务。
      Parameters:
      task - the task - 任务
      Returns:
      this scope - 此作用域

    • forkAll

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

    • forkAll

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

    • joinAll

      public List<T> joinAll()
      Joins and returns all results. 等待并返回所有结果。
      Returns:
      the results - 结果

    • joinAll

      public List<T> joinAll(Duration timeout)
      Joins with timeout and returns all results. Note: In JDK 25, timeout must be configured at scope creation time via Configuration. This method provides a best-effort timeout using a virtual thread monitor. 带超时等待并返回所有结果。 注意：JDK 25 中超时须在创建时通过 Configuration 配置。 此方法通过虚拟线程监控提供尽力超时。
      Parameters:
      timeout - the timeout - 超时
      Returns:
      the results - 结果

    • joinAny

      public T joinAny()
      Joins and returns the first successful result (for SHUTDOWN_ON_SUCCESS). 等待并返回首个成功结果（用于 SHUTDOWN_ON_SUCCESS）。
      Returns:
      the first result - 首个结果

    • 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 - 任务数

    • getPolicy

      public StructuredScope.Policy getPolicy()
      Gets the policy. 获取策略。
      Returns:
      the policy - 策略

    • close

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