TransmittableThreadLocal在使用线程池等会缓存线程的组件状况下传递ThreadLocal

一、简介

TransmittableThreadLocal 是Alibaba开源的、用于解决 “在使用线程池等会缓存线程的组件状况下传递ThreadLocal” 问题的 InheritableThreadLocal 扩展。若但愿 TransmittableThreadLocal 在线程池与主线程间传递，需配合 TtlRunnable 和 TtlCallable 使用。

二、使用场景

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

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

三、简单分析使用

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

下面分析下InheritableThreadLocInheritableThreadLocal类重写了ThreadLocal的3个函数：

/**
  * 该函数在父线程建立子线程，向子线程复制InheritableThreadLocal变量时使用
*/
protected T childValue(T parentValue) {
    return parentValue;
}

/**
  * 因为重写了getMap，操做InheritableThreadLocal时，
  * 将只影响Thread类中的inheritableThreadLocals变量，
  * 与threadLocals变量再也不有关系
*/
ThreadLocalMap getMap(Thread t) {
     return t.inheritableThreadLocals;
}

/**
 * 相似于getMap，操做InheritableThreadLocal时，
 * 将只影响Thread类中的inheritableThreadLocals变量，
 * 与threadLocals变量再也不有关系
 */
void createMap(Thread t, T firstValue) {
    t.inheritableThreadLocals = new ThreadLocalMap(this, firstValue);
}

注意：重写了getMap()和createMap()两个函数，说到InheritableThreadLocal，还要从Thread类提及：

public class Thread implements Runnable {
   ......(其余源码)
    /* 
     * 当前线程的ThreadLocalMap，主要存储该线程自身的ThreadLocal
     */
    ThreadLocal.ThreadLocalMap threadLocals = null;

    /*
     * InheritableThreadLocal，自父线程集成而来的ThreadLocalMap，
     * 主要用于父子线程间ThreadLocal变量的传递
     * 本文主要讨论的就是这个ThreadLocalMap
     */
    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;
    ......(其余源码)
}

Thread类中包含 threadLocals 和 inheritableThreadLocals 两个变量，其中 inheritableThreadLocals 即主要存储可自动向子线程中传递的ThreadLocal.ThreadLocalMap。
接下来看一下父线程建立子线程的流程，咱们从最简单的方式提及：

用户建立Thread

hread thread = new Thread();

**
 * Allocates a new {@code Thread} object. This constructor has the same
 * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
 * {@code (null, null, gname)}, where {@code gname} is a newly generated
 * name. Automatically generated names are of the form
 * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.
 */
public Thread() {
    init(null, null, "Thread-" + nextThreadNum(), 0);
}

Thread初始化

/**
 * 默认状况下，设置inheritThreadLocals可传递
 */
private void init(ThreadGroup g, Runnable target, String name,
                  long stackSize) {
    init(g, target, name, stackSize, null, true);
}

/**
 * 初始化一个线程.
 * 此函数有两处调用，
 * 一、上面的 init()，不传AccessControlContext，inheritThreadLocals=true
 * 二、传递AccessControlContext，inheritThreadLocals=false
 */
private void init(ThreadGroup g, Runnable target, String name,
                  long stackSize, AccessControlContext acc,
                  boolean inheritThreadLocals) {
    ......（其余代码）

    if (inheritThreadLocals && parent.inheritableThreadLocals != null)
        this.inheritableThreadLocals =
            ThreadLocal.createInheritedMap(parent.inheritableThreadLocals);

    ......（其余代码）
}

能够看到，采用默认方式产生子线程时，inheritThreadLocals=true；若此时父线程inheritableThreadLocals不为空，则将父线程inheritableThreadLocals传递至子线程。

让咱们继续追踪createInheritedMap

static ThreadLocalMap createInheritedMap(ThreadLocalMap parentMap) {
    return new ThreadLocalMap(parentMap);
}


/**
 * 构建一个包含全部parentMap中Inheritable ThreadLocals的ThreadLocalMap
 * 该函数只被 createInheritedMap() 调用.
 */
private ThreadLocalMap(ThreadLocalMap parentMap) {
    Entry[] parentTable = parentMap.table;
    int len = parentTable.length;
    setThreshold(len);
    // ThreadLocalMap 使用 Entry[] table 存储ThreadLocal
    table = new Entry[len];

    // 逐一复制 parentMap 的记录
    for (int j = 0; j < len; j++) {
        Entry e = parentTable[j];
        if (e != null) {
            @SuppressWarnings("unchecked")
            ThreadLocal<Object> key = (ThreadLocal<Object>) e.get();
            if (key != null) {
                // 可能会有同窗好奇此处为什么使用childValue，而不是直接赋值，
                // 毕竟childValue内部也是直接将e.value返回；
                // 我的理解，主要为了减轻阅读代码的难度
                Object value = key.childValue(e.value);
                Entry c = new Entry(key, value);
                int h = key.threadLocalHashCode & (len - 1);
                while (table[h] != null)
                    h = nextIndex(h, len);
                table[h] = c;
                size++;
            }
        }
    }
}

从ThreadLocalMap可知，子线程将parentMap中的全部记录逐一复制至自身线程。InheritableThreadLocal主要用于子线程建立时，须要自动继承父线程的ThreadLocal变量，方便必要信息的进一步传递。

接下来提供的TransmittableThreadLocal类继承并增强InheritableThreadLocal类，解决上述的问题。

使用类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.kt。执行工程下的脚本scripts/run-agent-demo.sh便可运行Demo。

目前TTL Agent中，修饰了JDK中的线程池实现以下：

1. java.util.concurrent.ThreadPoolExecutor 和 java.util.concurrent.ScheduledThreadPoolExecutor
   修饰实现代码在TtlExecutorTransformlet.java
2. java.util.concurrent.ForkJoinTask（对应的线程池组件是java.util.concurrent.ForkJoinPool）
   修饰实现代码在TtlForkJoinTransformlet.java
3. java.util.TimerTask的子类（对应的线程池组件是java.util.Timer）
   修饰实现代码在TtlTimerTaskTransformlet.java
   注意：缺省没有开启TimerTask的修饰，使用Agent参数ttl.agent.enable.timer.task开启：-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true。
   更多关于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。

关于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的启动参数配置

在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

Maven依赖

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