Understanding ThreadLocal: Introduction, Source Code, Problems, and Application Scenarios

ThreadLocal

is a utility class that provides a thread‑local variable, meaning each thread accesses its own independent copy of a variable rather than a shared one.

The implementation works by giving every thread a ThreadLocalMap that stores entries keyed by the ThreadLocal instance; each thread only sees its own map, making the values invisible to other threads.

Key methods are get, set, remove, and setInitialValue. The get method retrieves the current thread's map, looks up the value, and if null, initializes it via setInitialValue. The set method stores a value in the map, creating the map if necessary.

The source code for these methods is straightforward: get calls getMap, fetches the entry, and initializes if needed; set obtains the map and either updates an existing entry or creates a new ThreadLocalMap via new ThreadLocalMap(this, firstValue). The remove method delegates to ThreadLocalMap.remove, which computes the index from the key's hash and clears the matching entry.

ThreadLocal can cause memory leaks because the ThreadLocalMap holds strong references to values while the keys are weak references to the ThreadLocal objects. If a ThreadLocal is garbage‑collected but its value remains, the entry becomes a dangling reference, preventing the value from being reclaimed.

To avoid leaks, the implementation invokes replaceStaleEntry (replaces null keys with new entries) and cleanSomeSlots (removes entries whose keys are null). Developers should also explicitly call remove() when a ThreadLocal is no longer needed.

Typical application scenarios include per‑thread database connections or session management, and storing request objects in Spring MVC so they can be accessed anywhere in the call chain without passing them as parameters.

The article also lists common interview questions, such as why ThreadLocal uses a hash code instead of thread ID, how values are transferred between parent and child threads via InheritableThreadLocal, and how ThreadLocal ensures isolation between threads.

Overall, the piece provides a detailed walkthrough of ThreadLocal's design, source code, pitfalls, and practical uses for Java developers.