多线程 on FelixHao's Blog

为什么 ThreadLocal 可能会导致内存泄漏？

Sat, 05 Jul 2025 11:00:28 +0800

ThreadLocal 让我们非常方便的管理和使用各线程独独有的局部变量，但是如果使用不当，会导致内存泄漏。这篇文章将详细的介绍为什么 ThreadLocal 会发生内存泄漏，以及如何避免内存泄漏的发生。

内存泄漏

内存泄漏：占有内存空间，但是存储的数据无法被程序使用和释放，随着时间的推移，内存占用量越来越多，最终导致内存溢出。

Java的四种引用类型

强引用：在任何时候，都不会被垃圾回收器回收，我们正常的 = 赋值就是强引用
软引用：当内存不足的时候，会被垃圾回收器回收
弱引用：任何时候，只要发生了 GC，内存都会被回收
虚引用：最弱的引用类型，软引用和弱饮用好歹还可以使用 get 方法获取到对应的对象，虚引用什么也获取不到。主要的作用就是跟踪对象被垃圾回收器回收的活动。

详细解释

相关源码

public class Thread implements Runnable {

    // ......

    /* ThreadLocal values pertaining to this thread. This map is maintained
     * by the ThreadLocal class. */
  	// 默认的访问权限：只有处于同一个包中的类可以访问 threadLocals 属性
    ThreadLocal.ThreadLocalMap threadLocals = null;

    /*
     * InheritableThreadLocal values pertaining to this thread. This map is
     * maintained by the InheritableThreadLocal class.
     */
    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

    // ......
}

static class ThreadLocalMap {

      static class Entry extends WeakReference<ThreadLocal<?>> {
          /** The value associated with this ThreadLocal. */
          Object value;

          Entry(ThreadLocal<?> k, Object v) {
              super(k);
              value = v;
          }
      }
  
      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);
      }
  
      private void set(ThreadLocal<?> key, Object value) {

          // We don't use a fast path as with get() because it is at
          // least as common to use set() to create new entries as
          // it is to replace existing ones, in which case, a fast
          // path would fail more often than not.

          Entry[] tab = table;
          int len = tab.length;
          int i = key.threadLocalHashCode & (len-1);

          for (Entry e = tab[i];
               e != null;
               e = tab[i = nextIndex(i, len)]) {
              ThreadLocal<?> k = e.get();

              if (k == key) {
                  e.value = value;
                  return;
              }

              if (k == null) {
                  replaceStaleEntry(key, value, i);
                  return;
              }
          }

          tab[i] = new Entry(key, value);
          int sz = ++size;
          if (!cleanSomeSlots(i, sz) && sz >= threshold)
              rehash();
      }
}

ThreadLocal 本身并不存储数据，只负责管理线程的局部变量。

ThreadLocal.ThreadLocalMap threadLocals = null;

Thread 类中 threadLocals 属性的访问权限是 default. 也就是说只有与 Thread 类处于同一个包中的类才可以访问 threadLocals 属性。并且 Thread 类本身也没有提供任何方法来操作 threadLocals 属性。要操作 threadLocals，只能够通过 ThreadLocal 类。

threadLocals 的类型是 ThreadLocalMap. 它通过 Entry[] 数组来存储键值对。但是 Entry 类的定义比较有意思：

class Entry extends WeakReference<ThreadLocal<?>> {
    /** The value associated with this ThreadLocal. */
    Object value;

    Entry(ThreadLocal<?> k, Object v) {
        super(k);
        value = v;
    }
}

Entry 继承了 WeakReference, 并根据构造函数可以知道：Entry 中的 key 属性是一个弱引用。当我们通过 ThreadLocal 操作 threadLocalMap 是，内存示意图如下：

根据强引用和弱引用的定义，如果 userThreadLocal 等变量不再指向 ThreadLocal, 那么 ThreadLocal 就只有 Entry 中的弱引用 key 指向 ThreadLocal 对象：

如果发生 GC，ThreadLocal 对象就会垃圾回收器回收占用的内存：

ThreadLocal 对象被回收后，ThreadLocalMap 不会被回收，因为有强引用在使用该对象，但是根据 threadLocals 的定义：

public class Thread implements Runnable {

    // ......

