📌 TransmittableThreadLocal(TTL) 📌

📖 English Documentation | 📖 中文文档

• 🔧 功能
• 🎨 需求场景
• 👥 User Guide
  • 1. 简单使用
  • 2. 保证线程池中传递值
    • 2.1 修饰

      Runnable

      和

      Callable

      • 整个过程的完整时序图
    • 2.2 修饰线程池
    • 2.3 使用

      Java Agent

      来修饰

      JDK

      线程池实现类

      • Java Agent

        的启动参数配置
      • 关于

        boot class path

• 🔌 Java API Docs
• 🍪 Maven依赖
• 🔨 关于编译构建与

  IDE

  开发
• ❓ FAQ
• ✨ 使用

  TTL

  的好处与必要性
• 🗿 更多文档
• 📚 相关资料
  • JDK Core Classes
• 👷 Contributors

🔧 功能

👉 在使用线程池等会池化复用线程的执行组件情况下，提供

ThreadLocal

Java

Java

JDK

InheritableThreadLocal

ThreadLocal

ThreadLocal

本库提供的

TransmittableThreadLocal

InheritableThreadLocal

整个

TransmittableThreadLocal

API

API

ExecutorService

ForkJoinPool

TimerTask

Wrapper

SLOC

欢迎 👏

• 建议和提问，提交 Issue
• 贡献和改进，Fork 后提通过 Pull Request 贡献代码

🎨 需求场景

ThreadLocal

TransmittableThreadLocal

ThreadLocal

TransmittableThreadLocal

下面是几个典型场景例子。

1. 分布式跟踪系统 或 全链路压测（即链路打标）
2. 日志收集记录系统上下文

3. Session

   级

   Cache

4. 应用容器或上层框架跨应用代码给下层

   SDK

   传递信息

各个场景的展开说明参见子文档 需求场景。

👥 User Guide

使用类

TransmittableThreadLocal

TransmittableThreadLocal

InheritableThreadLocal

InheritableThreadLocal

1. copy

   方法
   用于定制 任务提交给线程池时 的

   ThreadLocal

   值传递到 任务执行时 的拷贝行为，缺省传递的是引用。
   注意：如果跨线程传递了对象引用因为不再有线程封闭，与

   InheritableThreadLocal.childValue

   一样，使用者/业务逻辑要注意传递对象的线程安全。

2. protected

   的

   beforeExecute

   /

   afterExecute

   方法
   执行任务(

   Runnable

   /

   Callable

   )的前/后的生命周期回调，缺省是空操作。

具体使用方式见下面的说明。

1. 简单使用

父线程给子线程传递值。

示例代码：

TransmittableThreadLocal context = new TransmittableThreadLocal<>();

// =====================================================
// 在父线程中设置
context.set("value-set-in-parent");
// =====================================================
// 在子线程中可以读取，值是"value-set-in-parent"
String value = context.get();

# 完整可运行的Demo代码参见

SimpleDemo.kt

这是其实是

InheritableThreadLocal

InheritableThreadLocal

但对于使用线程池等会池化复用线程的执行组件的情况，线程由线程池创建好，并且线程是池化起来反复使用的；这时父子线程关系的

ThreadLocal

ThreadLocal

解决方法参见下面的这几种用法。

2. 保证线程池中传递值

2.1 修饰

Runnable

和

Callable

使用

TtlRunnable

TtlCallable

Runnable

Callable

示例代码：

TransmittableThreadLocal context = new TransmittableThreadLocal<>();

// =====================================================
// 在父线程中设置
context.set("value-set-in-parent");
Runnable task = new RunnableTask();
// 额外的处理，生成修饰了的对象ttlRunnable
Runnable ttlRunnable = TtlRunnable.get(task);
executorService.submit(ttlRunnable);
// =====================================================
// Task中可以读取，值是"value-set-in-parent"
String value = context.get();

上面演示了

Runnable

Callable

TransmittableThreadLocal context = new TransmittableThreadLocal<>();

// =====================================================
// 在父线程中设置
context.set("value-set-in-parent");
Callable call = new CallableTask();
// 额外的处理，生成修饰了的对象ttlCallable
Callable ttlCallable = TtlCallable.get(call);
executorService.submit(ttlCallable);
// =====================================================
// Call中可以读取，值是"value-set-in-parent"
String value = context.get();

# 完整可运行的Demo代码参见

