QuestDB Carrier 本地存储（CarrierLocal）深度解析：让线程本地状态安全穿越可迁移 Fiber

QuestDB Carrier 本地存储CarrierLocal深度解析让线程本地状态安全穿越可迁移 Fiber【免费下载链接】questdbQuestDB is a high performance, open-source, time-series database项目地址: https://gitcode.com/gh_mirrors/qu/questdb本篇技术指南围绕 QuestDB 仓库内core/src/main/java/io/questdb/mp/continuation/CARRIER_LOCAL.md这份设计笔记展开系统讲解io.questdb.std.CarrierLocal与io.questdb.mp.CarrierIdentity两个核心类型为什么在基于原始jdk.internal.vm.Continuation的 Fiber 调度模型下ThreadLocal不再安全、Carrier 身份如何通过 FFI 关键下行调用critical downcall从 Rustthread_local!槽位读取以及按载体carrier索引的线程本地存储的内部实现。读完本文你将理解 QuestDB 查询 Fiber 在 worker 之间迁移时的线程本地状态保护机制掌握 bind/unbind 生命周期、id 回收、行隔离等关键不变量并能对照源码与测试用例自行验证其行为。背景Fiber 迁移模型与 ThreadLocal 的失效QuestDB 的Fiber直接使用 JDK 内部的jdk.internal.vm.Continuation见 Fiber.java 的import jdk.internal.vm.Continuation并以new ContinuationScope(questdb-fiber)Fiber.java创建作用域。在这种模型下一个查询可以在某个 worker载体线程上挂起yield之后可能被同一个 Fiber-host 池中的另一个 worker恢复resume。ThreadLocal.get()的解析路径是Thread.currentThread()。HotSpot 将这一调用建模为_currentThread内建函数intrinsicC2 编译器可能把它当作循环不变量提升hoist——也就是说在一次循环或一段代码区域内C2 认为Thread.currentThread()的返回值不会变化。问题是用户态原始 continuation 代码无法使用ChangesCurrentThread注解。该注解是 JDK 虚拟线程virtual threads受保护机制的一部分仅存在于引导类加载器boot loader中供 JDK 内部使用应用/库代码无法在任意类上标注它来告知 C2“这里 current thread 会变化”。因此一个已编译的查询 Fiber 体可能在冻结的栈帧中保留载体 A 的 JavaThread引用并在载体 B 恢复它之后仍然通过该引用读取载体 A 的ThreadLocalmap。如果载体 A 恰好也在并发地使用同一个条目那么两个载体就会通过同一个 holder 同时变更本应是单线程的状态——这就是跨载体数据竞争cross-carrier corruption的根源。需要特别澄清一个边界worker 主循环本身并不是 continuation因此该风险只存在于挂载在 Fiber 内部执行的代码。但 QuestDB 中共享的 SQL、日志、异常与协议辅助代码无法安全地假设调用方一定在 Fiber 之外所以必须让这些共享代码也具备“载体感知”的线程本地存储能力。CarrierIdentity进程级载体身份原语CarrierIdentity的核心职责是为当前实际执行代码的 OS 线程分配一个进程内唯一的整数标识carrier id并在任何时刻都能读取到这个标识。bind入口绑定CarrierIdentity.bind()分配一个进程级整数并固定到当前 OS 线程CarrierIdentity.javapublic static int bind() { IdHolder holder new IdHolder(); int id RECYCLED.tryDequeue(holder) ? holder.id : NEXT_ID.getAndIncrement(); try { BIND.invokeExact(id); // - qdb_carrier_bind(id) } catch (RuntimeException | Error e) { throw e; } catch (Throwable t) { throw new AssertionError(t); } return id; }id 分配遵循“先用回收池、再递增新号”的策略被unbind()释放的 id 会被放入RECYCLED队列ConcurrentQueueIdHolder优先复用以约束CarrierLocal行索引在整个 JVM 生命周期内的上界。worker 线程和 timer-shard 线程在进入时绑定、退出时解绑worker 线程Worker.run()中进入主循环前调用CarrierIdentity.bind()Worker.java在finally退出路径中调用CarrierIdentity.unbind()Worker.javatimer-shard 线程TimerShards中同样在入口绑定TimerShards.java、出口解绑TimerShards.java。为什么不能用 pool 局部的 worker id因为每个 QuestDB worker 池都从 0 开始给自己的 worker 编号不同池的 worker 会撞到相同的 id在CarrierLocal中就会别名到同一行产生串扰。所以必须使用进程级 id。current透过 FFI 读取 Rust TLS 槽位CarrierIdentity.current()通过 FFI关键下行调用读取 Rust 侧thread_local!槽位CarrierIdentity.javaqdb_carrier_bind(int)写入 idqdb_carrier_current()读取 id。两个符号在静态初始化块中通过SymbolLookup.loaderLookup()与Linker.nativeLinker()绑定为MethodHandleCarrierIdentity.javaBIND linker.downcallHandle( lookup.find(qdb_carrier_bind).orElseThrow(...), FunctionDescriptor.ofVoid(ValueLayout.JAVA_INT), Linker.Option.critical(false)); CURRENT linker.downcallHandle( lookup.find(qdb_carrier_current).orElseThrow(...), FunctionDescriptor.of(ValueLayout.JAVA_INT), Linker.Option.critical(false));这段代码还包含一个启动约束CarrierIdentity要求 64 位 JVMOs.type Os._32Bit时抛出ExceptionInInitializerError并且静态初始化会强制加载 Rustcdyliblibquestdbr。为什么必须走 FFI因为“对 C2 不透明”是设计目标。Rust 侧的实现是 const 初始化的thread_local!carrier.rsthread_local! { static CARRIER_ID: Celli32 const { Cell::new(-1) }; } #[no_mangle] pub extern C fn qdb_carrier_bind(id: i32) { CARRIER_ID.with(|c| c.set(id)); } #[no_mangle] pub extern C fn qdb_carrier_current() - i32 { CARRIER_ID.with(|c| c.get()) }由于槽位使用 const 初始化器const { Cell::new(-1) }正常读取是直接的本地 TLS 访问没有惰性初始化的开销。更重要的是Linker.Option.critical(false)的关键下行调用对 C2 是不透明的C2 无法把这个调用与一个被提升的 JavaThread引用折叠fold到一起从而杜绝了“C2 以为 current carrier 不变”的错误优化。这里还有一个跨组件约束OSS 与企业版代码都必须使用libquestdbr中的同一组符号因为独立的cdylib文件拥有独立的本地 TLS 槽位——如果两边各加载一份动态库id 读写就会各自为政、互不可见。文档同时给出了一个前瞻性风险提示如果未来某个 JDK 版本将关键下行调用视为可折叠foldable那么在使用 carrier-local 状态前应把该调用改为非关键下行调用或 JNI。unbind出口解绑与 id 回收CarrierIdentity.unbind()CarrierIdentity.java做三件事且顺序敏感CarrierLocal.releaseRow(id)—— 清空该载体对应的CarrierLocal行通过qdb_carrier_bind(UNBOUND)把 Rust TLS 槽位重置为-1把 id 推入RECYCLED队列。注释明确解释了顺序的重要性必须先清空行、再重置 Rust TLS最后才能把 id 放回回收池否则一个并发的bind()弹出该 id 时会观察到陈旧的CarrierLocalmap。unbind()是幂等的在从未bind()过的线程上调用是 no-op因为current() 0。未绑定线程的语义从未调用bind()的线程Bootstrap、测试、关闭钩子等通过current()读到UNBOUND -1CarrierIdentity.java。这类线程正常情况下不会在原始 continuation 内部迁移因此它们走CarrierLocal的 JavaThreadLocal兜底路径即可。CarrierLocal按载体索引的线程本地存储CarrierLocalT是面向使用方的 API。其核心数据结构是private static volatile CarrierLocalMap[] rows new CarrierLocalMap[0];外层是一个按 carrier id 索引的数组每个绑定的载体拥有一行CarrierLocalMap内层 map 以CarrierLocal实例为键。get()用当前 carrier id 选择[carrierId][key]条目——所以被恢复的查询读到的是当前执行它的 worker的行而不是冻结帧中残留的旧值CarrierLocal.java。内层 CarrierLocalMapThreadLocalMap 的移植CarrierLocalMap是java.lang.ThreadLocal.ThreadLocalMap的直接移植CarrierLocal.java开放寻址哈希表初始容量 16threshold len * 2 / 3弱引用键Entry extends WeakReferenceCarrierLocal?CarrierLocal.java当某个CarrierLocal实例不可达时GC 清除弱引用后续触碰到该桶的操作会顺带驱逐expunge陈旧条目由此每个载体 map 的大小只与“活着的键”成正比而不是与历史累计创建的CarrierLocal个数成正比——这避免了长期运行中的内存膨胀。哈希种子使用经典常量HASH_INCREMENT 0x61c88647CarrierLocal.java配合开放寻址可获得较好的分布。整个内层 map只允许所属载体线程单线程访问single-thread access only这是其无需加锁的性能前提。外层数组的增长发生在类监视器synchronized (CarrierLocal.class)之下并通过rows的 volatile 写发布createMap中rows r的 volatile 自赋值用于发布r[id]的普通写配合读者端的 volatile 读rows避免读到“新 map 引用但内容未初始化”的中间态见 CarrierLocal.java。API 一览方法行为get()以CarrierIdentity.current()为索引取当前载体的条目不存在则调用初始工厂并写入CarrierLocal.javaget(int carrierId)接受调用方已采样的 id适合需要分支判断的场景省一次下行调用set(T value)写入当前载体对应行未绑定线程写入 fallbackremove()删除当前载体条目与 JDKThreadLocal语义一致不关闭值交由 GC 回收先置value null再触发 map 删除避免陈旧条目清扫误触发 close 副作用见 CarrierLocal.javaremoveAndFree()若值是Closeable则调用Misc.freeIfCloseable后再删除条目适合持有 native 资源需要急切释放的场景CarrierLocal.javastatic releaseRow(int id)由CarrierIdentity.unbind()调用置空外层行使 map 可被 GC防止线程反复创建/销毁导致rows无界增长CarrierLocal.java未绑定线程的 Java ThreadLocal 兜底对于CarrierIdentity.current() 0的线程CarrierLocal退化为一个惰性初始化的java.lang.ThreadLocalTfallbackCarrierLocal.java。设计注释特别说明fallback 字段仅在“未绑定线程第一次触碰该实例”时才会分配生产路径carrier-bound 访问永远不会触及它——考虑到代码库中约有 70 处CarrierLocal调用点这种延迟分配是有意为之的成本优化。关键不变量设计文档明确列出五条必须遵守的不变量违反任何一条都会引入跨载体数据竞争或泄漏每个 carrier 线程在运行查询 Fiber 或 carrier-local 代码之前必须先bind()只能在该 carrier 的退出路径上unbind()当值代表“载体限定carrier-confined的可变状态”时严禁把CarrierIdentity.current()或 carrier-local 值缓存在一次挂起suspension的跨越点上——因为恢复后载体可能已经变了必须使用进程级 carrier id而不是 pool worker id各池 worker 编号从 0 重复在unbind()之前显式释放 native 资源例如通过removeAndFree()因为清空一行并不会关闭任意值。验证与测试如何证明跨载体安全设计文档指出验证分为三个层面1. 单元测试Java 侧CarrierLocalTest.java 覆盖了绑定、id 回收、行隔离与跨载体迁移的核心语义包括绑定与默认值testBoundDefaultIsNull、testBoundSetGetRoundtrip初始化语义testBoundInitialValueOnlyCalledOncePerCarrier、testReentrantInitialValueReadingDifferentCarrierLocal、testReentrantSetWithinOwnInitialValueWins移除语义testRemoveDoesNotCloseValueMatchingJdkSemantics、testRemoveAndFreeFreesCloseableValueOnCurrentCarrier行隔离testTwoBoundCarriersDoNotShareValues、testIsolationAcrossCarriersIndependentValues、testConcurrentDifferentCarriersStress8 个 carrier 各跑 10K 次 set/get 验证 map 操作不被并发破坏id 回收与新鲜度testRecycledIdSeesFreshSlotNotPriorValue、testTightRecycleCycleEachCycleSeesFreshSlot、testRebindCycleNoLeakAcrossCarriers验证releaseRow每次 unbind 都丢弃整张表旧值不会泄漏到新 id陈旧条目清扫testStaleEntryChurnExercisesExpungePaths、testStaleEntryReclaimedAfterCarrierLocalUnreachableGC 后条目应可回收证明 expunge 逻辑未绑定兜底testUnboundFallbackInitialPerThread、testUnboundRemoveAndFreeAfterSetClosesCloseable等。2. 单元测试Rust 侧carrier.rs 自带两个#[test]bind_and_read_round_trip验证qdb_carrier_current()初始为-1绑定 7、0 后分别读回distinct_threads_have_distinct_slots验证不同 OS 线程拥有各自独立的 TLS 槽位互不干扰。3. 集成测试HTTP/PG 的 sleep 场景与wait_wal_table()集成测试会让查询 Fiber 在真实生产 Fiber 路径上发生载体迁移挂起、被其他 worker 恢复从端到端角度验证迁移安全。设计文档还坦率地指出了测试的边界C2 失败取决于编译与内联形态compilation and inlining shape一个小的、仅解释器模式的测试无法完整复现。因此启用日志的并发挂起压力测试logging-enabled concurrent suspension stress仍然是最有效的端到端守护手段。相关文件索引文件作用CARRIER_LOCAL.md本文依据的设计笔记本仓库内CarrierIdentity.java载体身份bind/current/unbind 与 FFI 下行调用绑定CarrierLocal.javacarrier-keyed 线程本地存储实现carrier.rsRust 侧thread_local!槽位与两个extern C符号Worker.javaworker 线程的 bindL197/ unbindL267生命周期TimerShards.javatimer-shard 线程的 bindL363/ unbindL395Fiber.java基于jdk.internal.vm.Continuation的 Fiber 实现CarrierLocalTest.java绑定、回收、隔离、迁移相关的单元测试注意设计笔记中给出的 Rust 路径为core/rust/qdbr/src/carrier.rs而仓库实际文件位于core/rust/qdbr/src/ffi/carrier.rsffi子目录下阅读源码时请以实际路径为准。【免费下载链接】questdbQuestDB is a high performance, open-source, time-series database项目地址: https://gitcode.com/gh_mirrors/qu/questdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考