Page History

Any thread that invokes Threads that invoke Object.wait() expects expect to wake up and resume execution when some their condition predicate becomes true. As recommended by CON18To be compliant with THI03-J. Always invoke wait() and await() methods inside a loop, waiting threads should must test their condition predicates upon receiving notifications and must resume waiting if they the predicates are false.

The methods notify() and notifyAll() methods of package java.lang.Object are used to waken wake up a waiting thread (s)or threads, respectively. These methods must be invoked from code a thread that holds the same object lock as the waiting thread(s); these methods throw an IllegalMonitorStateException when invoked from any other thread. The notifyAll() method wakes up all threads and allows ones waiting on an object lock and allows threads whose condition predicate is true to resume execution. Furthermore, if all the threads whose condition predicate is now evaluates to true previously held a specific lock before going into the wait state, only one of them will reacquire the lock upon being notified. Presumably, and the others may, presumably, the other threads will resume waiting. The notify() method wakes up only one thread, and makes no guarantees as to which with no guarantee regarding which specific thread is notified. If the thread's The chosen thread is permitted to resume waiting if its condition predicate is not satisfied, the chosen thread may not awaken, defeating the purpose of the notify() call.unsatisfied; this often defeats the purpose of the notification.

Consequently, invoking the The notify() method may only be invoked if:is permitted only when all of the following conditions are met:

• All waiting threads have identical condition predicates.
• All threads Every condition predicate in every waiting thread would be satisfied if a notification were received by each, independently. Furthermore, all these threads must perform the same set of operations after waking up. In other wordsThat is, any one thread can be selected to wake up and resume for an a single invocation of notify().
• Only one thread must wake up on the notify signal. This is contingent on the condition predicate, in that, only one predicate must fulfill the condition and allow the thread to proceed. Multiple condition predicates in the same statement should be avoided.
• No untrusted code has access to the object being waited on. If untrusted code has access to this object, it can wait() on the object and intercept a notify() call.
• is required to wake upon the notification.

These conditions are satisfied by threads that are identical and provide a stateless service or utility.

The java.util.concurrent.locks utilities (interface Condition) provide the provide the Condition.signal() and Condition.signalAll() methods to awaken waiting threads that are blocked on an a Condition.await() call. Like the Condition objects are required when using java.util.concurrent.locks.Lock objects. Although Lock objects allow the use of Object.wait(), Object.notify() method, the signal() method wakes up any one of the threads that is waiting on the condition and consequently, may be insecure. It is always safer to use signalAll albeit a small performance penalty. Similarly, any thread that is blocked on a wait() method invocation on a Java object being used as a condition queue, should be notified using notifyAll().

Noncompliant Code Example (notify())

This noncompliant code example shows a complex multi-step process being undertaken by several threads. Each thread executes one step of the process; the step being currently performed is enumerated by the step field. Each thread waits for the step field to indicate that it is time to perform the corresponding thread's step. After performing the step, each thread increments step to transfer control to the next thread, notifies it, and exits.

, and Object.notifyAll() methods, their use is prohibited by LCK03-J. Do not synchronize on the intrinsic locks of high-level concurrency objects. Code that synchronizes using a Lock object uses one or more Condition objects associated with the Lock object rather than using its own intrinsic lock. These objects interact directly with the locking policy enforced by the Lock object. Consequently, the await(), signal(), and signalAll() methods are used in place of the wait(), notify(), and notifyAll() methods.

The signal() method must not be used unless all of these conditions are met:

• The Condition object is identical for each waiting thread.
• All threads must perform the same set of operations after waking up, which means that any one thread can be selected to wake up and resume for a single invocation of signal().
• Only one thread is required to wake upon receiving the signal.

or all of these conditions are met:

• Each thread uses a unique Condition object.
• Each Condition object is associated with the same Lock object.

When used securely, the signal() method has better performance than signalAll().

When notify() or signal() is used to waken a waiting thread, and the thread is not prepared to resume execution, it often resumes waiting. Consequently, no thread wakens, which may cause the system to hang.

Noncompliant Code Example (notify())

This noncompliant code example shows a complex, multistep process being undertaken by several threads. Each thread executes the step identified by the time field. Each thread waits for the time field to indicate that it is time to perform the corresponding thread's step. After performing the step, each thread first increments time and then notifies the thread that is responsible for the next step.

public final class ProcessStep implements Runnable {
  private static final Object lock = new Object();
  private static int time = 0;
  private final int step; // Do Perform operations when field time

public class ProcessStep implements Runnable {
  private static final Object lock = new Object();
  private static int time = 0;
  private final int step; // Do operations when the step reaches this value

