What is ThreadLocal?

ThreadLocal provides thread-local variables. Unlike regular variables that are shared across threads, each thread accessing a ThreadLocal variable gets its own independently initialized copy.

Think of it as a private storage compartment for each thread. When you declare a ThreadLocal field, the runtime ensures every thread receives a separate instance of that value.

This mechanism eliminates thread contention issues since no two threads can interfere with each other's data. The get() and set() operations work on the calling thread's isolated copy.

How ThreadLocal Works Internally

The implementation relies on a clever design embedded within the Thread class itself.

public class Thread implements Runnable {
    // Stores thread-local variables for this thread
    ThreadLocal.ThreadLocalMap threadLocals = null;
    
    // Stores inheritable thread-local variables
    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;
}

Each Thread instance maintains its own ThreadLocalMap—a custom hash map implementation specific to ThreadLocal. The map stores entries keyed by ThreadLocal instances with corresponding values.

The map remains null until a thread actually invokes set() or get() on a ThreadLocal. This lazy initialization keeps overhead minimal for threads that never use thread-local storage.

The set() Method Implementation

public void set(T value) {
    Thread currentThread = Thread.currentThread();
    ThreadLocalMap map = accessThreadMap(currentThread);
    
    if (map != null) {
        map.store(this, value);
    } else {
        initializeThreadMap(currentThread, value);
    }
}

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

The process works like this:

1. Retrieve the currently executing thread
2. Access that thread's ThreadLocalMap
3. If the map exists, store the value keyed to the current ThreadLocal
4. If not, create the map first, then store the value

ThreadLocalMap Structure

ThreadLocalMap(ThreadLocal<?> key, Object value) {
    // Initialize internal table with capacity for initial entry
}

ThreadLocalMap functions as a specialized HashMap optimized for thread-local storage. It uses ThreadLocal instances as keys, enabling direct retrieval of values specific to the calling thread.

The data isn't stored in the ThreadLocal object itself—rather, each thread carries its own map containing key-value pairs where the key is the ThreadLocal reference. This design allows multiple ThreadLocal variables to coexist within a single thread, each maintaining its own isolated value.