Understanding ThreadLocal: Usage, Implementation, and Memory Leak Risks

1. What is ThreadLocal

ThreadLocal provides thread‑local variables, giving each thread its own independent copy of a variable. Accessing a variable via get or set operates on the thread‑specific copy, not a shared instance. Typically a ThreadLocal is declared as a private static field to associate state (e.g., user ID or transaction ID) with a particular thread.

Each Thread holds a ThreadLocal.ThreadLocalMap instance named threadLocals. The map stores entries where the key is the ThreadLocal object (held as a weak reference) and the value is the thread‑specific data.

2. Usage Examples

Example 1: A simple counter demonstrates that each thread maintains an independent value.

package com.shepherd.example.juc;

public class ThreadLocalDemo {
    private static ThreadLocal<Integer> countValue = new ThreadLocal<Integer>(){
        // implement initialValue()
        public Integer initialValue(){
            return 0;
        }
    };

    public int nextSeq(){
        countValue.set(countValue.get() + 1);
        return countValue.get();
    }

    public static void main(String[] args){
        ThreadLocalDemo demo = new ThreadLocalDemo();
        MyThread thread1 = new MyThread(demo);
        MyThread thread2 = new MyThread(demo);
        MyThread thread3 = new MyThread(demo);
        MyThread thread4 = new MyThread(demo);
        thread1.start();
        thread2.start();
        thread3.start();
        thread4.start();
    }

    private static class MyThread extends Thread{
        private ThreadLocalDemo demo;
        MyThread(ThreadLocalDemo demo){
            this.demo = demo;
        }
        @Override
        public void run(){
            for(int i = 0; i < 3; i++){
                System.out.println(Thread.currentThread().getName() + " countValue :" + demo.nextSeq());
            }
        }
    }
}

Running the program prints a sequence where each thread’s count starts at 1 and increments independently, confirming thread isolation.

Sample output:

Thread-0 seqCount :1
Thread-3 seqCount :1
Thread-2 seqCount :1
Thread-1 seqCount :1
Thread-2 seqCount :2
Thread-3 seqCount :2
Thread-0 seqCount :2
Thread-3 seqCount :3
Thread-2 seqCount :3
Thread-1 seqCount :2
Thread-0 seqCount :3
Thread-1 seqCount :3
Process finished with exit code 0

Example 2: In a Spring MVC interceptor, a ThreadLocal<LoginVO> stores the authenticated user for the duration of a request, allowing downstream code to retrieve the user without passing it explicitly.

@Component
public class AuthInterceptor implements HandlerInterceptor{
    private static final String AUTHORIZE_TOKEN = "authorization";
    public static ThreadLocal<LoginVO> localUser = new ThreadLocal<>();

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception{
        String token = request.getHeader(AUTHORIZE_TOKEN);
        if(StringUtils.isBlank(token)){
            response.setStatus(HttpStatus.METHOD_NOT_ALLOWED.value());
            return false;
        }
        try{
            Claims claims = JwtUtil.parseJWT(token);
            LoginVO loginVO = JSONObject.parseObject(claims.getSubject(), LoginVO.class);
            localUser.set(loginVO);
        }catch(Exception e){
            e.printStackTrace();
            response.setStatus(HttpStatus.UNAUTHORIZED.value());
            return false;
        }
        return true;
    }
}

3. ThreadLocal Source Code

The core of ThreadLocal is the inner class ThreadLocalMap. It stores entries where the key is a weak reference to the ThreadLocal and the value is the thread‑specific data.

static class Entry extends WeakReference<ThreadLocal<?>>{
    /** The value associated with this ThreadLocal. */
    Object value;
    Entry(ThreadLocal<?> k, Object v){
        super(k);
        value = v;
    }
}

The two most important methods are set(ThreadLocal<?> key, Object value) and get().

private void set(ThreadLocal<?> key, Object value){
    ThreadLocal.ThreadLocalMap.Entry[] tab = table;
    int len = tab.length;
    int i = key.threadLocalHashCode & (len-1);
    for(ThreadLocal.ThreadLocalMap.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 ThreadLocal.ThreadLocalMap.Entry(key, value);
    int sz = ++size;
    if(!cleanSomeSlots(i, sz) && sz >= threshold)
        rehash();
}

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;
        }
    }
    return setInitialValue();
}

getMap(Thread t)

simply returns t.threadLocals. If the map does not exist, createMap(Thread t, T firstValue) creates a new ThreadLocalMap for the thread.

4. Memory‑Leak Risks

Although the map’s key is a weak reference, the value remains strongly reachable from the thread as long as the thread lives. If a thread (e.g., from a thread pool) is not terminated, the value cannot be garbage‑collected, leading to a memory leak.

To mitigate this, the implementation clears stale entries when key == null and developers should explicitly call ThreadLocal.remove() or ensure that thread‑local values are cleared when a thread is returned to a pool.

5. Summary

ThreadLocal provides per‑thread state isolation, not a mechanism for shared mutable data.

Each thread holds a ThreadLocalMap that stores weak‑referenced keys and strong‑referenced values.

The map’s set method handles key collisions, stale entries, and rehashing; get retrieves the value or falls back to the initial value.

Improper use with long‑lived threads (especially thread pools) can cause memory leaks; calling remove() or clearing entries prevents this.