  public ProcessStep(int step) {
    this.step = step;
  }

  public void run() {
    try {
      synchronized (lock) {
        while (time != step) { 
          lock.wait();    
        }

        // ...reaches Dothis operationsvalue

  public ProcessStep(int step) {
    time++this.step = step;
  }

  @Override public void  lock.notifyrun(); {
    try  }{
    }  catchsynchronized (InterruptedException ielock) {
      Thread.currentThread().interrupt(); // Reset interrupted status  while (time != step) {
    }    
  }

lock.wait();
   public static void main(String[] args) {}

    for (int i = 4;// i >= 0; i--) {Perform operations

      ProcessStep ms = new ProcessStep(i) time++;
       new Thread(ms).startlock.notify();
      }
    }
}

This noncompliant code example violates the liveness property. Each thread has a different condition predicate, as each requires step to have a different value before proceeding. The Object.notify() method wakes up only one thread at a time. unless it happens to wake up the thread that is to perform the next step, the program deadlocks.

Compliant Solution (notifyAll())

In this compliant solution, all threads that have performed their own step use notifyAll() to notify other waiting threads. Consequently, the respective threads that are ready can perform the task, while all other threads whose condition predicate is unsatisfied promptly go back to sleep.

  // ...
  public void run() {
    try {
      synchronized (lock) {
        while (time != step) { 
          lock.wait();  
        }

        // ... do stuff

        time++;
        lock.notifyAll();
      }
    } catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    }    
  }

Noncompliant Code Example (Condition interface)

This noncompliant code example derives from the previous noncompliant code example but uses the Condition interface. Field condition is used to let threads wait on different condition predicates.

 catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    }
  }

  public static void main(String[] args) {
    for (int i = 4; i >= 0; i--) {
      new Thread(new ProcessStep(i)).start();
    }
  }
}

This noncompliant code example violates the liveness property. Each thread has a different condition predicate because each requires step to have a different value before proceeding. The Object.notify() method wakes only one thread at a time. Unless it happens to wake the thread that is required to perform the next step, the program will deadlock.

Compliant Solution (notifyAll())

In this compliant solution, each thread completes its step and then calls notifyAll() to notify the waiting threads. The thread that is ready can then perform its task while all the threads whose condition predicates are false (loop condition expression is true) promptly resume waiting.

Only the run() method from the noncompliant code example is modified, as follows:

public final class ProcessStep implements Runnable {
  private static final Object lock = new Object();
  private static int time = 0;
  private final int step; // Perform operations when field time 
                          // reaches this value
  public ProcessStep(int step) {
    this.step = step;
  }