    /* ThreadLocal values pertaining to this thread. This map is maintained
     * by the ThreadLocal class. */
  	// 默认的访问权限：只有处于同一个包中的类可以访问 threadLocals 属性
    ThreadLocal.ThreadLocalMap threadLocals = null;

    /*
     * InheritableThreadLocal values pertaining to this thread. This map is
     * maintained by the InheritableThreadLocal class.
     */
    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

    // ......
}

只有与 Thread 处于同一个包中的类才可访问 threadLocals 属性，并且源码注释也说明了 threadLocals 属性是交给 ThreadLocal 类来维护的。如果 ThreadLocal 对象不存在了，就没有办法访问 ThradLocalMap 中的元素了。ThreadLocal 虽然被回收了，但是 ThreadLocalMap 却不会被回收，因为有强引用指向它。无法被访问，但是内存又没法被回收，这不就是内存泄漏吗？

知道了为什么会导致内存泄漏，那该如何避免呢？

在 ThreadLocal 内存被回收之前手动调用 remove() 方法
避免频繁的创建和删除 ThreadLocal 对象。
内存池中的线程使用 ThreadLocal 一定要注意以上两点。因为线程池中的线程长时间存活的，而 ThreadLocalMap 的生命周期是与 Thread 绑定在一起的。

为什么要使用弱引用？

如果 Key 使用强引用，开发人员在使用不当的情况下，内存泄漏会更为严重，因为栈中的引用不再指向 ThreadLocal 对象时，Entry 中的 Key 是强引用，堆中的 ThreadLocal 对象永远都无法被回收：

使用弱引用时，如果外部没有强引用指向 ThreadLocal，那么 ThreadLocal 对象会被回收，因此 ThreadLocalMap 可以检查 Entry 中的 key 是否为 null 来判断 Entry 是否过期，从而释放因使用不当造成的内存泄漏。

ThreadLocal 如何尽可能的减少内存泄漏？

调用 set() 方法时，清除过期元素
调用 get() 方法时，清除过期元素
调用 remove() 方法时，清除过期元素

只要在访问 ThreadLocal 的过程过程中，遍历了底层的 Entry 数组，ThreadLocal 都会进行清除过期元素的操作，将清除元素的操作平坦到每一次基础的操作中。

// set 方法的逻辑：
// 1. 通过 key 找到 Entry 在数组中的位置 i
// 2. 从数组第 i 个位置开始遍历，直到找到 key 对应的元素或者找到已过期的元素
// 		2.1 如果找到 key 对应的元素，直接设置值，然后返回
// 		2.2 如果找到过期的元素，将过期的元素删除，并将过期元素所在的位置设置成 set 方法传递过来的 key 和 value
private void set(ThreadLocal<?> key, Object value) {
    Entry[] tab = tableh;
    int i = key.threadLocalHashCode & (len-1);

    for (Entry e = tab[i];
         e != null;
         e = tab[i = nextIndex(i, len)]
        ) {
        ThreadLocal<?> k = e.get();

        if (k == key) {
            e.value = value;
            return;
        }

        // 如果 key 为 null，说明元素已经过期，进行删除
        if (k == null) {
            // 替换过期的元素
            replaceStaleEntry(key, value, i);
            return;
        }
    }

    tab[i] = new Entry(key, value);
    int sz = ++size;
    if (!cleanSomeSlots(i, sz) && sz >= threshold)
        rehash();
}


private void remove(ThreadLocal<?> key) {
    Entry[] tab = table;
    int len = tab.length;
    int i = key.threadLocalHashCode & (len-1);
    for (Entry e = tab[i];
         e != null;
         e = tab[i = nextIndex(i, len)]) {
        if (e.get() == key) {
            e.clear();
          	// 删除元素的同时，清理过期元素
            expungeStaleEntry(i);
            return;
        }
    }
}

// key 对应的元素存在且没有发生 hash 冲突，直接返回对应的值
// key 不存在或者是发生了 hash 冲突，遍历数组并清理过期元素
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);
}

private Entry getEntryAfterMiss(ThreadLocal<?> key, int i, Entry e) {
    Entry[] tab = table;
    int len = tab.length;

    while (e != null) {
        ThreadLocal<?> k = e.get();
        if (k == key)
            return e;
        if (k == null)
            expungeStaleEntry(i);
        else
            i = nextIndex(i, len);
        e = tab[i];
    }
    return null;
}

