结构化并发：把子任务关进词法作用域

API 形状：open、Joiner、Subtask01

JDK 25 的 StructuredTaskScope 是接口，不能 new。用静态 open() 创建；无参 open() 使用默认策略：等待所有子任务成功，任一失败就取消其余。更复杂的完成策略由 Joiner 表达。

public sealed interface StructuredTaskScope<T, R>
        extends AutoCloseable {
    static <T> StructuredTaskScope<T, Void> open();
    static <T, R> StructuredTaskScope<T, R> open(
            Joiner<? super T, ? extends R> joiner);
    static <T, R> StructuredTaskScope<T, R> open(
            Joiner<? super T, ? extends R> joiner,
            Function<Configuration, Configuration> config);

    <U extends T> Subtask<U> fork(Callable<? extends U> task);
    <U extends T> Subtask<U> fork(Runnable task);
    R join() throws InterruptedException;
    boolean isCancelled();
    void close();
}

Configuration 提供 withTimeout(Duration)、withName(String)、withThreadFactory(ThreadFactory)。超时从 open 开始计时；到期后作用域被取消，join() 抛 TimeoutException。

public interface Configuration {
    Configuration withThreadFactory(ThreadFactory factory);
    Configuration withName(String name);
    Configuration withTimeout(Duration timeout);
}

失败、超时与取消：短路，但不是强杀02

默认策略下，任一子任务抛异常，作用域立即取消其余子任务，join() 抛 FailedException，原始异常在 cause 中。被取消的子任务状态是 UNAVAILABLE；这不是「没开始」，而是「没有可用结果」。

import java.util.concurrent.*;
import java.time.Duration;

public class ScopePolicies {
    public static void main(String[] args) throws Exception {
        try (var scope = StructuredTaskScope.open()) {
            scope.fork(() -> 1);
            scope.fork(() -> 2);
            System.out.println("default join=" + scope.join());
            System.out.println("cancelled=" + scope.isCancelled());
        }

        try (var scope = StructuredTaskScope.open(
                StructuredTaskScope.Joiner.<String>allSuccessfulOrThrow())) {
            scope.fork(() -> "ok");
            scope.fork(() -> { throw new IllegalStateException("boom2"); });
            try {
                scope.join();
            } catch (StructuredTaskScope.FailedException e) {
                System.out.println("allSuccessful failed=" + e.getCause());
            }
        }

        try (var scope = StructuredTaskScope.open(
                StructuredTaskScope.Joiner.<String>anySuccessfulResultOrThrow())) {
            scope.fork(() -> { throw new IllegalStateException("first-fail"); });
            scope.fork(() -> { Thread.sleep(50); return "second-ok"; });
            System.out.println("any=" + scope.join());
        }

        try (var scope = StructuredTaskScope.open(
                StructuredTaskScope.Joiner.<String>anySuccessfulResultOrThrow())) {
            scope.fork(() -> { throw new IllegalStateException("a"); });
            scope.fork(() -> { throw new IllegalArgumentException("b"); });
            try {
                scope.join();
            } catch (StructuredTaskScope.FailedException e) {
                System.out.println("any all failed=" + e.getCause());
            }
        }

        try (var scope = StructuredTaskScope.open(
                StructuredTaskScope.Joiner.<String>allSuccessfulOrThrow(),
                cfg -> cfg.withTimeout(Duration.ofMillis(80)))) {
            scope.fork(() -> { Thread.sleep(1000); return "late"; });
            try {
                scope.join();
            } catch (StructuredTaskScope.TimeoutException e) {
                System.out.println("timeout=" + e.getClass().getSimpleName());
            }
        }
    }
}

javac --release 25 --enable-preview ScopePolicies.java
java --enable-preview ScopePolicies

default join=null
cancelled=false
allSuccessful failed=java.lang.IllegalStateException: boom2
any=second-ok
any all failed=java.lang.IllegalStateException: a
timeout=TimeoutException

1. 默认 open()：全部成功，join() 返回 null，isCancelled() 为 false。
2. allSuccessfulOrThrow()：一个失败，join 抛 FailedException，cause 是原始异常。
3. anySuccessfulResultOrThrow()：一个失败但另一个成功，join 返回成功结果。
4. 同一 Joiner 下全部失败：join 抛 FailedException，cause 是其中一个失败。
5. 超时：作用域取消，join 抛 TimeoutException；它不是 FailedException 的子类。

