ThreadLocal 原理与内存泄漏：弱引用的坑

// 服务运行 3 天后，运维导出 Heap Dump（4.2GB）
// MAT (Memory Analyzer Tool) 分析结果：

Dominator Tree:
  ThreadLocalMap$Entry[]          retained: 3.1 GB
    └── Entry[0..1999999]         retained: 2.8 GB
         └── UserContext × 2000000  ← 200 万个用户上下文对象！
              ├── userId: Long
              ├── tenantId: String
              └── permissions: List<String>

// 根因：Filter 中 set 了 ThreadLocal，但忘了 remove
// 线程池中的线程被复用，Entry 永远不会被清理

/* ─── 场景 1：数据库连接管理（类似 Spring 的实现思路） ─── */
public class DBUtil {
    private static final ThreadLocal<Connection> connHolder = new ThreadLocal<>();

    public static Connection getConnection() {
        Connection conn = connHolder.get();
        if (conn == null) {           // 懒加载：本线程第一次取才建
            conn = dataSource.getConnection();
            connHolder.set(conn);
        }
        return conn;
    }

    public static void close() {
        Connection conn = connHolder.get();
        if (conn != null) { conn.close(); connHolder.remove(); }
    }
}

/* ─── 场景 2：SimpleDateFormat 线程安全 ─── */
private static final ThreadLocal<SimpleDateFormat> sdfHolder =
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

String formatted = sdfHolder.get().format(new Date());

/* ─── 场景 3：请求上下文（Spring Security 的思路） ─── */
public class UserContext {
    private static final ThreadLocal<UserInfo> holder = new ThreadLocal<>();
    public static void set(UserInfo user) { holder.set(user); }
    public static UserInfo get() { return holder.get(); }
    public static void clear() { holder.remove(); }
}

/* ─── 场景 4：MDC TraceId ─── */
MDC.put("traceId", UUID.randomUUID().toString());
// logback 日志格式: %d [%X{traceId}] %-5level %msg%n

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class ThreadLocalDemo {

    // 注意：生产里 ThreadLocal 必须是 static final，原因见第 17 站
    private static final ThreadLocal<Integer> counter = new ThreadLocal<>();

    public static void main(String[] args) throws Exception {
        // ① 主线程设置自己的值
        counter.set(100);

        // ② 子线程读不到主线程的值（默认不继承！）
        Thread t = new Thread(() -> {
            System.out.println("子线程 get() = " + counter.get());      // null
            counter.set(200);                                           // 各存各的
            System.out.println("子线程 set 后 get() = " + counter.get()); // 200
        });
        t.start();
        t.join();

        // ③ 主线程的值没有被污染
        System.out.println("主线程 get() = " + counter.get());          // 100

        // ④ 线程池场景：线程复用，值会"残留"给下一个任务
        ExecutorService pool = Executors.newFixedThreadPool(1);
        pool.submit(() -> {
            counter.set(999);
            System.out.println("任务A get() = " + counter.get());        // 999
            // 注意：没有 remove()！
        });
        pool.submit(() -> System.out.println("任务B get() = " + counter.get())); // 999 ← 脏数据！
        pool.shutdown();
    }
}

子线程 get() = null
子线程 set 后 get() = 200
主线程 get() = 100
任务A get() = 999
任务B get() = 999   ← 任务 B 读到了任务 A 留下的值！

// 每个线程都有一张自己的 map（懒加载：第一次 set 才创建）
ThreadLocal.ThreadLocalMap threadLocals = null;

// 专供 InheritableThreadLocal 用的另一张 map（第 15 站细讲）
ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

public void set(T value) {
    // 1. 获取当前线程
    Thread t = Thread.currentThread();

    // 2. 获取该线程的 ThreadLocalMap（"当前线程取 map"）
    ThreadLocalMap map = getMap(t);  // return t.threadLocals;

    if (map != null) {
        // 3. 以 this（当前 ThreadLocal 实例）为 key 存入 map
        map.set(this, value);
    } else {
        // 4. 首次使用，为线程创建 ThreadLocalMap
        createMap(t, value);
    }
}

// createMap 的真相：map 是挂在当前线程对象上的
void createMap(Thread t, T firstValue) {
    t.threadLocals = new ThreadLocalMap(this, firstValue);
}

