Skip to end of metadata
Go to start of metadata

The java.lang.ThreadLocal<T> class provides thread-local variables. According to the Java API [API 2014]:

These variables differ from their normal counterparts in that each thread that accesses one (via its get or set method) has its own, independently initialized copy of the variable. ThreadLocal instances are typically private static fields in classes that wish to associate state with a thread (e.g., a user ID or transaction ID).

The use of ThreadLocal objects requires care in classes whose objects are required to be executed by multiple threads in a thread pool. The technique of thread pooling allows threads to be reused to reduce thread creation overhead or when creating an unbounded number of threads can diminish the reliability of the system. Each task that enters the pool expects to see ThreadLocal objects in their initial, default state. However, when ThreadLocal objects are modified on a thread that is subsequently made available for reuse, the next task executing on the reused thread sees the state of the ThreadLocal objects as modified by the previous task that executed on that thread [JPL 2006].

Programs must ensure that each task that executes on a thread from a thread pool sees only correctly initialized instances of ThreadLocal objects.

Noncompliant Code Example

This noncompliant code example consists of an enumeration of days (Day) and two classes (Diary and DiaryPool). The Diary class uses a ThreadLocal variable to store thread-specific information, such as each task's current day. The initial value of the current day is Monday; it can be changed later by invoking the setDay() method. The class also contains a threadSpecificTask() instance method that performs a thread-specific task.

The DiaryPool class consists of the doSomething1() and doSomething2() methods that each start a thread. The doSomething1() method changes the initial (default) value of the day to Friday and invokes threadSpecificTask(). However, doSomething2() relies on the initial value of the day (Monday) and invokes threadSpecificTask(). The main() method creates one thread using doSomething1() and two more using doSomething2().

public enum Day {
  MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY;
}

public final class Diary {
  private static final ThreadLocal<Day> days =
      new ThreadLocal<Day>() {
    // Initialize to Monday
    protected Day initialValue() {
      return Day.MONDAY;
    }
  };

  private static Day currentDay() {
    return days.get();
  }

  public static void setDay(Day newDay) {
    days.set(newDay);
  }

  // Performs some thread-specific task
  public void threadSpecificTask() {
    // Do task ...
  }
}

public final class DiaryPool {
  final int numOfThreads = 2; // Maximum number of threads allowed in pool
  final Executor exec;
  final Diary diary;

  DiaryPool() {
    exec = (Executor) Executors.newFixedThreadPool(numOfThreads);
    diary = new Diary();
  }

  public void doSomething1() {
    exec.execute(new Runnable() {
        @Override public void run() {
          diary.setDay(Day.FRIDAY);
          diary.threadSpecificTask();
        }
    });
  }

  public void doSomething2() {
    exec.execute(new Runnable() {
        @Override public void run() {
          diary.threadSpecificTask();
       }
    });
  }

  public static void main(String[] args) {
    DiaryPool dp = new DiaryPool();
    dp.doSomething1(); // Thread 1, requires current day as Friday
    dp.doSomething2(); // Thread 2, requires current day as Monday
    dp.doSomething2(); // Thread 3, requires current day as Monday
  }
}

The DiaryPool class creates a thread pool that reuses a fixed number of threads operating off a shared, unbounded queue. At any point, no more than numOfThreads threads are actively processing tasks. If additional tasks are submitted when all threads are active, they wait in the queue until a thread is available. The thread-local state of the thread persists when a thread is recycled.

The following table shows a possible execution order:

Time

Task

Pool Thread

Submitted by Method

Day

1

t1

1

doSomething1()

Friday

2

t2

2

doSomething2()

Monday

3

t3

1

doSomething2()

Friday

In this execution order, it is expected that the two tasks (t2 and t3) started from doSomething2() would observe the current day as Monday. However, because pool thread 1 is reused, t3 observes the day to be Friday.

Noncompliant Code Example (Increase Thread Pool Size)

This noncompliant code example increases the size of the thread pool from two to three in an attempt to mitigate the issue:

public final class DiaryPool {
  final int numOfthreads = 3;
  // ...
}

Although increasing the size of the thread pool resolves the problem for this example, it fails to scale because changing the thread pool size is insufficient if additional tasks can be submitted to the pool.

Compliant Solution (try-finally Clause)

This compliant solution adds the removeDay() method to the Diary class and wraps the statements in the doSomething1() method of class DiaryPool in a try-finally block. The finally block restores the initial state of the thread-local days object by removing the current thread's value from it.

public final class Diary {
  // ...
  public static void removeDay() {
    days.remove();
  }
}

public final class DiaryPool {
  // ...

  public void doSomething1() {
      exec.execute(new Runnable() {
        @Override public void run() {
          try {
            Diary.setDay(Day.FRIDAY);
            diary.threadSpecificTask();
          } finally {
            Diary.removeDay(); // Diary.setDay(Day.MONDAY) 
                               // can also be used
          }
        }
    });
  }

  // ...
}

If the thread-local variable is read by the same thread again, it is reinitialized using the initialValue() method unless the task has already set the variable's value explicitly [API 2014]. This solution transfers the responsibility for maintenance to the client (DiaryPool) but is a good option when the Diary class cannot be modified.

Compliant Solution (beforeExecute())

This compliant solution uses a custom ThreadPoolExecutor that extends ThreadPoolExecutor and overrides the beforeExecute() method. The beforeExecute() method is invoked before the Runnable task is executed in the specified thread. The method reinitializes the thread-local variable before task r is executed by thread t.