  @Override public void run() {
    try {
      synchronized (lock) {
        while (time != step) {
          lock.wait();
        }
  
        // Perform operations
  
        time++;

public class ProcessStep implements Runnable {
  private static final Lock lock = new ReentrantLock();
  private static final Condition condition = lock.newCondition();
  private static int time = 0;
  private final int step; // Do operations when the step reaches this value

  public ProcessStep(int step) {
    this.step = step;
  }

  public void run() {
    lock.lock();
    try {
      while (time != step) { 
        conditionlock.awaitnotifyAll(); // Use notifyAll() instead of notify()
      }

    } catch // ... Do operations

      time++;
      condition.signal();
    } catch (InterruptedException (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    }
 finally {
      lock.unlock();
    }
  }

  public static void main(String[] args) {
    for (int i = 4; i >= 0; i--) {
      ProcessStep ms = new ProcessStep(i);
      new Thread(ms).start();
    }
  }
}

Similar to Object.notify(), the Condition.signal() method may choose any one thread and awaken it.

Compliant Solution (signalAll())

This compliant solution uses the signalAll() method to resume all the waiting threads whose condition predicate allows doing so.

}

}

Noncompliant Code Example (Condition Interface)

This noncompliant code example is similar to the noncompliant code example for notify() but uses the Condition interface for waiting and notification:

public class ProcessStep implements Runnable {
  private static final Lock lock = new ReentrantLock();
  private static final Condition condition = lock.newCondition();
  private static int time = 0;
  private final int step; // Perform operations when field time 
                          // reaches this value
  public ProcessStep(int step) {
    this.step = step;
  }

  @Override public void run() {
    lock.lock();
    try {
      

  public void run() {
    lock.lock();
    try {
      while (time != step) { 
        condition.await();  
      }

      // ... do stuffPerform operations

      time++;
      condition.signalAllsignal();
    } catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
      lock.unlock();
    }
  }

Compliant Solution (unique Condition per thread)

This compliant solution assigns each thread its own Condition, and makes them accessible to all the threads.

// Declare class as final because its constructor throws an exception 
public final class ProcessStep implements Runnable { 
  private static final Lock lock = new ReentrantLock
  public static void main(String[] args) {
    for (int i = 4; i >= 0; i--) {
      new Thread(new ProcessStep(i)).start();
  private static int}
  }
}

As with Object.notify(), the signal() method may awaken an arbitrary thread.

Compliant Solution (signalAll())

This compliant solution uses the signalAll() method to notify all waiting threads. Before await() returns, the current thread reacquires the lock associated with this condition. When the thread returns, it is guaranteed to hold this lock [API 2014]. The thread that is ready can perform its task while all the threads whose condition predicates are false resume waiting.

Only the run() method from the noncompliant code example is modified, as follows:

public class ProcessStep implements Runnable {
  private static final Lock lock = new ReentrantLock();
  private static final Condition condition = lock.newCondition();
  private static int time = 0;
  private final int step; // Perform operations when field time 
    time = 0;
  private final int step; // Do operations when the step reaches this value
  private static final int MAX_STEPS = 5;
  private static final Condition[] conditions = new Condition[MAX_STEPS];

  public ProcessStep(int step) {
    if (step <= MAX_STEPS) {
      this.step = step;
      conditions[step] = lock.newCondition();
    } else {
      throw new IllegalArgumentException("Too many threads");
    }
  }

  public void run() {
    lock.lock();
    try {
      while (time != step) { 
        conditions[step].await();  
      }

      // ...reaches Dothis operations
value
  public ProcessStep(int   time++;step) {
    this.step = if (step;
 + 1 < conditions.length) { }

  @Override public void run() {
  conditions[step + 1]lock.signallock();
    try {
 }
    } catchwhile (InterruptedException ietime != step) {
        Threadcondition.currentThreadawait().interrupt();
      }
  
      // Reset interrupted statusPerform operations

    } finally {time++;
      lockcondition.unlocksignalAll();
    }
 catch }

  public static void main(String[] args) {(InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    for (int i = MAX_STEPS - 1; i >= 0; i--) {
      ProcessStep ms = new ProcessStep(i);
      new Thread(ms).start();
    }
  }
}

Even though signal() is used, it is guaranteed that only one thread will awaken because each condition predicate corresponds to a unique Condition variable.

Risk Assessment

Invoking the notify() method instead of notifyAll() can be a threat to the liveness property of the system.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[JLS 05|AA. Java References#JLS 05]\] [Chapter 17, Threads and Locks|http://java.sun.com/docs/books/jls/third_edition/html/memory.html]
\[[Goetz 06|AA. Java References#Goetz 06]\] Section 14.2.4, Notification
\[[Bloch 01|AA. Java References#Bloch 01]\] Item 50: Never invoke wait outside a loop

 } finally {
      lock.unlock();
    }
  }

}

Compliant Solution (Unique Condition per Thread)

This compliant solution assigns each thread its own condition. All the Condition objects are accessible to all the threads:

// Declare class as final because its constructor throws an exception
public final class ProcessStep implements Runnable {
  private static final Lock lock = new ReentrantLock();
  private static int time = 0;
  private final int step; // Perform operations when field time 
                          // reaches this value
  private static final int MAX_STEPS = 5;
  private static final Condition[] conditions = new Condition[MAX_STEPS];

  public ProcessStep(int step) {
    if (step <= MAX_STEPS) {
      this.step = step;
      conditions[step] = lock.newCondition();
    } else {
      throw new IllegalArgumentException("Too many threads");
    }
  }

  @Override public void run() {
    lock.lock();
    try {
      while (time != step) {
        conditions[step].await();
      }

      // Perform operations

      time++;
      if (step + 1 < conditions.length) {
        conditions[step + 1].signal();
      }
    } catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
      lock.unlock();
    }
  }

  public static void main(String[] args) {
    for (int i = MAX_STEPS - 1; i >= 0; i--) {
      ProcessStep ps = new ProcessStep(i);
      new Thread(ps).start();
    }
  }
}

Even though the signal() method is used, only the thread whose condition predicate corresponds to the unique Condition variable will awaken.

This compliant solution is safe only when untrusted code cannot create a thread with an instance of this class.

Risk Assessment

Notifying a single thread rather than all waiting threads can violate the liveness property of the system.

Automated Detection

Related Guidelines

Bibliography

...

Image Added Image Added Image AddedCON18-J. Always invoke wait() and await() methods inside a loop      11. Concurrency (CON)      CON20-J. Do not perform operations that may block while holding a lock