// staleSlot 表示过期插槽的位置
private void replaceStaleEntry(ThreadLocal<?> key, Object value,
                                       int staleSlot) {
    Entry[] tab = table;
    int len = tab.length;
    Entry e;

    // slotToExpunge 变量用于存储第一个需要被清除的元素
  	int slotToExpunge = staleSlot;
  
  	// 1. 向前遍历，直到找到第一个没有存放 Entry 的 slot
  	// 2. 记录在遍历过程中最后遇到的应该清除的 slot 的位置
    for (int i = prevIndex(staleSlot, len);
         (e = tab[i]) != null;
         i = prevIndex(i, len))
        if (e.get() == null)
            slotToExpunge = i;

  	
    for (int i = nextIndex(staleSlot, len);
         (e = tab[i]) != null;
         i = nextIndex(i, len)) {
      
          ThreadLocal<?> k = e.get();

          // 向后遍历时，如果发现 key 对应的 entry 存在，重新设置 value 的值
          // 并将 key 对应的 entry 迁移到方法参数传递过来的已过期元素的位置上
          if (k == key) {
                e.value = value;

                tab[i] = tab[staleSlot];
                tab[staleSlot] = e;

                // 当前循环的作用是在数组 staleSlot 位置向后查找过期的元素，
                // slotToExpunge 变量的定义是：第一个需要被清除的元素
                // slotToExpunge == staleSlot 表明数组 staleSlot 位置前面没有过期的元素
                // 前面没有需要被清除的元素，第 i 个位置就是第一个需要被清除的元素，因此需要将 i 的值赋值给 slotToExpunge
                if (slotToExpunge == staleSlot)
                    slotToExpunge = i;
                cleanSomeSlots(expungeStaleEntry(slotToExpunge), len);
                return;
           }

      			// k == null 表示第 i 个元素需要被清除
      			// slotToExpunge == staleSlot 表示 staleSlot 前面没有需要被清除的元素，第 i 个位置就是第一个需要被清除的元素
      			// 因此需要将 i 的值赋值给 slotToExpunge
            if (k == null && slotToExpunge == staleSlot)
                slotToExpunge = i;
    }

  	// key 在数组中不存在，则把 key, value 放在 staleSlot 位置上
    tab[staleSlot].value = null;
    tab[staleSlot] = new Entry(key, value);

  	// 如果有过期的元素，则清除过期元素
    if (slotToExpunge != staleSlot)
        cleanSomeSlots(expungeStaleEntry(slotToExpunge), len);
}

// 清除元素，并重新计算未过期元素在数组中的位置
// 返回从 staleSlot 向后遍历遇到的第一个没有存放元素的位置
private int expungeStaleEntry(int staleSlot) {
      Entry[] tab = table;
      int len = tab.length;

      // expunge entry at staleSlot
      tab[staleSlot].value = null;
      tab[staleSlot] = null;
      size--;

      // Rehash until we encounter null
      Entry e;
      int i;
  		// 边遍历边删除元素，同时对元素重新 hash，迁移元素到新的位置上
      for (i = nextIndex(staleSlot, len);
           (e = tab[i]) != null;
           i = nextIndex(i, len)) {
          ThreadLocal<?> k = e.get();
          if (k == null) {
              e.value = null;
              tab[i] = null;
              size--;
          } else {
              int h = k.threadLocalHashCode & (len - 1);
              if (h != i) {
                  tab[i] = null;

                  // Unlike Knuth 6.4 Algorithm R, we must scan until
                  // null because multiple entries could have been stale.
                  while (tab[h] != null)
                      h = nextIndex(h, len);
                  tab[h] = e;
              }
          }
      }
      return i;
}

// 时间复杂度 N * logN
// 返回是否清除过元素
private boolean cleanSomeSlots(int i, int n) {
    boolean removed = false;
    Entry[] tab = table;
    int len = tab.length;
    do {
        i = nextIndex(i, len);
        Entry e = tab[i];
        if (e != null && e.get() == null) {
            n = len;
            removed = true;
            i = expungeStaleEntry(i); // 时间复杂度 N
        }
    } while ( (n >>>= 1) != 0); // 时间复杂度 logN
    return removed;
}

