Virtual Thread pinning怎么配置或排查

Virtual Thread pinning 通常不是“虚拟线程不能并发”，而是虚拟线程在需要等待时仍占着 carrier。Java 21 里最值得先查的是：synchronized 或同步方法包住了可能等待的 I/O，或者调用了 native/foreign 函数。本文只讨论 Java 21 的配置与排查路径。

官方资料：https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html

要点速览：先看 pinning 是否频繁且持续时间长；再用 JFR 或 jdk.tracePinnedThreads 找栈；最后只把长 I/O 从锁保护范围拆出去，不要为了消除一次事件而全量改写同步代码。

先判断 Virtual Thread pinning 是否真的有害

虚拟线程运行在 carrier（平台线程）上。遇到普通阻塞 I/O 时，虚拟线程通常可以卸载，carrier 去服务其他虚拟线程；但如果阻塞发生在 synchronized 块或同步方法中，Java 21 可能无法卸载，这就是 pinning。native 或 foreign function 也可能造成同类限制。

判断重点不是“出现过一次 pinning 就必须修”，而是看两个维度：是否频繁，以及等待是否足够长。启动阶段的一次同步初始化、只保护内存字段的短临界区，通常不值得改；请求路径里反复持锁访问数据库、HTTP、文件或阻塞队列，则应进入排查。

用 JFR 或 tracePinnedThreads 找到阻塞点

Java 21 的 JFR 提供 jdk.VirtualThreadPinned 事件，默认阈值为 20ms。先做一段有代表性的流量采集，再看事件的持续时间、阻塞操作和堆栈，而不是只看事件数量。

# 开启退出时写盘的 JFR 记录；文件名固定，便于后续分析
java -XX:StartFlightRecording=dumponexit=true,filename=virtual-thread.jfr \
  -jar app.jar

# 只打印虚拟线程相关事件；不要把普通日志误当成 pinning 证据
jfr print --events jdk.VirtualThreadPinned,jdk.VirtualThreadSubmitFailed virtual-thread.jfr

如果问题只在短时间窗口出现，可以临时用启动参数输出堆栈：

# short 只保留问题相关帧；现场信息不足时再改成 full
java -Djdk.tracePinnedThreads=short -jar app.jar

# full 会突出持有 monitor 的帧，适合第一次定位业务调用链
java -Djdk.tracePinnedThreads=full -jar app.jar

看到事件后，沿堆栈找两个交集：一是持有 monitor 的位置，二是实际等待的位置。只有“锁 + 可能长时间等待”同时存在，才是这篇文章要处理的 pinning 问题。

配置修复：把长 I/O 移出 synchronized

典型风险写法是把共享状态保护和外部调用放在同一个同步块里：

void refresh() {
    synchronized (cache) {
        // 共享状态和外部 I/O 被绑在一起，等待时可能 pin carrier
        cache.put("profile", client.fetchProfile());
    }
}

更稳妥的做法是先在锁外完成等待，再用短临界区提交结果。若业务必须在同一把锁下串行访问，也可以使用显式锁，并确保异常路径释放：

private final ReentrantLock lock = new ReentrantLock();

void refresh() {
    // 先做可能等待的调用，不把外部 I/O 放进 monitor
    Profile next = client.fetchProfile();
    lock.lock();
    try {
        // 锁只保护内存中的替换动作
        cache.put("profile", next);
    } finally {
        // 无论提交是否抛错，都必须释放显式锁
        lock.unlock();
    }
}

这不是机械替换规则。若“读取、校验、写回”必须保持一致性，应重新定义锁保护的共享状态和事务边界；不能为了绕开 pinning 而引入竞态。

哪些 pinning 不必急着改

复查时至少比较三件事：jdk.VirtualThreadPinned 的持续时间分布、carrier 是否长期忙于少数调用、业务吞吐是否改善。事件减少但锁语义被破坏，不算成功。

相关问题

pinning 会让程序直接报错吗？

通常不会。它首先是可伸缩性问题，表现为 carrier 被占用、并发等待变长或吞吐下降；是否严重要结合频率、持续时间和业务负载判断。

是不是所有 synchronized 都要换成 ReentrantLock？

不是。Java 21 官方建议优先处理频繁且可能长时间阻塞的同步区域；短时内存操作和低频逻辑可以保留更简单的 synchronized。

结论：先用 JFR 或启动参数拿到证据，再修改锁与 I/O 的边界；配置本身只是入口，真正的修复发生在持锁范围的重新设计。