java.lang.Object

cloud.opencode.base.core.thread.StructuredTaskUtil

public final class StructuredTaskUtil extends Object

StructuredTaskScope Utility - JDK 25 Structured Concurrency support (JEP 505) 结构化并发工具类 - JDK 25 结构化并发支持 (JEP 505)

Provides structured concurrent task management, ensuring child task lifecycle is bound to parent task.

提供结构化的并发任务管理，确保子任务生命周期与父任务绑定。

JDK 25 Structured Concurrency Features | JDK 25 结构化并发特性:

Structured lifecycle - Child tasks cannot escape parent task scope - 结构化生命周期：子任务不会逃逸出父任务作用域
Auto cancellation - Child tasks are automatically cancelled when parent is cancelled - 自动取消：父任务取消时子任务自动取消
Error propagation - Child task exceptions automatically propagate to parent - 错误传播：子任务异常自动传播到父任务
Resource safety - Ensures all child tasks complete before exiting scope - 资源安全：确保所有子任务完成后才退出作用域

JDK 25 API Changes | JDK 25 API 变化:

Uses Joiner API instead of ShutdownOnFailure/ShutdownOnSuccess subclasses
StructuredTaskScope.open() - default behavior (all must succeed)
Joiner.allSuccessfulOrThrow() - collect all successful results
Joiner.anySuccessfulResultOrThrow() - first to succeed wins

Usage Examples | 使用示例:

// Execute all tasks in parallel, all must succeed
List<String> results = StructuredTaskUtil.invokeAll(List.of(
    () -> fetchFromService1(),
    () -> fetchFromService2(),
    () -> fetchFromService3()
));

// Execute tasks, first to succeed wins (redundancy pattern)
String result = StructuredTaskUtil.invokeAny(List.of(
    () -> fetchFromPrimary(),
    () -> fetchFromBackup()
));

// Parallel execution with result combination
UserOrderInfo info = StructuredTaskUtil.parallel(
    () -> userService.getUser(userId),
    () -> orderService.getOrders(userId),
    (user, orders) -> new UserOrderInfo(user, orders)
);

Thread Safety | 线程安全: Yes - StructuredTaskScope manages thread safety internally

Since:

JDK 25, opencode-base-core V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static interface

StructuredTaskUtil.TriFunction<T1,T2,T3,R>

Functional interface for combining three values 用于合并三个值的函数式接口
Method Summary

Modifier and Type

Method

Description

static <T> List<T>

invokeAll(List<Callable<T>> tasks)

Execute all tasks in parallel, all must succeed 并行执行所有任务，全部成功才返回

static <T> List<T>

invokeAll(List<Callable<T>> tasks, Duration timeout)

Execute all tasks in parallel with timeout, all must succeed 并行执行所有任务（带超时），全部成功才返回

static <T> T

invokeAny(List<Callable<T>> tasks)

Execute tasks in parallel, first to succeed wins 并行执行任务，任一成功即返回

static <T> T

invokeAny(List<Callable<T>> tasks, Duration timeout)

Execute tasks in parallel with timeout, first to succeed wins 并行执行任务（带超时），任一成功即返回

static <T,U,R> R

parallel(Callable<T> task1, Callable<U> task2, BiFunction<T,U,R> combiner)

Execute two tasks in parallel and combine their results 并行执行两个任务并合并结果

static <T,U,R> R

parallel(Callable<T> task1, Callable<U> task2, BiFunction<T,U,R> combiner, Duration timeout)

Execute two tasks in parallel with timeout and combine their results 并行执行两个任务（带超时）并合并结果

static <T1,T2,T3,R> R

parallel(Callable<T1> task1, Callable<T2> task2, Callable<T3> task3, StructuredTaskUtil.TriFunction<T1,T2,T3,R> combiner)

Execute three tasks in parallel and combine their results 并行执行三个任务并合并结果

static <T> T

run(Callable<T> task)

Execute a single task with structured concurrency semantics 使用结构化并发语义执行单个任务

static <T> T

run(Callable<T> task, Duration timeout)

Execute a single task with timeout 执行单个任务（带超时）

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- invokeAll
  
  public static <T> List<T> invokeAll(List<Callable<T>> tasks) throws InterruptedException
  
  Execute all tasks in parallel, all must succeed 并行执行所有任务，全部成功才返回
  Uses Joiner.allSuccessfulOrThrow() strategy: if any task fails, all other tasks are cancelled and the exception is thrown.
  
  使用 Joiner.allSuccessfulOrThrow() 策略：如果任何任务失败，其他任务将被取消并抛出异常。
  
  Type Parameters:
  
  T - the result type of the tasks
  
  Parameters:
  
  tasks - the list of tasks to execute
  
  Returns:
  
  a list of results from all tasks
  
  Throws:
  
  InterruptedException - if the current thread is interrupted