ThreadLocal 的详细介绍

Thu, 03 Jul 2025 15:24:26 +0800

为什么需要 ThreadLocal

线程是最小的执行单元，多线程可以在同一时间同时执行相同的代码。如果多个线程在同一个对象或者是实例上执行，那么这些线程将共享对象或实例中的属性。同时每个线程都有它们自己的局部变量，但是这些局部变量如果不通过参数的方式传递，很难进行共享。

通过例子来解释是最好。假设有一个 Servlet，这个 Servlet 首先会获取用户的信息，然后执行一些其他的动作。

doGet(HttpServletRequest req, HttpServletReresponse resp) {
    User user = getLoggedInUser(req);
    doSomething();
    doSomethingElse();
    renderResponse(resp);
}

如果现在 doSomething() 和 doSomethingElse() 也需要用户信息，这个时候你该怎么办呢？你不能够把 user 变成一个实例变量或者是静态变量，因为其他的线程也会执行相同的代码, 可能出现用户信息被替换的情况。这时你可能会把用户信息作为一个参数传递给 doSomething() 和 doSomethingElse():

doGet(HttpServletRequest req, HttpServletReresponse resp) {
    User user = getLoggedInUser(req);
    doSomething(user);
    doSomethingElse(user);
    renderResponse(resp);
}

这种方式虽然临时解决了问题，但是这会让每个需要用户信息的方法都新增用户参数，并且随着时间的推移，如果又需要一些其他的信息呢？又增加参数吗？肯定不能够这么做，这大大增加了代码的维护难度，非常的不优雅。

更为优雅的处理方式是将用户相关的信息放入到 ThreadLocal 中:

StaticClass.java

class StaticClass {
  static private ThreadLocal<User> threadLocal = new ThreadLocal<>();

  static ThreadLocal<User> getThreadLocal() {
    return threadLocal;
  }
}

doGet(HttpServletRequest req, HttpServletResponse resp) {
  User user = getLoggedInUser(req);
  StaticClass.getThreadLocal().set(user)
  try {
    doSomething()
    doSomethingElse()
    renderResponse(resp)
  }
  finally {
    StaticClass.getThreadLocal().remove()
  }
}

然后在需要用户信息的地方在将其取出来：

User user = StaticClass.getThreadLocal().get()

什么是 ThreadLocal?

ThreadLocal 是 Java 提供的一个类，用于创建和管理线程的局部变量。每个线程都可以独立的访问和修改线程中的变量，而不影响其他的线程。ThreadLocal 的主要作用就是在多线程的环境下保存每个线程独有的数据，线程间互不影响，从而避免锁机制所带来的复杂性和额外的性能开销。

ThreadLocal 类似于一个中间件，它把对线程局部变量的操作进行了封装，通过 ThreadLocal 我们可以非常方便和优雅的访问和管理同一个线程中的局部变量。

ThreadLocal 的使用

有两种方式初始化 ThreadLocal：

// 1. 如果你希望局部变量有一个默认的初始值，可以使用这种方式
ThreadLocal<Integer> threadId = ThreadLocal.withInitial(() -> 2);

// 2. 没有默认值，直接 new 一个对象
ThreadLocal<integer> threadId = new ThreadLocal<>();

使用示例：

public class UserContext {
    private static ThreadLocal<User> userThreadLocal = new ThreadLocal<>();

    public static User getCurrentUser() {
        return userThreadLocal.get();
    }

    public static void setCurrentUser(User user) {
        userThreadLocal.set(user);
    }

    public static void clear() {
        userThreadLocal.remove();
    }
}

ThreadLocal 实现原理

前置代码

Thread.java

public class Thread implements Runnable {

    // ......

    /* ThreadLocal values pertaining to this thread. This map is maintained
     * by the ThreadLocal class. */
    ThreadLocal.ThreadLocalMap threadLocals = null;

    /*
     * InheritableThreadLocal values pertaining to this thread. This map is
     * maintained by the InheritableThreadLocal class.
     */
    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

    // ......
}

ThreadLocal.java

public class ThreadLocal<T> {
      // ......

