Skip to content

2.4-8 ThreadLocal:原理、内存泄漏、跨线程传递 ​

所属:02 Java 运行时 / 2.4 并发 分级:A 状态:◐ 初稿 关联:2.4-1、2.4-6、2.4-11、2.4-12、2.1-9

  • 题型:原理 / 排查 / 场景

  • 一句话结论:ThreadLocal 是“线程封闭”工具,每个 Thread 持有自己的 ThreadLocalMap,key 弱引用、value 强引用;它用空间换隔离,但线程池复用线程时必须 remove(),否则会上下文串线和 value 泄漏;跨线程传递要靠 InheritableThreadLocal、TTL 或显式传参,虚拟线程时代优先评估 ScopedValue。

  • 分层要点:

    1. 数据结构:Thread 有两个字段 threadLocals 和 inheritableThreadLocals,类型都是 ThreadLocal.ThreadLocalMap。ThreadLocalMap 不是 java.util.Map,而是自定义的开放寻址哈希表:Entry[] table,初始容量 16,阈值 2/3;Entry 继承 WeakReference<ThreadLocal<?>>,key 是弱引用,value 是强引用。每个 ThreadLocal 构造时生成 threadLocalHashCode,用黄金比例增量 0x61c88647 递增,保证连续创建的 key 在 2 的幂大小的表里分布均匀。
    2. get / set / remove 流程:get() 先取当前线程的 map,再 getEntry(this),命中直接返回 value,未命中走 setInitialValue():调用 initialValue()(默认 null),map 不存在就 createMap,存在就 set。set() 从 hash 槽开始线性探测:key 相同就覆盖;遇到 key 为 null 的 stale entry 就 replaceStaleEntry;找到空槽插入后 cleanSomeSlots,必要时 rehash/resize。remove() 找到 key 后 clear() 并 expungeStaleEntry,把 value 和 Entry 一起清掉,同时把后续元素重新哈希填洞。
    3. 内存泄漏的真正原因:Thread -> ThreadLocalMap -> Entry -> value 是强引用链;key 只是弱引用。若 ThreadLocal 对象不再被外部强引用(例如方法里的局部变量、临时 new),key 会被 GC 成 null,但 value 仍被 Entry 强引用,Entry 又被长生命周期的线程持有。线程池 worker 不死,value 就一直活着;如果 value 是大对象、用户上下文或 ClassLoader,就是内存泄漏/类加载器泄漏。ThreadLocalMap 只在该 map 被 get/set/remove 时顺带清理 stale entry,没有后台线程,所以“不再访问”就等于永远不清理。
    4. 跨线程传递:InheritableThreadLocal 在 new Thread() 时由父线程复制 inheritableThreadLocals,childValue() 默认返回同一个 value 引用;它只解决“创建那一刻”的继承。线程池线程只创建一次,之后提交的任务不会重新继承,容易读到陈旧值;正确做法是 TTL(提交时 capture、执行时 replay、结束后 restore)、Spring TaskDecorator、MDC 手动 copy,或者显式把上下文作为参数传下去。CompletableFuture 默认异步、ForkJoinPool.commonPool 都不会自动传播 ThreadLocal。
    5. 典型场景与边界:常见用途是请求上下文(用户、租户、traceId/MDC)、事务连接绑定、SimpleDateFormat 等非线程安全对象的每线程副本、每线程缓冲区。ThreadLocal 只提供“每线程一份引用”,不保证 value 本身线程安全;如果多个线程拿到同一个可变对象,仍然要加锁或改用不可变对象。不要把它当缓存(每线程副本无界增长),也不要用它传递跨线程的业务参数。
    6. 生产实践:声明为 private static final ThreadLocal<...> 让 key 稳定、避免每次 new;在 finally 里 remove();Web 请求在 Filter/Interceptor 的 afterCompletion 清理;线程池任务用 TaskDecorator/TTL 包装;应用关闭、Tomcat 重新部署时清理,防止 value 持有 ClassLoader。排查时抓 heap dump,用 MAT 看 ThreadLocalMap$Entry 中 key 为 null 但 value 仍在的对象,再看 GC Root 路径。
  • 图/流程:

text
Thread
 ├─ threadLocals ──────────► ThreadLocalMap
 │                            table[] ──► Entry
 │                                        ├─ key: WeakReference<ThreadLocal> ──✗ 可被 GC
 │                                        └─ value: strong ──► 业务对象
 └─ inheritableThreadLocals ─► 父线程在 new Thread 时复制(childValue)
text
线程池 worker(长生命周期)
  └─ Thread.threadLocals ──► ThreadLocalMap ──► Entry
                                                  ├─ key = null(ThreadLocal 已被 GC)
                                                  └─ value = 用户上下文 / 大对象 / ClassLoader
                                                        ↑ 仍被强引用,泄漏