class CustomThreadPoolExecutor extends ThreadPoolExecutor {
  public CustomThreadPoolExecutor(int corePoolSize,
      int maximumPoolSize, long keepAliveTime,
      TimeUnit unit, BlockingQueue<Runnable> workQueue) {
    super(corePoolSize, maximumPoolSize, keepAliveTime, 
          unit, workQueue);
  }

  @Override
  public void beforeExecute(Thread t, Runnable r) {
    if (t == null || r == null) {
      throw new NullPointerException();
    }
    Diary.setDay(Day.MONDAY);
    super.beforeExecute(t, r);
  }
}

public final class DiaryPool {
  // ...
  DiaryPool() {
    exec = new CustomThreadPoolExecutor(NumOfthreads, NumOfthreads,
               10, TimeUnit.SECONDS, new ArrayBlockingQueue<Runnable>(10));
    diary = new Diary();
  }
  // ...
}

Exceptions

TPS04-J-EX0: It is unnecessary to reinitialize a ThreadLocal object that does not change state after initialization. For example, there may be only one type of database connection represented by the initial value of the ThreadLocal object.

Risk Assessment

Objects using ThreadLocal data and executed by different tasks in a thread pool without reinitialization might be in an unexpected state when reused.

Rule

Severity

Likelihood

Remediation Cost

Priority

Level

TPS04-J

Medium

Probable

High

P4

L3

Bibliography

[API 2014]

Class java.lang.ThreadLocal<T>

[JPL 2006]

Section 14.13, "ThreadLocal Variables"

 


4 Comments

  1. Two problems:

    First, this rule seems a little like developer carelessness. I think using ThreadLocal objects in thread pools are perfectly safe if you do any of the following:

    • Guarentee no threads are recycled (I believe you can tweak the thread pool to destroy threads immediately upon task completion, right)
    • Never realy on a ThreadLocal's initialValue()
    • Have each ThreadLocal var reset its initial value when your thread starts (use ThreadLocal.remove())

    Presumably we could 'fix' the NCCE with three additional CS's, one for each solution I outline above.

    Second, I think there are race conditions in the NCCE. Specifically I'm not convinced that the output arose in the same order the tasks were submitted. This could be fixed by adding a number to each task. It's not the order the output lines appear in that matters, but rather that they indicate exactly which task produced which output.

      • Guaranteeing that no threads are recycled would defeat the purpose of a thread pool.
      • A diagnostic would ideally be generated not when the class is used but when initialValue() is invoked and probably after determining if values are being mutated from their default state. However, note that it is quite unlikely (although still possible with questionable design) that a class will be usable if its thread local variable is to be completely avoided. Perhaps we need an exception to the guideline. Also, if you don't rely on initialValue() I wonder if there is something else left to rely on.
      • This can be better handled by a finally clause. Basically ensure that the default state is reinstated even if the task is interrupted. Might work as a compliant solution where doSomething1() sets the day back to its initial value upon doing its deed.

      Adding task numbers might not help either because on every run different task numbers will be associated with different days. Basically, we cannot control which task will go next into the thread pool. So, the text would still be incorrect because there are race conditions that might produce a different order. Doing what I've done helped me avoid the mess.

  2. It seems like there should be a compliant solution based on the beforeExecute() method:

    See http://java.sun.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.html#beforeExecute%28java.lang.Thread,%20java.lang.Runnable%29

    Also see http://java.sun.com/javase/6/docs/api/java/util/concurrent/Executors.html

    privilegedThreadFactory

    public static ThreadFactory privilegedThreadFactory()

    Returns a thread factory used to create new threads that have the same permissions as the current thread. This factory creates threads with the same settings as defaultThreadFactory(), additionally setting the AccessControlContext and contextClassLoader of new threads to be the same as the thread invoking this privilegedThreadFactory method. A new privilegedThreadFactory can be created within an AccessController.doPrivileged(java.security.PrivilegedAction) action setting the current thread's access control context to create threads with the selected permission settings holding within that action.

    Note that while tasks running within such threads will have the same access control and class loader settings as the current thread, they need not have the same ThreadLocal or InheritableThreadLocal values. If necessary, particular values of thread locals can be set or reset before any task runs in ThreadPoolExecutor subclasses using ThreadPoolExecutor.beforeExecute(java.lang.Thread, java.lang.Runnable). Also, if it is necessary to initialize worker threads to have the same InheritableThreadLocal settings as some other designated thread, you can create a custom ThreadFactory in which that thread waits for and services requests to create others that will inherit its values.

    Returns:
    a thread factory
    Throws:
    AccessControlException - if the current access control context does not have permission to both get and set context class loader.

  3. Fixed, please review. I think the following advice that you cited is good but currently beyond the scope of this guideline:

    Also, if it is necessary to initialize worker threads to have the same InheritableThreadLocal settings as some other designated thread, you can create a custom ThreadFactory in which that thread waits for and services requests to create others that will inherit its values.

    This guideline isn't getting into inheriting the state from another thread. For example, from InheritableThreadLocal's API docs:

    Inheritable thread-local variables are used in preference to ordinary thread-local variables when the per-thread-attribute being maintained in the variable (e.g., User ID, Transaction ID) must be automatically transmitted to any child threads that are created.

    Also I think a CS or exception based on this would be tricky because this article (Goetz) says:

    To preserve thread-safety, you should use InheritableThreadLocal only for immutable objects (objects whose state will not ever be changed once created), because the object is shared between multiple threads. InheritableThreadLocal is useful for passing data from a parent thread to a child thread, such as a user id, or a transaction id, but not for stateful objects like JDBC Connections.