public T get() {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);

    if (map != null) {
        ThreadLocalMap.Entry e = map.getEntry(this);
        if (e != null) {
            @SuppressWarnings("unchecked")
            T result = (T) e.value;
            return result;
        }
    }
    // map 为空 或 没找到 Entry → 调用 initialValue() 初始化
    return setInitialValue();
}

private T setInitialValue() {
    T value = initialValue();  // 默认返回 null；withInitial() 可自定义
    Thread t = Thread.currentThread();
    ThreadLocalMap map = getMap(t);
    if (map != null)
        map.set(this, value);
    else
        createMap(t, value);
    return value;
}

// ThreadLocal.remove()
public void remove() {
    ThreadLocalMap m = getMap(Thread.currentThread());
    if (m != null)
        m.remove(this);
}

// ThreadLocalMap.remove()
private void remove(ThreadLocal<?> key) {
    Entry[] tab = table;
    int len = tab.length;
    int i = key.threadLocalHashCode & (len - 1);

    // 线性探测找到 key 对应的 Entry
    for (Entry e = tab[i]; e != null; e = tab[i = nextIndex(i, len)]) {
        if (e.get() == key) {
            e.clear();              // ① 清掉弱引用（Reference.clear()），key 变 null
            expungeStaleEntry(i);   // ② 删除该槽位，并把后续被"挤偏"的 Entry 重新放置
            return;
        }
    }
}

// 每个 ThreadLocal 实例在构造时固定自己的 hash
private final int threadLocalHashCode = nextHashCode();

// 魔数：2^32 × (√5 − 1) / 2 ≈ 2654435769 = 0x61C88647
private static final int HASH_INCREMENT = 0x61c88647;

// 全局递增计数器：每 new 一个 ThreadLocal，就加上一次魔数
private static AtomicInteger nextHashCode = new AtomicInteger();

private static int nextHashCode() {
    return nextHashCode.getAndAdd(HASH_INCREMENT);
}

// 强引用：只要引用存在，GC 绝不回收
Object obj = new Object();   // obj 是强引用

// 软引用：内存不足时才回收（适合做缓存）
SoftReference<Object> soft = new SoftReference<>(obj);

// 弱引用：下次 GC 必定回收（不管内存够不够）
WeakReference<Object> weak = new WeakReference<>(obj);

// 虚引用：随时可回收，无法通过它获取对象（仅用于跟踪回收）
PhantomReference<Object> phantom = new PhantomReference<>(obj, queue);

// getEntry 时如果没直接命中，会走 getEntryAfterMiss：
// 线性探测过程中遇到 key=null 的脏 Entry，调用 expungeStaleEntry 清理
private Entry getEntry(ThreadLocal<?> key) {
    int i = key.threadLocalHashCode & (table.length - 1);
    Entry e = table[i];
    if (e != null && e.get() == key) {
        return e;                      // 直接命中，最快的路径
    } else {
        return getEntryAfterMiss(key, i, e);  // 探测 + 顺路清理
    }
}

// expungeStaleEntry：清理脏 Entry + 重排后续元素（核心逻辑）
private int expungeStaleEntry(int staleSlot) {
    Entry[] tab = table;
    int len = tab.length;

    // 1. 解除 value 的强引用 —— value 终于可以被 GC 了
    tab[staleSlot].value = null;
    tab[staleSlot] = null;        // 清掉整个槽位
    size--;

    // 2. 继续向后扫描：重放被挤偏的 Entry，顺手再清脏
    Entry e;
    int i;
    for (i = nextIndex(staleSlot, len); (e = tab[i]) != null; i = nextIndex(i, len)) {
        ThreadLocal<?> k = e.get();
        if (k == null) {          // 又一个脏 Entry，一并清掉
            e.value = null;
            tab[i] = null;
            size--;
        } else {
            // 重新 hash，把这个 Entry 挪到更靠前的位置（保持探测链完整）
            int h = k.threadLocalHashCode & (len - 1);
            if (h != i) {
                tab[i] = null;
                while (tab[h] != null) h = nextIndex(h, len);
                tab[h] = e;
            }
        }
    }
    return i;
}

