what you should know

A little about ThreadLocal

ThreadLocal is a special class in Java that gives each thread a separate copy of a variable. That is, different threads do not share data with each other, and thus races for resources can be avoided.

Simple example:

private static ThreadLocal<Integer> threadLocalVariable = new ThreadLocal<>();

public static void main(String[] args) {
    threadLocalVariable.set(100); // Устанавливаем значение для текущего потока
    System.out.println(threadLocalVariable.get()); // Получаем значение для текущего потока
    threadLocalVariable.remove(); // Удаляем значение, чтобы избежать утечек
}

When you use ThreadLocalthe data is stored in a special structure called ThreadLocalMapwhich is associated with every Thread object. Each entry in ThreadLocalMap is a key-value pair, where the key is an object ThreadLocaland the value is the data you bound to this object.

The key is stored as a WeakReference, which allows the garbage collector to remove the object if there are no longer strong references to it.

And at this point we move on to the main problems.

The main problems of ThreadLocal: from simple to complex

Memory leaks due to incorrect use of ThreadLocal

The first and perhaps most common problem is memory leaks. Why is this happening? If you forget to call remove()the data will remain in memory even after the thread has completed its main work.

Example:

public class MemoryLeakExample {
    private static ThreadLocal<String> threadLocalVariable = new ThreadLocal<>();

    public static void main(String[] args) {
        threadLocalVariable.set("Important data");
        // Пропустили вызов remove(), данные остаются в памяти
    }
}

The problem here is that even if the key is removed (due to a weak reference), the value remains bound to ThreadLocalMapwhile the stream itself is alive. This is very dangerous in server applications where threads can exist for a long time, like in Tomcat or Jetty. So be sure to call remove().

Problems with thread pools

Often ThreadLocal used in a thread pool. This is where the real fun begins. In a pool, threads are reused many times, and if you do not clear variables, data from one task can accidentally end up in another task, which will lead to completely unexpected bugs and memory leaks.

Example:

ExecutorService executor = Executors.newFixedThreadPool(5);
ThreadLocal<String> localVariable = new ThreadLocal<>();

for (int i = 0; i < 10; i++) {
    executor.submit(() -> {
        localVariable.set("task data");
        // Работаем с переменной
        localVariable.remove(); // Важно не забывать удалять переменные!
    });
}

If you forget to call remove()the next task can inherit data from the previous one. And this is already a complete mess. Task will write the data of one user to the log, and suddenly the log of another user appears there.

Incorrect initialization and errors with null

Another common problem is forgetting to explicitly set a value for ThreadLocal. In this case, on the first call get()you will receive nullwhich can lead to NullPointerException or some errors if the application relies on the presence of data in ThreadLocal.

Example:

public class UninitializedThreadLocal {
    private static ThreadLocal<String> local = new ThreadLocal<>();

    public static void main(String[] args) {
        System.out.println(local.get()); // Возвращает null, если значение не было установлено
    }
}

To avoid such surprises, you can use the method ThreadLocal.withInitial()which sets the default value for each thread:

private static ThreadLocal<String> local = ThreadLocal.withInitial(() -> "Default Value");

Now each thread will get the value if you forget to set it explicitly.

Performance issues

When you have many threads, each of which creates its own copy of the data in ThreadLocalthis may lead to additional memory overhead.

Solutions and recommendations: how to minimize risks

So, to summarize: to avoid stepping on a rake when using ThreadLocalfollow simple but important rules:

• Always call remove(): After finishing working with a variable, be sure to delete it to avoid leaks.

• Avoid using thread pools: if possible, it is better not to use it at all ThreadLocal in thread pools to avoid data inheritance between tasks.

• Memory monitoring: Use tools to monitor memory leaks.

If you need to work with multithreading, consider some alternatives.

Alternatives

Several powerful alternatives ThreadLocal:

1. Passing data through method parameters
   Instead of using ThreadLocaljust pass the necessary data explicitly through method parameters. This will make the code more predictable and transparent.

2. Thread-safe collections
   Use classes ConcurrentHashMap or BlockingQueuefor secure data access between threads.

3. Dependency Injection
   In DI frameworks (such as Spring), threads are managed automatically. Contexts are isolated without explicit use ThreadLocal.

4. Reactor and Vert.x Context
   In reactive applications, use contexts to manage data asynchronously, minimizing thread dependency.

5. Project Loom
   With Loom, Java will offer lightweight threads that eliminate the need for ThreadLocal.

The approach you choose depends on your scenario.

Conclusion

ThreadLocal is a powerful tool, but must be used with care.

In conclusion, I recommend to Java developers the open lesson “Development of a pdf file parser”, in which participants will develop a real useful application for parsing VTB Bank statements in pdf format. You can sign up for a lesson on the “Java Developer. Professional” page.