取消通过中断传播。子任务如果正在 sleep、阻塞 I/O 或可中断的锁上，会收到 InterruptedException；如果它吞掉中断或阻塞在不可中断操作上，close() 只能等它自然结束。结构化并发保证的是「不遗弃」，不是「瞬间杀死」。

owner、fork 与 Subtask 的运行时规则03

作用域绑定到打开它的 owner 线程。只有 owner 能 fork/join；Subtask 的结果只能在 join 之后读取；作用域不能逃逸出词法块，也不能交给别的线程复用。

import java.util.concurrent.*;

public class ScopeRules {
    public static void main(String[] args) throws Exception {
        try (var scope = StructuredTaskScope.open()) {
            var subtask = scope.fork(() -> 1);
            try {
                subtask.get();
            } catch (Exception e) {
                System.out.println("get before join=" + e.getClass().getSimpleName());
            }

            var nested = scope.fork(() -> {
                try {
                    scope.fork(() -> 2);
                    return "forked";
                } catch (Exception e) {
                    return e.getClass().getSimpleName();
                }
            });
            scope.join();
            System.out.println("subtask state=" + subtask.state());
            System.out.println("fork from subtask=" + nested.get());
        }
    }
}

get before join=IllegalStateException
subtask state=SUCCESS
fork from subtask=WrongThreadException

模式：允许部分失败时，用 awaitAll 收结果01

默认策略和 allSuccessfulOrThrow() 都是 fail-fast：一个失败就取消其余。若业务允许「部分成功」，用 awaitAll() 等全部结束，再逐个检查状态。下面的输出来自本机验证。

import java.util.concurrent.*;

public class PartialResults {
    public static void main(String[] args) throws Exception {
        try (var scope = StructuredTaskScope.open(
                StructuredTaskScope.Joiner.<String>awaitAll())) {
            var ok = scope.fork(() -> "ok");
            var bad = scope.fork(() -> {
                throw new IllegalStateException("bad");
            });
            scope.join();
            System.out.println("ok=" + ok.state() + "/" + ok.get());
            System.out.println("bad=" + bad.state() + "/" + bad.exception());
        }
    }
}

ok=SUCCESS/ok
bad=FAILED/java.lang.IllegalStateException: bad

• awaitAll() 不因失败取消，适合批量导入、可选 enrichment、部分结果可用的场景。
• awaitAllSuccessfulOrThrow() 也等待全部，但只要有一个失败就抛 FailedException。
• 失败任务的结果不要调 get()；先看 state()，需要原因时用 exception()。
• 部分结果模式要定义清楚：失败是跳过、降级，还是整体失败。不要用 awaitAll 逃避错误处理。

常见坑02

• 忘记 --enable-preview：编译和运行两端都要加，且必须是同一个 JDK 版本。
• 照搬 21 的 API：ShutdownOnFailure / ShutdownOnSuccess / joinUntil 在 25 已移除。
• 把 TimeoutException 当 FailedException 捕：超时会直接逃出 catch，close 仍会执行。
• 吞掉中断：子任务不响应中断，close 会一直等到它结束；取消不是强杀。
• 作用域逃逸：把 scope 存字段、跨请求复用或交给别的线程，会触发结构检查异常。
• 共享可变状态：子任务并发执行，普通集合/计数器仍需要同步或并发容器。
• 在子任务里再 fork 同一个 scope：fork 只能由 owner 线程调用，子任务里会抛 WrongThreadException。

合上页面，先回答01

版本边界：21 与 25 不能直接互换02

import java.util.concurrent.*;

public class OldApi {
    void fetch() throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            scope.fork(() -> "a");
            scope.join().throwIfFailed();
        }
    }
}

javac --release 25 --enable-preview OldApi.java

OldApi.java:5: error: cannot find symbol
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
                                                ^
  symbol:   class ShutdownOnFailure
  location: interface StructuredTaskScope
Note: OldApi.java uses preview features of Java SE 25.
Note: Recompile with -Xlint:preview for details.
1 error

两边都叫「预览」，但 API 形状不兼容。21 的预览 class 是 65.65535，25 只识别 69.65535；升级时必须重写并重新编译，不能只改启动参数。