// 错误写法：任务结束没清 MDC（MDC 底层就是 ThreadLocal）
public void handle(Request req) {
    MDC.put("traceId", UUID.randomUUID().toString());   // 请求入口放 traceId

    asyncExecutor.submit(() -> {
        // 线程池线程执行 —— 上个任务留下的 traceId 还在！
        log.info("处理请求");   // 日志里带着"别人的" traceId
    });

    // 忘了在 finally 里 MDC.remove() → traceId 残留在当前线程
    // 下一个请求复用这个线程 → 新 traceId 覆盖失败？不，是读到了旧值……
}

// 正确写法：finally 里清理，配套第 14 站的模板
try {
    MDC.put("traceId", UUID.randomUUID().toString());
    // ... 业务逻辑 ...
} finally {
    MDC.remove();   // 或者 MDC.clear()
}

public class UserContextFilter implements Filter {
    // ① 静态字段持有：避免 ThreadLocal 实例被 GC（见第 17 站）
    private static final ThreadLocal<UserContext> USER_HOLDER = new ThreadLocal<>();

    @Override
    public void doFilter(ServletRequest req, ServletResponse resp,
                         FilterChain chain) throws IOException, ServletException {
        try {
            UserContext ctx = parseUser(req);
            USER_HOLDER.set(ctx);       // ② 设置上下文
            chain.doFilter(req, resp);  // ③ 业务处理（Controller → Service → DAO 都能拿到）
        } finally {
            USER_HOLDER.remove();       // ④ 必须在 finally 中清理！
            // 不能放在 try 里（异常会跳过）；不能漏；线程池场景更不能省
        }
    }
}

ThreadLocal<String> tl = new InheritableThreadLocal<>();
tl.set("main-thread-value");

new Thread(() -> {
    // 子线程可以读到父线程的值！
    System.out.println(tl.get());  // 输出: main-thread-value
}).start();

// 原理：Thread.init() 时，如果父线程的 inheritableThreadLocals 不为空，
// 会把整张 map 浅拷贝给子线程（值对象共享引用）

// 创建子线程时（Thread.init()），父线程的 inheritableThreadLocals 被拷贝
if (inheritThreadLocals && parent.inheritableThreadLocals != null) {
    this.inheritableThreadLocals =
        ThreadLocal.createInheritedMap(parent.inheritableThreadLocals);
}

// 拷贝是"浅拷贝"：每个 Entry 的 value 走 childValue() 转换，默认原样返回
// 注意：value 对象本身是共享的 —— 子线程改了对象内部状态，父线程也看得到

// Maven: com.alibaba:transmittable-thread-local:2.14.x

// 1. 使用 TTL 替代 ThreadLocal
TransmittableThreadLocal<UserContext> ctx = new TransmittableThreadLocal<>();

// 2. 包装线程池（关键步骤！）
ExecutorService pool = TtlExecutors.getTtlExecutorService(
    Executors.newFixedThreadPool(10)
);

// 3. 提交任务时，TTL 自动完成 capture → replay → restore
ctx.set(new UserContext("user-123"));

pool.submit(() -> {
    // 线程池线程能正确读到提交时的值，任务结束自动还原，不会串号
    UserContext user = ctx.get();  // user-123
    processRequest(user);
});

/* ─── 配合 Spring + 线程池的完整配置 ─── */
@Configuration
public class AsyncConfig {

    @Bean("taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("async-ttl-");
        // 用 TTL 装饰任务，确保 @Async 方法能正确传递上下文
        executor.setTaskDecorator(new TtlTaskDecorator());
        executor.initialize();
        return executor;
    }
}

/* ─── 自定义 TaskDecorator（Spring 集成） ─── */
public class TtlTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        // TtlRunnable 会自动 capture/replay/restore
        return TtlRunnable.get(runnable);
    }
}

/* ─── 使用方式 ─── */
@Service
public class OrderService {
    @Async("taskExecutor")
    public CompletableFuture<Void> processAsync() {
        // 即使在不同线程执行，也能拿到正确的用户上下文
        UserContext user = UserContextHolder.get();
        log.info("processing order for user: {}", user.getUserId());
        return CompletableFuture.completedFuture(null);
    }
}