      ThreadLocalMap getMap(Thread t) {
        return t.threadLocals;
      }

      protected T initialValue() {
          return null;
      }

      void createMap(Thread t, T firstValue) {
          t.threadLocals = new ThreadLocalMap(this, firstValue);
      }

      private T setInitialValue() {
          T value = initialValue();
          Thread t = Thread.currentThread();
          ThreadLocalMap map = getMap(t);
          if (map != null) {
              map.set(this, value);
          } else {
              createMap(t, value);
          }
          if (this instanceof TerminatingThreadLocal) {
              TerminatingThreadLocal.register((TerminatingThreadLocal<?>) this);
          }
          return value;
      }

      // ......
}

设置元素的流程

public class ThreadLocal<T> {
  
  	// .....
   
    public void set(T value) {
          Thread t = Thread.currentThread();
          ThreadLocalMap map = getMap(t);
          if (map != null) {
            	// key 是 ThreadLocal
              map.set(this, value);
          } else {
              createMap(t, value);
          }
      }
  
  	// .....
}

获取元素的流程

public class ThreadLocal<T> {
  	
  	// ......
  
    public T get() {
        Thread t = Thread.currentThread();
        ThreadLocalMap map = getMap(t);
        if (map != null) {
          	// key 是 ThreadLocal
            ThreadLocalMap.Entry e = map.getEntry(this); 
            if (e != null) {
                @SuppressWarnings("unchecked")
                T result = (T)e.value;
                return result;
            }
        }
        return setInitialValue();
    }
  
  	// ......
}

删除元素

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

通过上述源码阅读可以知道，ThreadLocal 的关键就是 Thread 类里面的 threadLocals 属性。通过 ThreadLocal 声明的线程局部属性都会保存在 Thread 类的threadLocals 属性中，key 为 ThreadLocal，value 为用户设定的值。

InheritableThreadLocal

InheritableThreadLocal 对 ThreadLocal 进行了扩展，允许在创建子线程的时候将父线程中已存在的线程局部变量继承到子线程中。继承后，父线程和子线程对局部变量的修改是独立的，互不影响。需要注意的是，子线程创建后，父线程中对局部变量的修改，子线程是无法感知的。这点需要注意，接下来是使用示例：

public class InheritableThreadLocalDemo {

    private static InheritableThreadLocal<String> threadLocal = new InheritableThreadLocal<>();

    public static void main(String[] args) {
        threadLocal.set("mainThread");
        System.out.println("value:"+threadLocal.get());
        Thread thread = new Thread(new Runnable() {
            @Override
            public void run() {
                String value = threadLocal.get();
                System.out.println("value:"+value);
            }
        });
        thread.start();
    }
}

执行结果：

value:mainThread
value:mainThread

如果将上述代码中 InheritableThreadLocal 改成 ThreadLocal, 则子线程中输出的值为 null

public class InheritableThreadLocalDemo {

    private static ThreadLocal<String> threadLocal = new ThreadLocal<>();

    public static void main(String[] args) {
        threadLocal.set("mainThread");
        System.out.println("value:"+threadLocal.get());
        Thread thread = new Thread(new Runnable() {
            @Override
            public void run() {
                String value = threadLocal.get();
                System.out.println("value:"+value);
            }
        });
        thread.start();
    }
}

执行结果：

value:mainThread
value:null

潜在的问题

ThreadLocal 虽然带来了很多的便利，但是使用不当的话，会导致内存泄漏，尤其是在 Thread 生命周期特别长情况下，比如线程池中的线程。如果当前线程不需要 ThreadLocal 后，应该使用 ThreadLocal 的 remove() 方法手动删除 ThreadLocal 存储的数据。

在哪些场景下使用

非线程安全的对象：Java 中的很多类都是非线程安全的，例如 SimpleDateFormat，NumberFormat. 通过 ThreadLocal 来使用这些类，可以让每个线程都拥有它们自己的实例，从而避免并发相关的问题。
线程特定上下文数据：需要在应用程序的不同层(方法)中访问的数据可以使用 ThreadLocal，比如用户信息，国际化设置或者是其他的上下文信息。这样可以避免上下文数据通过方法参数的方式到处传递，提升代码的可维护性。