Repository navigation
feat: 客户端虚拟线程化（工程改进第二项）——OTopic 派发线程虚拟线程化 + 阻塞 API 虚拟线程亲和契约 + 双绊线夹具 - #18
Merged
Merged
Conversation
- 改动（唯一运行时代码点）：RemoteTopic.Subscription 派发线程由平台线程改虚拟线程（Thread.ofVirtual().name("openlatch-topic-delivery-", 0).factory() 顺序号命名替随机后缀，setDaemon 随形态删除；deliveryLoop poll(200ms) 与无 interrupt/join 的关停链不动）——SDK 内唯一"按订阅 1:1 消耗平台线程"形态就此消灭；EventLoop/HashedWheelTimer/lockLostExecutor 保持平台线程为显式 Non-Goal（序列化契约已入规格与指南、定时精度与单条成本，改之无益）
- 契约：client-sdk 主规格新增"虚拟线程亲和"要求（阻塞调用面虚拟线程安全高效——桥接零钉扎源、归属键 threadId() 与中断语义形态无关、OTopic 交付每订阅一条虚拟线程且平台线程数不随订阅数增长、三类基建线程形态与数量承诺保持），6 场景
- 测试：新增 ClientVirtualThreadsIT 五用例——①OTopic 扇出平台线程数绊线（500 订阅一 key 一订阅：服务端 TopicRegistry (session,key) 唯一登记幂等覆盖，同会话同 key 多订阅只存续一路由，扇出形态据此实证修正；红先实测 +500 精确红于主断言且交付正确性断言先行绿，改后 ≤100 常数带）②万级虚拟线程等待者 90s 预算闭环（同规模平台线程不可启动的存在性证明，分批启动避每连接在途上限）③JFR jdk.VirtualThreadPinned 零断言（含预热轮：初版无预热窗读到 10 次事件，全归因 <clinit> 首触类初始化伪影/时长 0.004–0.86ms，桥接等待本体零事件；判例落 evidence）④虚拟线程归属矩阵（重入两次两次释放、他线程查询为假、非持锁 unlock 拒 IllegalMonitorStateException）⑤中断语义平台/虚拟两形态逐项一致（锁等待/队列 take/许可 acquire，补偿归还线复用）
- 基准：前后同形对比 p99 无实质劣化（topic 扇出 0.91→0.92ms），队列/原子/屏障多相上涨，扇出吞吐 -9.4% 属同量级双向波动带；harness 不输出线程数/RSS，RSS 如实标为未覆盖项（资源形态面由绊线证据承载）
- 验证：mvn clean verify 8/8 模块 BUILD SUCCESS（0 失败 0 错误；唯一跳过 ClientChaosIT 既有环境门槛）；-Pdrill 单轮全绿（RollingRestart 447s、LeaderKill、Partition、LeaderStallRepro 0 stall），drill 报告落 drill-logs；check-source-citations 零命中、check-links 零死链、openspec validate --specs --strict 17/17、主规格 sync 双查（无残留 delta 段头）
- 文档：双语指南 03 新增"虚拟线程"节与 OTopic 线程条措辞、10 兼容矩阵新增调用方线程形态行；ROADMAP 工程改进第二项 进行中→已落地（附归档链接）；OpenLatchClient/OTopic 契约 Javadoc 线程模型句同步
- 零新 wire 类型、不升协议门（维持 v11）、零公开 API 签名变更、无 BREAKING；change 归档至 openspec/changes/archive/2026-10-07-client-virtual-threads/
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
ROADMAP 工程改进第二项（客户端虚拟线程化）落地：把已成立的虚拟线程亲和钉为契约与常驻绊线，并消灭 SDK 内唯一"按订阅 1:1 消耗平台线程"的形态。
改动
RemoteTopic.Subscription派发线程 → 每次订阅一条虚拟线程（顺序号命名替随机后缀，setDaemon随形态删除；poll(200ms)与无 interrupt/join 的关停链不动）HashedWheelTimer/ lockLostExecutor（失锁回调专用单线程）保持平台线程——序列化契约已入规格与双语指南，改之只赔契约稳定--specs --strict17/17，无残留 delta 段头）ClientVirtualThreadsIT五用例——扇出平台线程数绊线（红先 +500 精确红 → 改后 ≤100）、万级虚拟线程等待者 90s 预算、JFRjdk.VirtualThreadPinned零断言（含预热轮，钉扎伪影归因见证据）、归属矩阵、中断语义两形态一致验证
Expecting 500 <= 100精确红（交付正确性断言先行绿），证据evidence/red-tripwire-fanout.mdClientVirtualThreadsIT5/5；ClientTopicIT5/5、RemoteTopicScriptedTest4/4 回归锚点全过clean verify8/8 模块 BUILD SUCCESS，0 失败 0 错误（唯一跳过ClientChaosIT既有环境门槛）-Pdrill单轮全绿（RollingRestart 447s / LeaderKill / Partition / LeaderStallRepro 0 stall），报告落drill-logs/check-source-citations零命中、check-links零死链、openspec validate --specs --strict17/17过程偏差（如实记账）
TopicRegistry按(session, key)唯一登记幂等覆盖，原设"10 key × 50 订阅"不成立 → 改 500 key × 1 订阅（design D5 已更注）<clinit>首触类初始化伪影（JVM 级，非桥接缺陷）→ 观测窗前加预热轮，判例落证据-am形态exec:java落根聚合 pom（判例变体）→ 基准复跑走 install + 单模块形态，与基线口径一致change 已归档至
openspec/changes/archive/2026-10-07-client-virtual-threads/（含 evidence 四件）。