Select Page

Intro to ThreadLocal in Java

Joydip Kanjilal
Published: August 12, 2022

Java Developer Tutorials

For the value of a variable in Java to be available across different threads at any given point in time, developers must use synchronization mechanisms provided by the Java programming language, such as the synchronized keyword or lock objects.

This ensures only one thread gets access at any time, ensuring no conflicts arise between concurrent accesses from multiple threads when using variables within those areas where there could potentially be contention issues. Enter ThreadLocal.

The ThreadLocal class in Java allows programmers to create variables that are accessible only to the thread that created them. This is useful for creating thread-safe code, as it ensures that each thread has its own copy of a variable and can not interfere with other threads.

This means every thread running in your application will have its own copy of the variables, depending on what context they belong to. In this programming tutorial, we will look at the basic concepts related to the ThreadLocal class, its benefits, how it works, and how it can be used in Java applications.

Read: Best Application Performance Monitoring Tools

Thread-Safety in Java

There are many ways to achieve thread safety in Java, and each has its advantages and disadvantages:

  • Synchronized blocks or methods: This is the most basic form of thread safety, and it can be effective in some cases. However, it can also lead to performance problems if not used carefully.
  • Atomic variables: These are variables that can be read and written atomically, without the need for synchronization. You can leverage ThreadLocal in Java to reduce the cost of synchronization.
  • Immutable objects: If an object’s state cannot change once created, it is said to be immutable. This is often used with other approaches, such as synchronized methods or atomic variables.
  • Lock objects: You can take advantage of these objects to lock a chunk of code such that access to this block of code will be allowed to only one thread at a particular point. They enable better finer-grained control than synchronized blocks or methods but may also result in more complicated code.

What is ThreadLocal in Java?

ThreadLocal is a special class in Java that helps us achieve thread safety by providing per-thread contexts and maintaining them separately for each thread. In other words, ThreadLocal is a Java class that can be used to define variables accessible solely by the thread that created them. This can be useful in a number of situations, but the most common use case is when you need to store data that should not be shared between threads.

For example, let’s say a developer is writing a multi-threaded application, and each thread needs to have its own copy of a variable. If you were to simply use a regular variable, it is possible that one thread would overwrite the value of the variable before another thread has a chance to use it. With ThreadLocal, each thread has its own copy of the variable, so there is no risk of one thread overwriting the value before another thread has a chance to use it.

A ThreadLocal instance is represented as a private static field in a Java class that needs to store thread-specific information. ThreadLocal variables are not global variables, so they cannot be accessed by other threads unless they are explicitly passed to the other threads. This makes them ideal for storing sensitive information, such as passwords or user IDs, which should not be accessible to other threads.

When to use ThreadLocal?

There are several reasons for using ThreadLocal in Java. The most common use case is when you need to maintain state information for a given thread, but that state is not shareable between threads. For example, if you are using a JDBC connection pool, each thread will need its connection. In this case, using ThreadLocal allows each thread to have its connection without having to worry about the overhead of creating and destroying connections every time a thread is created or destroyed.

Another common use case for ThreadLocal is when you need to share state information between different components in a single thread. For example, if you have a service that needs to call multiple DAOs (database access objects), each DAO might need its ThreadLocal variable to store the current transaction or session information. This allows each component to access the state it requires without worrying about passing around data between components.

Finally, you can also use ThreadLocal as a simple way to create global variables for a thread. This is often useful for debugging or logging purposes. For example, you could create a ThreadLocal variable that stores the current user ID. This would allow you to easily log all actions performed by that user without having to pass the user ID around everywhere.

You can learn more about logging by reading our tutorial: Working with the Java Logging API.

How to use ThreadLocal in Java

To use ThreadLocal, you first need to create a ThreadLocal instance:

ThreadLocal threadLocal = new ThreadLocal();

Once you have done this, you can store data in the ThreadLocal instance by calling the set() method:

threadLocal.set("This is a thread local data");

To retrieve the data from the ThreadLocal instance, you can call the get() method:

String data = (String) threadLocal.get();

You can also remove the value of a ThreadLocal variable by calling the remove() method. For example, to remove the value of threadLocal, you would use this Java code snippet:


It is important to remember to remove the value of a ThreadLocal variable when you are finished with it because, otherwise, it will stay in memory and could cause memory leaks.

Read: Tips to Improve Java Performance

Finally, you can call the clear() method to remove the values of all ThreadLocal variables. This is generally only necessary when a developer’s program is shutting down. For example, to clear all ThreadLocal variables, you can use the following piece of code:


It is important to note that the data in a ThreadLocal instance is only accessible to the thread that created it. If you try to access the data from another thread, you will get an IllegalStateException.

Pros and Cons of Using Java’s ThreadLocal

When used correctly, the ThreadLocal class in Java may reduce the overhead of synchronization and boost performance. By eliminating memory leaks, the code can be read and maintained more easily.

Programmers can use ThreadLocal variables when they need to maintain a state that is specific to a single thread, when they need to improve performance by reducing synchronization, and when they need to prevent memory leaks.

Some of the downsides associated with using ThreadLocal variables include race conditions and memory leaks.

How to Prevent Race Conditions

There is no guaranteed way to prevent race conditions when using ThreadLocal variables, as they are inherently prone to race conditions. However, there are some best practices that can help reduce the likelihood of race conditions, such as using atomic operations and ensuring that all access to ThreadLocal variables are properly synchronized.

Final Thoughts on ThreadLocal in Java

ThreadLocal is a powerful API in Java that allows developers to store and retrieve data that is specific to a given Thread. In other words, ThreadLocal allows you to define variables accessible only by the thread that creates them.

When used correctly, ThreadLocal can be a valuable tool for creating high-performant, thread-safe code. However, it is important to be aware of the potential risks and downsides of using ThreadLocal before using it in your Java applications.

Read more Java programming tutorials and software development guides.