TtlWrapperDemo.kt

整个过程的完整时序图

2.2 修饰线程池

省去每次

Runnable

Callable

通过工具类

com.alibaba.ttl.threadpool.TtlExecutors

• getTtlExecutor

  ：修饰接口

  Executor

• getTtlExecutorService

  ：修饰接口

  ExecutorService

• getTtlScheduledExecutorService

  ：修饰接口

  ScheduledExecutorService

示例代码：

ExecutorService executorService = ...
// 额外的处理，生成修饰了的对象executorService
executorService = TtlExecutors.getTtlExecutorService(executorService);

TransmittableThreadLocal context = new TransmittableThreadLocal<>();
// =====================================================
// 在父线程中设置
context.set("value-set-in-parent");
Runnable task = new RunnableTask();
Callable call = new CallableTask();
executorService.submit(task);
executorService.submit(call);
// =====================================================
// Task或是Call中可以读取，值是"value-set-in-parent"
String value = context.get();

# 完整可运行的Demo代码参见

TtlExecutorWrapperDemo.kt

2.3 使用

Java Agent

来修饰

JDK

线程池实现类

这种方式，实现线程池的传递是透明的，业务代码中没有修饰

Runnable

Java Agent

示例代码：

// ## 1. 框架上层逻辑，后续流程框架调用业务 ##
TransmittableThreadLocal context = new TransmittableThreadLocal<>();
context.set("value-set-in-parent");

// ## 2. 应用逻辑，后续流程业务调用框架下层逻辑 ##
ExecutorService executorService = Executors.newFixedThreadPool(3);
Runnable task = new RunnableTask();
Callable call = new CallableTask();
executorService.submit(task);
executorService.submit(call);
// ## 3. 框架下层逻辑 ##
// Task或是Call中可以读取，值是"value-set-in-parent"
String value = context.get();

Demo参见

AgentDemo.kt

scripts/run-agent-demo.sh

目前

TTL Agent

JDK

1. java.util.concurrent.ThreadPoolExecutor

   和

   java.util.concurrent.ScheduledThreadPoolExecutor

   • 修饰实现代码在

     JdkExecutorTtlTransformlet.java

     。

2. java.util.concurrent.ForkJoinTask

   （对应的执行器组件是

   java.util.concurrent.ForkJoinPool

   ）
   • 修饰实现代码在

     ForkJoinTtlTransformlet.java

     。从版本

     2.5.1

     开始支持。
   • 注意：

     Java 8

     引入的

     CompletableFuture

     与（并行执行的）

     Stream

     底层是通过

     ForkJoinPool

     来执行，所以支持

     ForkJoinPool

     后，

     TTL

     也就透明支持了

     CompletableFuture

     与

     Stream

     。🎉

3. java.util.TimerTask

   的子类（对应的执行器组件是

   java.util.Timer

   ）
   • 修饰实现代码在

     TimerTaskTtlTransformlet.java

     。从版本

     2.7.0

     开始支持。
   • 注意：从

     2.11.2

     版本开始缺省开启

     TimerTask

     的修饰（因为保证正确性是第一位，而不是最佳实践『不推荐使用

     TimerTask

     』:）；

     2.11.1

     版本及其之前的版本没有缺省开启

     TimerTask

     的修饰。
   • 使用

     Agent

     参数

     ttl.agent.enable.timer.task

     开启/关闭

     TimerTask

     的修饰：

     • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true

     • -javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false

   • 更多关于

     TTL Agent

     参数的配置说明详见

     TtlAgent.java

     的JavaDoc。

关于

java.util.TimerTask

/

java.util.Timer

Timer

是

JDK 1.3

的老类，不推荐使用

Timer

类。

推荐用

ScheduledExecutorService

。

ScheduledThreadPoolExecutor

实现更强壮，并且功能更丰富。 如支持配置线程池的大小（

Timer

只有一个线程）；

Timer

在

Runnable

中抛出异常会中止定时执行。更多说明参见10. Mandatory Run multiple TimeTask by using ScheduledExecutorService rather than Timer because Timer will kill all running threads in case of failing to catch exceptions. - Alibaba Java Coding Guidelines。

Java Agent

的启动参数配置

在

Java

-javaagent:path/to/transmittable-thread-local-2.x.y.jar

注意：