- invokeAll
  
  public static <T> List<T> invokeAll(List<Callable<T>> tasks, Duration timeout) throws InterruptedException
  
  Execute all tasks in parallel with timeout, all must succeed 并行执行所有任务（带超时），全部成功才返回
  
  Type Parameters:
  
  T - the result type of the tasks
  
  Parameters:
  
  tasks - the list of tasks to execute
  
  timeout - the maximum time to wait
  
  Returns:
  
  a list of results from all tasks
  
  Throws:
  
  InterruptedException - if the current thread is interrupted or timeout occurs
- invokeAny
  
  public static <T> T invokeAny(List<Callable<T>> tasks) throws InterruptedException
  
  Execute tasks in parallel, first to succeed wins 并行执行任务，任一成功即返回
  Uses Joiner.anySuccessfulResultOrThrow() strategy: when any task succeeds, all other tasks are cancelled and the result is returned.
  
  使用 Joiner.anySuccessfulResultOrThrow() 策略：当任何任务成功时，其他任务将被取消并返回结果。
  
  This is useful for redundancy patterns where you want to try multiple sources and use the first successful result.
  
  Type Parameters:
  
  T - the result type of the tasks
  
  Parameters:
  
  tasks - the list of tasks to execute
  
  Returns:
  
  the result from the first successful task
  
  Throws:
  
  InterruptedException - if the current thread is interrupted
- invokeAny
  
  public static <T> T invokeAny(List<Callable<T>> tasks, Duration timeout) throws InterruptedException
  
  Execute tasks in parallel with timeout, first to succeed wins 并行执行任务（带超时），任一成功即返回
  
  Type Parameters:
  
  T - the result type of the tasks
  
  Parameters:
  
  tasks - the list of tasks to execute
  
  timeout - the maximum time to wait
  
  Returns:
  
  the result from the first successful task
  
  Throws:
  
  InterruptedException - if the current thread is interrupted or timeout occurs
- parallel
  
  public static <T,U,R> R parallel(Callable<T> task1, Callable<U> task2, BiFunction<T,U,R> combiner) throws InterruptedException
  
  Execute two tasks in parallel and combine their results 并行执行两个任务并合并结果
  Both tasks must succeed. If either fails, the other is cancelled.
  
  两个任务必须都成功。如果任一失败，另一个将被取消。
  
  Type Parameters:
  
  T - the result type of the first task
  
  U - the result type of the second task
  
  R - the combined result type
  
  Parameters:
  
  task1 - the first task
  
  task2 - the second task
  
  combiner - the function to combine the two results
  
  Returns:
  
  the combined result
  
  Throws:
  
  InterruptedException - if the current thread is interrupted
- parallel
  
  public static <T,U,R> R parallel(Callable<T> task1, Callable<U> task2, BiFunction<T,U,R> combiner, Duration timeout) throws InterruptedException
  
  Execute two tasks in parallel with timeout and combine their results 并行执行两个任务（带超时）并合并结果
  
  Type Parameters:
  
  T - the result type of the first task
  
  U - the result type of the second task
  
  R - the combined result type
  
  Parameters:
  
  task1 - the first task
  
  task2 - the second task
  
  combiner - the function to combine the two results
  
  timeout - the maximum time to wait
  
  Returns:
  
  the combined result
  
  Throws:
  
  InterruptedException - if the current thread is interrupted or timeout occurs
- parallel
  
  public static <T1,T2,T3,R> R parallel(Callable<T1> task1, Callable<T2> task2, Callable<T3> task3, StructuredTaskUtil.TriFunction<T1,T2,T3,R> combiner) throws InterruptedException
  
  Execute three tasks in parallel and combine their results 并行执行三个任务并合并结果
  
  Type Parameters:
  
  T1 - the result type of the first task
  
  T2 - the result type of the second task
  
  T3 - the result type of the third task
  
  R - the combined result type
  
  Parameters:
  
  task1 - the first task
  
  task2 - the second task
  
  task3 - the third task
  
  combiner - the function to combine the three results
  
  Returns:
  
  the combined result
  
  Throws:
  
  InterruptedException - if the current thread is interrupted
- run
  
  public static <T> T run(Callable<T> task) throws InterruptedException
  
  Execute a single task with structured concurrency semantics 使用结构化并发语义执行单个任务
  This ensures the task completes or is cancelled before the scope exits.
  
  Type Parameters:
  
  T - the result type
  
  Parameters:
  
  task - the task to execute
  
  Returns:
  
  the result of the task
  
  Throws:
  
  InterruptedException - if the current thread is interrupted
- run
  
  public static <T> T run(Callable<T> task, Duration timeout) throws InterruptedException
  
  Execute a single task with timeout 执行单个任务（带超时）
  
  Type Parameters:
  
  T - the result type
  
  Parameters:
  
  task - the task to execute
  
  timeout - the maximum time to wait
  
  Returns:
  
  the result of the task
  
  Throws:
  
  InterruptedException - if the current thread is interrupted or timeout occurs

Class StructuredTaskUtil

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Details

invokeAll

invokeAll

invokeAny

invokeAny

parallel

parallel

parallel

run

run