java
static class Entry extends WeakReference<ThreadLocal<?>> {
    Object value;
    Entry(ThreadLocal<?> k, Object v) {
        super(k);          // key 弱引用
        value = v;         // value 强引用
    }
}
  • 版本/源码锚点:

    • JDK 1.2:ThreadLocal、InheritableThreadLocal。
    • JDK 5:泛型化;JDK 7:ThreadLocalRandom(不走 ThreadLocalMap)。
    • JDK 8:ThreadLocal.withInitial(Supplier);当前 ThreadLocalMap 开放寻址实现。
    • JDK 21:虚拟线程正式(JEP 444);ScopedValue、结构化并发仍是 preview。
    • JDK 25:ScopedValue 正式(JEP 506);结构化并发仍是 preview(JEP 505)。
    • 源码:Thread.threadLocals、ThreadLocal.get/set/remove/createMap、ThreadLocalMap.Entry/set/getEntry/expungeStaleEntry/rehash/resize、ThreadLocal.createInheritedMap、InheritableThreadLocal.childValue。
    • 第三方:Alibaba TransmittableThreadLocal(TTL)2.x,非 JDK 标准。
  • ThreadLocal vs synchronized:

维度ThreadLocalsynchronized
解决问题线程隔离,每线程一份副本互斥,保护共享状态
方向空间换时间时间换空间
竞争无共享,通常无锁有竞争,可能阻塞
适用上下文、非线程安全对象副本计数器、共享资源临界区
风险泄漏、上下文串线死锁、锁粒度、性能
  • 跨线程传递方案:
方案原理适用局限
InheritableThreadLocalnew Thread 时复制父线程 map手动创建子线程线程池只继承一次,值会陈旧
TTL提交时 capture,执行时 replay,结束后 restore线程池、异步任务需包装或 agent,注意清理与开销
显式传参/上下文对象方法参数、RequestContext可控、可测试侵入业务签名
Spring TaskDecorator包装 Runnable,复制/清理 MDC 等@Async、Spring 线程池只覆盖 Spring 管理的任务
ScopedValue作用域绑定,子线程/结构化并发继承虚拟线程、请求上下文不可变,普通线程池仍需显式传递
  • 追问链:

    1. ThreadLocal 的原理? → 每个 Thread 有一个 ThreadLocalMap,以 ThreadLocal 对象为 key、业务对象为 value;get/set/remove 只操作当前线程的 map,所以天然隔离。
    2. 为什么 key 用弱引用、value 用强引用? → key 弱引用是为了 ThreadLocal 对象不再被使用时能被 GC;value 强引用是因为它是线程真正要用的数据,若也弱引用可能被意外回收。代价是 key 死后 value 仍被 Entry 持有,必须 remove()。
    3. ThreadLocal 内存泄漏是怎么发生的? → 线程池线程长期存活,ThreadLocal 对象被 GC 后 key 变 null,但 Entry 的 value 仍是强引用,且 map 只在被访问时才清理 stale entry,于是 value 和它引用的对象一直活着。
    4. 为什么线程池里必须 remove? → worker 线程会被复用,不清理会让下一个任务读到上一个请求的用户/trace/事务上下文,既串数据又泄漏;finally 里 remove 是底线。
    5. 用 static final 声明 ThreadLocal 就不会泄漏了吗? → 不会。static final 只保证 key 不被 GC,避免“key 为 null 的 stale entry”;如果 value 一直不 remove,仍然会随线程存活,属于逻辑泄漏。static final 是推荐写法,不是免死金牌。
    6. set(null) 和 remove() 有什么区别? → set(null) 仍然保留 Entry(key 还在,value 为 null);remove() 会清掉 Entry、value 并触发 expungeStaleEntry。线程池清理上下文应该用 remove()。
    7. ThreadLocalMap 为什么用开放寻址而不是链表? → 每个线程的 ThreadLocal 通常很少,开放寻址不需要额外 Node、内存更紧凑、局部性更好;冲突用线性探测,删除时 expungeStaleEntry 重新哈希填洞。
    8. 0x61c88647 是什么? → 黄金比例增量,用来生成 threadLocalHashCode,让连续创建的 ThreadLocal 在 2 的幂大小的表里均匀散布,减少碰撞。
    9. InheritableThreadLocal 的原理? → Thread 构造时如果 inheritThreadLocals=true,会把父线程的 inheritableThreadLocals 复制一份,value 默认经 childValue() 直接传引用;子线程之后 set 只改自己的 map,不影响父线程。
    10. 为什么线程池里 InheritableThreadLocal 会失效? → 线程池线程只在创建时继承一次,之后父线程再 set 不会同步;任务复用时读到的可能是创建时的旧值,甚至不同请求的值。要用 TTL 或显式传参。
    11. TTL 的原理? → 提交任务时捕获当前线程的 TTL 快照,任务执行前把快照回放到 worker 线程,执行完恢复 worker 原来的上下文;TtlRunnable/TtlCallable/TtlExecutors 或 Java Agent 做包装。
    12. ThreadLocal 能保证 value 线程安全吗? → 不能。它只保证每个线程拿到自己的引用;如果多个线程 set 了同一个可变对象,或者 value 内部引用共享状态,仍然要同步或使用不可变对象。
    13. ThreadLocal 和 ThreadLocalRandom 的关系? → ThreadLocalRandom 不是用 ThreadLocalMap,而是用 Thread 上的 threadLocalRandomSeed/probe 字段,避免每个线程维护 map 的开销和竞争,适合高并发随机数。
    14. ThreadLocal 在虚拟线程下有什么问题? → 每个虚拟线程也是 Thread,有自己的 ThreadLocalMap;虚拟线程数量可能很大,每线程一份上下文会放大内存。虚拟线程更适合用 ScopedValue 表达有界、不可变的上下文。
    15. ScopedValue 和 ThreadLocal 的区别? → ScopedValue 不可变、绑定在词法作用域内、离开作用域自动恢复、可被结构化并发子任务继承,不需要 remove;ThreadLocal 可变、生命周期跟随线程、需要手动清理。ScopedValue 不是可变线程状态的通用替代。
    16. Spring 里哪些地方用了 ThreadLocal? → RequestContextHolder 存请求属性、TransactionSynchronizationManager 绑定连接/事务、SecurityContextHolder 存安全上下文、LocaleContextHolder 等;异步/线程池场景要 TaskDecorator 或 TTL 传递。
    17. 怎么排查 ThreadLocal 泄漏? → jcmd/jmap 抓 heap dump,MAT 里看 ThreadLocalMap$Entry,找 key 为 null 但 value 很大的条目,再沿 GC Root 找到线程池 worker;结合代码检查是否在 finally remove、是否 static final、是否把大对象/ClassLoader 放进 value。
    18. ThreadLocal 会导致类加载器泄漏吗? → 会。若 value 持有应用类、ClassLoader 或框架对象,而 worker 线程生命周期超过应用,重新部署后旧 ClassLoader 无法回收;Tomcat 的 ThreadLocalLeakPreventionListener 只能在容器层兜底,应用仍要主动 remove。
  • 生产案例/取舍(示例,替换成你的项目):

    • 用户上下文用 ThreadLocal 缓存,线程池任务结束没有 remove;下一个请求复用到同一 worker,读到了上一个用户的权限,出现越权。修复:Filter 的 finally 中 UserContext.remove(),并加单测验证线程复用。
    • @Async 方法里 MDC 的 traceId 丢失,日志无法串联;用 TaskDecorator 在提交时复制 MDC.getCopyOfContextMap(),执行后 MDC.clear()。
    • SimpleDateFormat 写成 static 共享,偶发日期串位;改成 DateTimeFormatter(不可变、线程安全),或 ThreadLocal 包装并在 finally remove。
    • 异步任务里 @Transactional 失效,因为事务连接绑定在原线程的 ThreadLocal 上;改为在异步线程里用 TransactionTemplate 显式开事务,或把事务边界收回到调用线程。
    • Tomcat 重新部署后 Metaspace OOM,heap dump 发现 worker 线程的 ThreadLocal value 持有旧应用的 ClassLoader;在 contextDestroyed 中清理,并排查所有 ThreadLocal 的 remove。
    • 取舍:ThreadLocal 用空间换隔离,避免锁竞争;代价是每线程副本、必须清理、跨线程不自动传播。上下文传递优先显式参数或 TTL;虚拟线程 + 不可变上下文优先 ScopedValue。
  • 易错点:

    • 认为 key 是弱引用就不会泄漏,忽略 value 的强引用。
    • 认为 static final 就万事大吉,不 remove。
    • 线程池任务结束不清理 ThreadLocal,导致用户/trace/事务上下文串线。
    • 用 InheritableThreadLocal 解决线程池传递,结果读到创建时的旧值。
    • 认为 ThreadLocal 的值天然线程安全,多个线程共享同一个可变对象。
    • 把 ThreadLocal 当成本地缓存,value 随线程无界增长。
    • 用 set(null) 代替 remove(),Entry 仍然留在 map 里。
    • 在 CompletableFuture/parallelStream/commonPool 里直接 get(),以为会自动继承。
    • 虚拟线程里大量使用 ThreadLocal,忽略每线程 map 的内存放大。
    • value 持有 ClassLoader、连接、大 buffer,重新部署或长时间运行后 OOM。
    • 子线程修改 InheritableThreadLocal 以为会影响父线程;实际只改自己的 map,但可变 value 仍可能共享。
  • 30 秒口述稿:

ThreadLocal 是线程封闭工具,每个 Thread 有一个 ThreadLocalMap,key 是弱引用的 ThreadLocal,value 是强引用。get/set 只操作当前线程的 map,开放寻址,初始 16、阈值 2/3。内存泄漏的根源是线程池线程长活:ThreadLocal 对象被 GC 后 key 变 null,但 value 还被 Entry 强引用;所以要用 static final、finally remove。跨线程 InheritableThreadLocal 只在 new Thread 时复制,线程池里会陈旧,要用 TTL 或显式传参;虚拟线程时代可以用 ScopedValue。

  • 3 分钟展开顺序:结论(线程封闭 + 弱 key/强 value)→ Thread/ThreadLocalMap/Entry 结构 → get/set/remove 与开放寻址 → 内存泄漏链路与 remove → static final 的边界 → InheritableThreadLocal 与线程池失效 → TTL/TaskDecorator/显式传参 → ThreadLocal vs synchronized → 虚拟线程与 ScopedValue → 生产案例与排查。