• 如果修改了下载的

  TTL

  的

  Jar

  的文件名（

  transmittable-thread-local-2.x.y.jar

  ），则需要自己手动通过

  -Xbootclasspath JVM

  参数来显式配置。
  比如修改文件名成

  ttl-foo-name-changed.jar

  ，则还需要加上

  Java

  的启动参数：

  -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar

  。
• 或使用

  v2.6.0

  之前的版本（如

  v2.5.1

  ），则也需要自己手动通过

  -Xbootclasspath JVM

  参数来显式配置（就像

  TTL

  之前的版本的做法一样）。
  加上

  Java

  的启动参数：

  -Xbootclasspath/a:path/to/transmittable-thread-local-2.5.1.jar

  。

Java

java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \
    -cp classes \
    com.alibaba.demo.ttl.agent.AgentDemo

如果修改了TTL jar文件名 或 TTL版本是 2.6.0 之前
则还需要显式设置 -Xbootclasspath 参数
java -javaagent:path/to/ttl-foo-name-changed.jar 
    -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar 
    -cp classes 
    com.alibaba.demo.ttl.agent.AgentDemo
java -javaagent:path/to/transmittable-thread-local-2.5.1.jar 
    -Xbootclasspath/a:path/to/transmittable-thread-local-2.5.1.jar 
    -cp classes 
    com.alibaba.demo.ttl.agent.AgentDemo

关于

boot class path

因为修饰了

JDK

bootstrap class loader

JDK

TTL

Java Agent

TTL Jar

boot class path

TTL

v2.6.0

TTL Agent

TTL Jar

boot class path

Maven

TTL Jar

transmittable-thread-local-2.x.y.jar

-Xbootclasspath JVM

TTL

自动设置

TTL Jar

boot class path

TTL Java Agent Jar

manifest

META-INF/MANIFEST.MF

Boot-Class-Path

Boot-Class-Path

A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed.

更多详见

• Java Agent

  规范 -

  JavaDoc

• JAR File Specification - JAR Manifest
• Working with Manifest Files - The Java™ Tutorials

🔌 Java API Docs

当前版本的Java API文档地址： https://alibaba.github.io/transmittable-thread-local/apidocs/

🍪 Maven依赖

示例：

    com.alibaba
    transmittable-thread-local
    2.12.1

可以在 search.maven.org 查看可用的版本。

🔨 关于编译构建与

IDE

开发

编译构建的环境要求：

JDK 8~11

Maven

Maven

mvnw

Maven

# 运行测试Case
./mvnw test
# 编译打包
./mvnw package
# 运行测试Case、编译打包、安装TTL库到Maven本地
./mvnw install

#####################################################
如果使用你自己安装的 maven，版本要求：maven 3.3.9+
mvn install

如何用

IDE

IDE

❓ FAQ

Q1.

TTL Agent

Agent

Skywalking

Promethues

配置

TTL Agent

Agent

TTL Agent

java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \
     -javaagent:path/to/skywalking-agent.jar \
     -jar your-app.jar

原因是：

• 像

  Skywalking

  这样的

  Agent

  的入口逻辑（

  premain

  ）包含了线程池的启动。
• 如果配置在这样的

  Agent

  配置在前面，到了

  TTL Agent

  （的

  premain

  ）时，

  TTL

  需要加强的线程池类已经加载（

  load

  ）了。

• TTL Agent

  的

  TtlTransformer

  是在类加载时触发类的增强；如果类已经加载了会跳过

  TTL Agent

  的增强逻辑。

更多讨论参见 Issue：

TTL agent

Agent

Q2.

MacOS

Java Agent

JavaLaunchHelper

JDK Bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8021205
可以换一个版本的

JDK

1.7.0_40

1.6.0_51

1.7.0_45

1.7.0_45

JavaLaunchHelper

✨ 使用

TTL

的好处与必要性

注：不读这一节，并不会影响你使用

TTL

来解决你碰到的问题，可以放心跳过；读了 User Guide 就可以快速用起来了～ 😄 这一节信息密度较高不易读。

好处：透明且自动完成所有异步执行上下文的可定制、规范化的捕捉与传递。
这个好处也是

TransmittableThreadLocal

必要性：随着应用的分布式微服务化并使用各种中间件，越来越多的功能与组件会涉及不同的上下文，逻辑流程也越来越长；上下文问题实际上是个大的易错的架构问题，需要统一的对业务透明的解决方案。

使用

ThreadLocal

