📖 English Documentation | 📖 中文文档
- 🔧 功能
- 🎨 需求场景
- 👥 User Guide
- 🔌 Java API Docs
- 🍪 Maven依赖
- 🔨 关于编译构建与
IDE
开发 - ❓ FAQ
- 🗿 更多文档与资料
- 📚 相关资料
- 👷 Contributors
👉 在使用线程池等会池化复用线程的执行组件情况下,提供ThreadLocal
值的传递功能,解决异步执行时上下文传递的问题。
一个Java
标准库本应为框架/中间件设施开发提供的标配能力,本库功能聚焦 & 0依赖,支持Java
17/16/15/14/13/12/11/10/9/8/7/6。
JDK
的InheritableThreadLocal
类可以完成父线程到子线程的值传递。但对于使用线程池等会池化复用线程的执行组件的情况,线程由线程池创建好,并且线程是池化起来反复使用的;这时父子线程关系的ThreadLocal
值传递已经没有意义,应用需要的实际上是把 任务提交给线程池时的ThreadLocal
值传递到 任务执行时。
本库提供的TransmittableThreadLocal
类继承并加强InheritableThreadLocal
类,解决上述的问题,使用详见User Guide。
整个TransmittableThreadLocal
库的核心功能(用户API
与框架/中间件的集成API
、线程池ExecutorService
/ForkJoinPool
/TimerTask
及其线程工厂的Wrapper
),只有 ~1000 SLOC
代码行,非常精小。
欢迎 👏
- 建议和提问,提交 Issue
- 贡献和改进,Fork 后提通过 Pull Request 贡献代码
ThreadLocal
的需求场景即TransmittableThreadLocal
的潜在需求场景,如果你的业务需要『在使用线程池等会池化复用线程的执行组件情况下传递ThreadLocal
值』则是TransmittableThreadLocal
目标场景。
下面是几个典型场景例子。
- 分布式跟踪系统 或 全链路压测(即链路打标)
- 日志收集记录系统上下文
Session
级Cache
- 应用容器或上层框架跨应用代码给下层
SDK
传递信息
各个场景的展开说明参见子文档 需求场景。
使用TransmittableThreadLocal
的好处与必要性:
- 好处和目标:透明/自动完成所有异步执行上下文的可定制、规范化的捕捉/传递。
- 必要性:上下文问题实际上是个大的易错的架构问题,需要统一的解决方案。
更多展开讨论参见 Issue:这个库带来怎样的好处和优势? #128。
使用类TransmittableThreadLocal
来保存值,并跨线程池传递。
TransmittableThreadLocal
继承InheritableThreadLocal
,使用方式也类似。相比InheritableThreadLocal
,添加了
copy
方法
用于定制 任务提交给线程池时 的ThreadLocal
值传递到 任务执行时 的拷贝行为,缺省传递的是引用。
注意:如果跨线程传递了对象引用因为不再有线程封闭,与InheritableThreadLocal.childValue
一样,使用者/业务逻辑要注意传递对象的线程安全。protected
的beforeExecute
/afterExecute
方法
执行任务(Runnable
/Callable
)的前/后的生命周期回调,缺省是空操作。
具体使用方式见下面的说明。
父线程给子线程传递值。
示例代码:
TransmittableThreadLocal<String> context = new TransmittableThreadLocal<>();
// =====================================================
// 在父线程中设置
context.set("value-set-in-parent");
// =====================================================
// 在子线程中可以读取,值是"value-set-in-parent"
String value = context.get();
# 完整可运行的Demo代码参见SimpleDemo.kt
。
这是其实是InheritableThreadLocal
的功能,应该使用InheritableThreadLocal
来完成。
但对于使用线程池等会池化复用线程的执行组件的情况,线程由线程池创建好,并且线程是池化起来反复使用的;这时父子线程关系的ThreadLocal
值传递已经没有意义,应用需要的实际上是把 任务提交给线程池时的ThreadLocal
值传递到 任务执行时。
解决方法参见下面的这几种用法。
使用TtlRunnable
和TtlCallable
来修饰传入线程池的Runnable
和Callable
。
示例代码:
TransmittableThreadLocal<String> 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<String> 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
。
省去每次Runnable
和Callable
传入线程池时的修饰,这个逻辑可以在线程池中完成。
通过工具类com.alibaba.ttl.threadpool.TtlExecutors
完成,有下面的方法:
getTtlExecutor
:修饰接口Executor
getTtlExecutorService
:修饰接口ExecutorService
getTtlScheduledExecutorService
:修饰接口ScheduledExecutorService
示例代码:
ExecutorService executorService = ...
// 额外的处理,生成修饰了的对象executorService
executorService = TtlExecutors.getTtlExecutorService(executorService);
TransmittableThreadLocal<String> 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
。
这种方式,实现线程池的传递是透明的,业务代码中没有修饰Runnable
或是线程池的代码。即可以做到应用代码 无侵入。
# 关于 无侵入 的更多说明参见文档Java Agent
方式对应用代码无侵入。
示例代码:
// ## 1. 框架上层逻辑,后续流程框架调用业务 ##
TransmittableThreadLocal<String> 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
即可运行Demo。
目前TTL Agent
中,修饰了的JDK
执行器组件(即如线程池)如下:
java.util.concurrent.ThreadPoolExecutor
和java.util.concurrent.ScheduledThreadPoolExecutor
- 修饰实现代码在
TtlExecutorTransformlet.java
。
- 修饰实现代码在
java.util.concurrent.ForkJoinTask
(对应的执行器组件是java.util.concurrent.ForkJoinPool
)- 修饰实现代码在
TtlForkJoinTransformlet.java
。从版本2.5.1
开始支持。 - 注意:
Java 8
引入的CompletableFuture
与(并行执行的)Stream
底层是通过ForkJoinPool
来执行,所以支持ForkJoinPool
后,TTL
也就透明支持了CompletableFuture
与Stream
。🎉
- 修饰实现代码在
java.util.TimerTask
的子类(对应的执行器组件是java.util.Timer
)- 修饰实现代码在
TtlTimerTaskTransformlet.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
的启动参数加上:-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
因为修饰了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文档地址: https://alibaba.github.io/transmittable-thread-local/apidocs/
示例:
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>transmittable-thread-local</artifactId>
<version>2.12.0</version>
</dependency>
可以在 search.maven.org 查看可用的版本。
编译构建的环境要求: 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
开发 - Developer Guide。
1. 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
的兼容性问题 #226。
2. 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
的出错信息,但不影响运行。
- 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 :-)