<div align="center"><a href="#dummy"><img src="https://user-images.githubusercontent.com/1063891/233595946-4493119e-4e0c-4081-a382-0a20731c578e.png" alt="📌 TransmittableThreadLocal(TTL)"></a></div>

[!IMPORTANT] 🚧 这个分支是TransmittableThreadLocal(TTL) v3，在开发中还没有发布。
v3的版本说明、工作项列表及其进展，参见 issue 432。

👉 目前使用中的稳定发布版本v2.x在 分支2.x上。

📖 English Documentation | 📖 中文文档

🔧 功能
🎨 需求场景
👥 User Guide
- 1. 简单使用
- 2. 保证线程池中传递值
🔌 Java API Docs
🍪 Maven依赖
🔨 关于编译构建
❓ FAQ
✨ 使用TTL的好处与必要性
🗿 更多文档
📚 相关资料
- JDK Core Classes
💗 Who Used
👷 Contributors

🔧 功能

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

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

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

整个TransmittableThreadLocal库的核心功能（用户API、线程池ExecutorService/ForkJoinPool/TimerTask及其线程工厂的Wrapper；开发者API、框架/中间件的集成API），只有 ~1000 SLOC代码行，非常精小。

欢迎 👏

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

[!NOTE] 从TTL v2.13+开始，升级到Java 8。🚀
如果需要Java 6的支持，使用版本2.12.x <a href="https://repo1.maven.org/maven2/com/alibaba/transmittable-thread-local/maven-metadata.xml"><img src="https://img.shields.io/maven-central/v/com.alibaba/transmittable-thread-local?versionPrefix=2.12.&color=lightgrey&logo=apache-maven&logoColor=white" alt="Maven Central"></a>

🎨 需求场景

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

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

分布式跟踪系统或全链路压测（即链路打标）
日志收集记录系统上下文
Session级Cache
应用容器或上层框架跨应用代码给下层SDK传递信息

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

👥 User Guide

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

TransmittableThreadLocal继承InheritableThreadLocal，使用方式也类似。相比InheritableThreadLocal，添加了protected的transmitteeValue()方法，用于定制 任务提交给线程池时 的ThreadLocal值传递到 任务执行时 的传递方式，缺省是简单的赋值传递。

注意：如果传递的对象（引用类型）会被修改，且没有做深拷贝（如直接传递引用或是浅拷贝），那么

因为跨线程传递而不再有线程封闭，传递对象在多个线程之间是有共享的。
与JDK的InheritableThreadLocal.childValue()一样，需要使用者/业务逻辑注意保证传递对象的线程安全。

<blockquote> <details> <summary>关于<code>transmitteeValue</code>方法的展开说明</summary> <br> <p>关于构词后缀<code>er</code>与<code>ee</code>的说明： <ul> <li><code>transmit</code>是动词传递，<code>transmitter</code>动作的执行者/主动方，而<code>transmittee</code>动作的接收者/被动方。</li> <li><code>er</code>与<code>ee</code>后缀的常见词是<code>employer</code>（雇主）/<code>employee</code>（雇员）、<code>caller</code>（调用者）/<code>callee</code>（被调用者）。</li> </ul> </details> </blockquote>

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

1. 简单使用

父线程给子线程传递值。

示例代码：

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值传递到 任务执行时。

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

2. 保证线程池中传递值

2.1 修饰`Runnable`和`Callable`

使用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();