Page History

Wiki MarkupAccording to the Java API \[[API 06|AA. Java References#API 06]\], class {{The java.lang.ThreadLocal<T>}} documentation:

...

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 transaction ID).

Wiki MarkupThe use of {{ThreadLocal}} objects is insecure in classes whose objects are required to be executed by several threads, together in a thread pool. The technique of thread pooling allows threads to be reused when thread creation overhead is too high or creating an unbounded number of threads is a potential threat to the reliability of the system. Every thread that enters the pool expects to see an an object in its initial, default state. However, when {{ThreadLocal}} objects are set from a thread which is subsequently made available for reuse, the reusing thread which takes its place may see the most recent state that was set by the previous thread instead of the expected, default state. \[[JPL 06|AA. Java References#JPL 06]\] 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 Day of days (Day) and two classes , (Diary and DiaryPool). The Diary class Diary uses a ThreadLocal variable to store thread-specific information, such as each threadtask's current day. The initial value of the current day is Monday, and this ; it can be changed later by using invoking the setDay() method. The class also contains a thread-specific threadSpecificTask() instance method that performs a thread-specific task.

The DiaryPool class DiaryPool consists of two methods the doSomething1() and doSomething2() methods that each start one a thread each, respectively. The method doSomething1() method changes the initial (default) value of the day in the diary to Friday and invokes the threadSpecificTask() method. On the other hand, the method However, doSomething2() relies on the initial value of the day (Monday) in the diary and invokes the threadSpecificTask() method. 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 ...
    System.out.println("The current day is: " + currentDay());
  }
}

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

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

  public void doSomething1() {
    exec.execute(new Runnable() {
        @Override public void run() {
          Diarydiary.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
  } 
}

This noncompliant code example frequently produces an incorrect output, for example:

The current day is: FRIDAY

The

...

The issue is that the DiaryPool class uses creates a thread pool to execute multiple threads. This allows threads to be reused when the pool is full. When this happens, the thread local state of a previous thread may be inherited by a new thread that has just begun execution. In this case, even though the threads that were started using doSomething2() are expected to see the current day as Monday, one of them inherits the day Friday from the first thread, when that thread is reused. Increasing the thread pool size appears to fix the problem because it prints the expected state (Friday occurs only once):

The current day is: FRIDAY
The current day is: MONDAY
The current day is: MONDAY

The execution order may differ depending on thread scheduling, however, Friday occurs just once in this case. Note that increasing the thread pool size from time to time is not a feasible option.

Compliant Solution

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:

In this execution order, it is expected that the two tasks (t₂ and t₃) started from doSomething2() would observe the current day as Monday. However, because pool thread 1 is reused, t₃ 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 itThe class Diary does not use a ThreadLocal object in this compliant solution. Also, the class DiaryPool uses local instances of class Diary within the methods doSomething1() and doSomething2(). The Day is uniquely maintained by each instance of the Diary class. As multiple threads are allowed to share a Diary instance, the day field is declared static. Creating two Diary instances in class DiaryPool allows the first thread to work with the object instance having the current day as Friday and the other two threads to work with the object instance having the current day as Monday.

public final class Diary {
   private static Day day;

  Diary// ...
  public static void removeDay() {
    day = Day.MONDAY; // Default	
  days.remove();
  }
}

public final private Day currentDay()class DiaryPool {
    return day;
  }// ...

  public void setDaydoSomething1(Day d) {
    day = d;
  }

  // Performs some thread-specific task
  exec.execute(new Runnable() {
        @Override public void threadSpecificTaskrun() {
     //    Do tasktry ...{
    System.out.println("The day is: " + currentDay()        Diary.setDay(Day.FRIDAY);
  }
}

public final class DiaryPool {
  private final int NoOfThreads = 2diary.threadSpecificTask();
 //  Maximum number of threads allowed in pool
 } privatefinally final{
 Executor exec;

  DiaryPool() {
    exec = (Executor) ExecutorsDiary.newFixedThreadPoolremoveDay(NoOfThreads);
  }

  public void doSomething1() {// Diary.setDay(Day.MONDAY) 
    final Diary diary = new Diary(); // First instance
    exec.execute(new Runnable() {
      public void run() {
    // can also  diary.setDay(Day.FRIDAY);
be used
          diary.threadSpecificTask();
}
        }
    });
  } 

  public void doSomething2() // ...
}

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,
 final Diary diary = new Diary(); // Second instance
int maximumPoolSize, long keepAliveTime,
     exec.execute(new Runnable( TimeUnit unit, BlockingQueue<Runnable> workQueue) {
    super(corePoolSize, maximumPoolSize, keepAliveTime, public
 void run() {
        diary.threadSpecificTask(unit, workQueue);
  }

  @Override
  public }
void beforeExecute(Thread t, Runnable }r); {
  }

  public static void main(String[] args  if (t == null || r == null) {
    DiaryPool dp =throw new DiaryPoolNullPointerException();
    }
    dpDiary.doSomething1setDay(Day.MONDAY);
  // Thread 1, requires current day as Friday
    dp.doSomething2(); // Thread 2, requires current day as Monday super.beforeExecute(t, r);
  }
}

public final class DiaryPool {
  // ...
  DiaryPool() {
    exec = new CustomThreadPoolExecutor(NumOfthreads, NumOfthreads,
    dp.doSomething2(); // Thread 2, requires current day as Monday
  } 
}

As expected, this code prints an order in which Friday occurrs just once, for example:

The current day is: FRIDAY
The current day is: MONDAY
The current day is: MONDAY

Classes that cannot be refactored and whose design incorporates ThreadLocal data should not be executed in thread pools.

Exceptions

 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 initializationEX1: Sometimes the state of the ThreadLocal object does not change beyond its initial value. For example, there may be only one type of database connection represented by the initial value of the ThreadLocal object. In the absence of mutability, it is safe to use a thread pool.

Risk Assessment

When objects of classes that use Objects using ThreadLocal data are and executed by different tasks in a thread pool by different threads, they may assume stale states, resulting in corrupt datawithout reinitialization might be in an unexpected state when reused.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

...

Bibliography

...

Image Added Image Added Image Added}} \[[JPL 06|AA. Java References#JPL 06]\] 14.13. ThreadLocal VariablesFIO36-J. Do not create multiple buffered wrappers on an InputStream      09. Input Output (FIO)      09. Input Output (FIO)