📌 Transmittable ThreadLocal(TTL) 📌

📖 English Documentation | 📖 中文文档

---

• 🔧 功能
• 🎨 需求场景
• 👥 User Guide
  • 1. 简单使用
  • 2. 保证线程池中传递值
    • 2.1 修饰Runnable和Callable
      • 整个过程的完整时序图
    • 2.2 修饰线程池
    • 2.3 使用Java Agent来修饰JDK线程池实现类
      • 关于boot class path设置
      • Java的启动参数配置
      • Java Agent的使用方式在什么情况下TTL会失效
• 🔌 Java API Docs
• 🍪 Maven依赖
• ❓ FAQ
• 🗿 更多文档
• 📚 相关资料
  • Jdk core classes
  • Java Agent
• 👷 Contributors

---

🔧 功能

👉 在使用线程池等会池化复用线程的组件情况下，提供ThreadLocal值的传递功能，解决异步执行时上下文传递的问题。 一个Java标准库本应为框架/中间件设施开发提供的标配能力，本库功能聚焦 & 0依赖，支持Java 11/10/9/8/7/6。

JDK的InheritableThreadLocal类可以完成父线程到子线程的值传递。但对于使用线程池等会池化复用线程的组件的情况，线程由线程池创建好，并且线程是池化起来反复使用的；这时父子线程关系的ThreadLocal值传递已经没有意义，应用需要的实际上是把 任务提交给线程池时的ThreadLocal值传递到 任务执行时。

本库提供的TransmittableThreadLocal类继承并加强InheritableThreadLocal类，解决上述的问题，使用详见User Guide。

整个库包含TTL核心功能、线程池修饰及Agent支持（ExecutorService/ForkJoinPool），只有不到 800 SLOC代码行，非常精小。

欢迎 👏

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

🎨 需求场景

在ThreadLocal的需求场景即是TTL的潜在需求场景，如果你的业务需要『在使用线程池等会池化复用线程的组件情况下传递ThreadLocal』则是TTL目标场景。

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

1. 分布式跟踪系统
2. 日志收集记录系统上下文
3. 应用容器或上层框架跨应用代码给下层SDK传递信息

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

👥 User Guide

使用类TransmittableThreadLocal来保存值，并跨线程池传递。

TransmittableThreadLocal继承InheritableThreadLocal，使用方式也类似。

相比InheritableThreadLocal，添加了

1. protected方法copy
   用于定制 任务提交给线程池时 的ThreadLocal值传递到 任务执行时 的拷贝行为，缺省传递的是引用。
2. protected方法beforeExecute/afterExecute
   执行任务(Runnable/Callable)的前/后的生命周期回调，缺省是空操作。

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

1. 简单使用

父线程给子线程传递值。

示例代码：

// 在父线程中设置
TransmittableThreadLocal<String> parent = new TransmittableThreadLocal<String>();
parent.set("value-set-in-parent");

// =====================================================

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

这是其实是InheritableThreadLocal的功能，应该使用InheritableThreadLocal来完成。

但对于使用线程池等会池化复用线程的组件的情况，线程由线程池创建好，并且线程是池化起来反复使用的；这时父子线程关系的ThreadLocal值传递已经没有意义，应用需要的实际上是把 任务提交给线程池时的ThreadLocal值传递到 任务执行时。

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

2. 保证线程池中传递值

2.1 修饰Runnable和Callable

使用TtlRunnable和TtlCallable来修饰传入线程池的Runnable和Callable。

示例代码：

TransmittableThreadLocal<String> parent = new TransmittableThreadLocal<String>();
parent.set("value-set-in-parent");

Runnable task = new Task("1");
// 额外的处理，生成修饰了的对象ttlRunnable
Runnable ttlRunnable = TtlRunnable.get(task);
executorService.submit(ttlRunnable);

// =====================================================

// Task中可以读取，值是"value-set-in-parent"
String value = parent.get();

上面演示了Runnable，Callable的处理类似

TransmittableThreadLocal<String> parent = new TransmittableThreadLocal<String>();
parent.set("value-set-in-parent");

Callable call = new Call("1");
// 额外的处理，生成修饰了的对象ttlCallable
Callable ttlCallable = TtlCallable.get(call);
executorService.submit(ttlCallable);

// =====================================================

// Call中可以读取，值是"value-set-in-parent"
String value = parent.get();

整个过程的完整时序图

2.2 修饰线程池

省去每次Runnable和Callable传入线程池时的修饰，这个逻辑可以在线程池中完成。

