《Java 并发编程·线程与内存模型》附录 A 并发 API 速查

怎么用这份速查

这份附录不解释原理，只解决一个问题：写代码时想不起签名。每一行给出「有哪几个方法、哪个是关键、边界在哪」，原理回到对应章节。

三条阅读约定：方法名省略类名但保留参数类型，签名以 JDK 25 为准，Thread.getId() 这类已弃用方法不收录；「边界」一列只写最容易踩的那一点，不是完整说明；标 P 的是 preview API，编译和运行都要 --enable-preview，其余都是稳定 API。

全书只有 StructuredTaskScope 一个 preview API。ScopedValue 在 JDK 25 已经转正，可以按稳定 API 写。

线程与执行

创建与属性

中断与协作

Thread.interrupted() 的清除行为是最常见的坑：在 catch 块里写 if (Thread.interrupted()) 会把标志吃掉，后续代码再也看不到中断。恢复中断用 Thread.currentThread().interrupt()。

执行器

前三个工厂的无界队列是生产事故的常见来源：任务提交速度持续高于处理速度时，队列会一直涨到 OOM。需要背压就用 new ThreadPoolExecutor(...) 显式指定有界队列和拒绝策略。

ThreadPoolExecutor 七参数

执行顺序是：核心线程未满则新建 → 否则入队 → 队列满则扩容到 max → 仍满则拒绝。很多「池不扩容」的问题，根因是队列无界，永远走不到第三步。

提交与关闭

submit 吞异常是本卷反复出现的问题：返回的 Future 不调用 get()，任务里抛出的异常就永远不会被任何人看到。

定时任务

任务抛异常会取消后续所有执行，且不打印任何东西。11.1 节有实测。

同步器

锁

StampedLock 的乐观读不阻塞写线程，适合「读多、读到的值可以重算」的缓存场景：

final class StockCache {
    private final StampedLock lock = new StampedLock();
    private long stock;

    long read() {
        long stamp = lock.tryOptimisticRead();
        long value = stock;
        if (lock.validate(stamp)) {
            return value;
        }
        stamp = lock.readLock();
        try {
            return stock;
        } finally {
            lock.unlockRead(stamp);
        }
    }

    void write(long next) {
        long stamp = lock.writeLock();
        try {
            stock = next;
        } finally {
            lock.unlockWrite(stamp);
        }
    }
}

乐观读返回的 stamp 必须交给 validate 校验，忘了这一步就等于读到脏值。

条件队列

await 必须放在 while (!condition) 循环里，理由见 5.2 节。Condition 相比 Object.wait 的唯一实质优势是能按条件分组，避免 notifyAll 唤醒无关线程。

协作工具

CountDownLatch 的计数归零后不能重置，需要重复使用就选 CyclicBarrier 或 Phaser。Semaphore 的 release() 可以超出许可数，写错会悄悄放宽限流，因此 acquire() 必须放在 try 外面：放在里面时 acquire 抛异常，finally 仍会 release()，许可数就会凭空增加。

并发容器

Map

ConcurrentHashMap 不允许 null 键和 null 值，这一点与 HashMap 不同。computeIfAbsent 的映射函数如果递归修改同一个 map，会死锁或抛 IllegalStateException。

队列

四个核心方法的分工：

DelayQueue 的元素必须实现 Delayed，getDelay 返回剩余时间。关闭队列时不要只置一个 volatile boolean 标志，阻塞在 take() 的消费者不会被唤醒，要投递哨兵元素（5.3 节实测过这个死锁）。

其他容器

CopyOnWriteArrayList 读无锁、写持锁并全量复制数组，只适合「读远多于写、集合小」；它的迭代器是快照，迭代期间的修改看不到，也不会抛 ConcurrentModificationException，元素上千且写入频繁时开销无法接受。ConcurrentLinkedQueue 读写都无锁，但 size() 是 O(n)。ConcurrentSkipListMap / ConcurrentSkipListSet 读写都是对数复杂度，需要有序遍历或有序去重时才用。

原子类与字段更新器

基本原子类

weakCompareAndSet 系列从 JDK 9 起被标为弃用，JDK 25 上调用会有弃用警告。需要 CAS 就用 compareAndSet。

引用与标记

AtomicStampedReference 的 compareAndSet 是四参数：期望引用、新引用、期望戳、新戳。只传引用不传戳的写法在 JDK 25 上不存在，写错会编译失败。

累加器

LongAdder 在低竞争下比 AtomicLong 慢，因为要多一次 Cell 定位。它适合「写多读少」的统计计数，不适合需要读到精确当前值的场景（如库存）。

字段更新器与 VarHandle

字段更新器不满足前提时会抛 IllegalArgumentException，消息分别是 Must be volatile type、Must be integer type。这些报错在 8.2 节有实测输出。

VarHandle 的内存序方法对照：

虚拟线程与结构化并发

虚拟线程

虚拟线程不需要池化。用 newFixedThreadPool 包一层，等于把 M:N 调度退化成 M:1，白白丢掉它的全部优势。

ScopedValue（已转正）

绑定不可变，出了 run / call 自动解除，普通线程不会继承。它不替代互斥，只替代「隐式传参」那一半的 ThreadLocal。

结构化并发（preview）

ShutdownOnFailure 和 ShutdownOnSuccess 在 JDK 25 已经不存在，网上大量示例仍在用它们。JDK 25 的写法是 open(Joiner.allSuccessfulOrThrow()) 这类静态工厂。

Reservation reserve(String isbn, String memberId) throws Exception {
    try (var scope = StructuredTaskScope.open(Joiner.allSuccessfulOrThrow())) {
        var stock = scope.fork(() -> bookRepository.findByIsbn(isbn));
        var quota = scope.fork(() -> quotaOf(memberId));
        scope.join();
        return decide(stock.get(), quota.get());
    }
}

这段代码必须用 --enable-preview 编译和运行，且 close() 会取消所有未完成的子任务。

方法命名规律

最容易混的是 getAndX 与 XAndGet：自增并返回旧值还是新值，决定了计数从 0 开始还是从 1 开始，差一位的 bug 往往就出在这里。

我要做什么 → 用哪个

什么时候不要用（反查）

速查只列卷一覆盖的 API。AQS 队列、ConcurrentHashMap 的 bin 锁与扩容、Striped64 分片、CompletableFuture 的依赖触发顺序，源码在卷二展开；线程池指标与 jcmd/jstack/JFR 的线上用法在卷三展开，附录 B 给出命令与事件的实际输出。