ThreadLocal

set/remove

1. 从业务使用者角度来看

1. 繁琐
   • 业务逻辑要知道：有哪些上下文；各个上下文是如何获取的。
   • 并需要业务逻辑去一个一个地捕捉与传递。
2. 依赖
   • 需要直接依赖不同

     ThreadLocal

     上下文各自的获取的逻辑或类。
   • 像

     RPC

     的上下文（如

     Dubbo

     的

     RpcContext

     ）、全链路跟踪的上下文（如

     SkyWalking

     的

     ContextManager

     ）、不同业务模块中的业务流程上下文，等等。
3. 静态（易漏）
   • 因为要 事先 知道有哪些上下文，如果系统出现了一个新的上下文，业务逻辑就要修改添加上新上下文传递的几行代码。也就是说因 系统的 上下文新增，业务的 逻辑就跟进要修改。
   • 而对于业务来说，不关心系统的上下文，即往往就可能遗漏，会是线上故障了。
   • 随着应用的分布式微服务化并使用各种中间件，越来越多的功能与组件会涉及不同的上下文，逻辑流程也越来越长；上下文问题实际上是个大的易错的架构问题，需要统一的对业务透明的解决方案。
4. 定制性
   • 因为需要业务逻辑来完成捕捉与传递，业务要关注『上下文的传递方式』：直接传引用？还是拷贝传值？拷贝是深拷贝还是浅拷贝？在不同的上下文会需要不同的做法。
   • 『上下文的传递方式』往往是 上下文的提供者（或说是业务逻辑的框架部分）才能决策处理好的；而 上下文的使用者（或说是业务逻辑的应用部分）往往不（期望）知道上下文的传递方式。这也可以理解成是 依赖，即业务逻辑 依赖/关注/实现了 系统/架构的『上下文的传递方式』。

2. 从整体流程实现角度来看

关注的是 上下文传递流程的规范化。上下文传递到了子线程要做好 清理（或更准确地说是要 恢复 成之前的上下文），需要业务逻辑去处理好。如果业务逻辑对清理的处理不正确，比如：

• 如果清理操作漏了：
  • 下一次执行可能是上次的，即『上下文的 污染/串号』，会导致业务逻辑错误。
  • 『上下文的 泄漏』，会导致内存泄漏问题。
• 如果清理操作做多了，会出现上下文 丢失。

上面的问题，在业务开发中引发的

Bug

ThreadLocal

set/remove

• 当线程池满了且线程池的

  RejectedExecutionHandler

  使用的是

  CallerRunsPolicy

  时，提交到线程池的任务会在提交线程中直接执行，

  ThreadLocal.remove

  操作清理提交线程的上下文导致上下文丢失。
• 类似的，使用

  ForkJoinPool

  （包含并行执行

  Stream

  与

  CompletableFuture

  ，底层使用

  ForkJoinPool

  ）的场景，展开的

  ForkJoinTask

  会在任务提交线程中直接执行。同样导致上下文丢失。

怎么设计一个『上下文传递流程』方案（即上下文的生命周期），以保证没有上面的问题？

期望：上下文生命周期的操作从业务逻辑中分离出来。业务逻辑不涉及生命周期，就不会有业务代码如疏忽清理而引发的问题了。整个上下文的传递流程或说生命周期可以规范化成：捕捉、回放和恢复这3个操作，即

CRR(capture/replay/restore)

replay

restore

总结上面的说明：在生产应用（几乎一定会使用线程池等异步执行组件）中，使用

ThreadLocal

set/remove

Bug

更多

TTL

🗿 更多文档

• 🎨 需求场景说明
• ❤️ 小伙伴同学们写的

  TTL

  使用场景 与 设计实现解析的文章（写得都很好！） - Issue #123
• 🎓 Developer Guide
• ☔ 性能测试

📚 相关资料

JDK Core Classes

• WeakHashMap
• InheritableThreadLocal

👷 Contributors

• Jerry Lee <oldratlee at gmail dot com> @oldratlee
• Yang Fang <snoop.fy at gmail dot com> @driventokill
• Zava Xu <zava.kid at gmail dot com> @zavakid
• wuwen <wuwen.55 at aliyun dot com> @wuwen5
• Xiaowei Shi <179969622 at qq dot com> @xwshiustc
• David Dai <351450944 at qq dot com> @LNAmp
• Your name here :-)