These variables differ from their normal counterparts in that each thread that accesses one (via its
setmethod) has its own, independently initialized copy of the variable.
ThreadLocalinstances 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
Noncompliant Code Example
This noncompliant code example consists of an enumeration of days (
Day) and two classes (
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.
DiaryPool class consists of the
doSomething2() methods that each start a thread. The
doSomething1() method changes the initial (default) value of the day to Friday and invokes
doSomething2() relies on the initial value of the day (Monday) and invokes
main() method creates one thread using
doSomething1() and two more using
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:
Submitted by Method
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:
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 (
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.
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 (
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
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 data and executed by different tasks in a thread pool without reinitialization might be in an unexpected state when reused.