通过工具类com.alibaba.ttl.threadpool.TtlExecutors完成，有下面的方法：

• getTtlExecutor：修饰接口Executor
• getTtlExecutorService：修饰接口ExecutorService
• getTtlScheduledExecutorService：修饰接口ScheduledExecutorService

示例代码：

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

TransmittableThreadLocal<String> parent = new TransmittableThreadLocal<String>();
parent.set("value-set-in-parent");

Runnable task = new Task("1");
Callable call = new Call("2");
executorService.submit(task);
executorService.submit(call);

// =====================================================

// Task或是Call中可以读取，值是"value-set-in-parent"
String value = parent.get();

2.3 使用Java Agent来修饰JDK线程池实现类

这种方式，实现线程池的传递是透明的，代码中没有修饰Runnable或是线程池的代码。即可以做到应用代码 无侵入。
# 关于 无侵入 的更多说明参见文档Java Agent方式对应用代码无侵入。

示例代码：

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

// ## 2. 应用逻辑，后续流程业务调用框架下层逻辑 ##
ExecutorService executorService = Executors.newFixedThreadPool(3);

Runnable task = new Task("1");
Callable call = new Call("2");
executorService.submit(task);
executorService.submit(call);

// ## 3. 框架下层逻辑 ##
// Task或是Call中可以读取，值是"value-set-in-parent"
String value = context.get();

Demo参见AgentDemo.java。执行工程下的脚本scripts/run-agent-demo.sh即可运行Demo。

目前Agent中，修饰了JDK中的两个线程池实现类（实现代码在TtlTransformer.java）：

• java.util.concurrent.ThreadPoolExecutor
• java.util.concurrent.ScheduledThreadPoolExecutor

关于boot class path设置

因为修饰了JDK的标准库的类，标准库由bootstrap class loader加载；上面修饰后的JDK类引用了TTL的代码，所以TTL的Jar需要加到boot class path上。

TTL从v2.6.0开始，加载TTL Agent会自动把自己的Jar设置到boot class path上。

注意：不能修改从Maven库下载的TTL的Jar的文件名（形如transmittable-thread-local-2.x.x.jar）。 如果修改了，则需要自己手动通过-Xbootclasspath JVM参数来显式配置（就像TTL之前的版本的做法一样）。

实现是通过指定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™ TutorialsHide

Java的启动参数配置

在Java的启动参数加上：-javaagent:path/to/transmittable-thread-local-2.x.x.jar。

如果修改了下载的TTL的Jar的文件名（transmittable-thread-local-2.x.x.jar），则需要自己手动通过-Xbootclasspath JVM参数来显式配置：
比如修改文件名成ttl-foo-name-changed.jar，则还加上Java的启动参数：-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar

Java命令行示例如下：

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

或是

java -javaagent:path/to/ttl-foo-name-changed.jar \
    -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar \
    -cp classes \
    com.alibaba.ttl.threadpool.agent.demo.AgentDemo

Java Agent的使用方式在什么情况下TTL会失效

由于Runnable和Callable的修饰代码，是在线程池类中插入的。下面的情况会让插入的代码被绕过，传递会失效。

• 用户代码中继承java.util.concurrent.ThreadPoolExecutor和java.util.concurrent.ScheduledThreadPoolExecutor， 覆盖了execute、submit、schedule等提交任务的方法，并且没有调用父类的方法。
  修改线程池类的实现，execute、submit、schedule等提交任务的方法禁止这些被覆盖，可以规避这个问题。
• 目前，没有修饰java.util.Timer类，使用Timer时，TTL会有问题。

🔌 Java API Docs

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

🍪 Maven依赖

示例：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>transmittable-thread-local</artifactId>
    <version>2.6.1</version>
</dependency>

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

❓ FAQ

• Mac OS X下，使用javaagent，可能会报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的出错信息，但不影响运行。

🗿 更多文档

• 🎨 需求场景说明
• 🎓 Developer Guide
• ☔ 性能测试

📚 相关资料

Jdk core classes

• WeakHashMap
• InheritableThreadLocal

Java Agent

• Java SE 6 新特性: Instrumentation 新功能
• Creation, dynamic loading and instrumentation with javaagents
• JavaAgent加载机制分析
• 官方文档
  • Java Agent规范 - JavaDoc
  • JAR File Specification - JAR Manifest
  • Working with Manifest Files - The Java™ TutorialsHide

👷 Contributors

• Jerry Lee <oldratlee at gmail dot com> @oldratlee
• Yang Fang <snoop.fy at gmail dot com> @driventokill
• 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 :-)