Page History

 its [condition predicate|BB. Definitions#condition predicate] becomes true.  Waiting threads must test their condition predicates upon receiving notifications and resume waiting if the predicates are false, to be compliant with [CON18-J. Always invoke wait() and await() methods inside a loop].

The {{notify()}} and {{notifyAll()}} methods of package {{java.lang.Object}} are used to wake up waiting thread(s). These methods must be invoked from code that holds the same object lock as the waiting thread(s). An {{IllegalMonitorStateException}} is thrown if the current thread does not acquire this object's intrinsic lock before invoking these methods. The {{notifyAll()}} method wakes up all threads and allows threads whose condition predicate is true to resume execution. Furthermore, if all the threads whose condition predicate 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, the other threads will resume waiting.  The {{notify()}} method wakes up only one thread and makes no guarantees as to which thread is notified. If the thread's condition predicate doesn't allow the thread to proceed, the chosen thread may resume waiting, defeating the purpose of the notification.

The {{notify()}} method may only be invoked if all of the following conditions are met:
* The condition predicate is identical for each waiting thread. 
* All threads must perform the same set of operations after waking up. This means that any one thread can be selected to wake up and resume for a single invocation of {{notify()}}.
* Only one thread 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}} utilities (interface {{Condition}}) provide the {{signal()}} and {{signalAll()}} methods to awaken threads that are blocked on an {{await()}} call. {{Condition}} objects are required when using {{Lock}} objects. A {{Lock}} object allows the use of {{wait()}} and {{notify()}} methods, however, code that synchronizes using a {{Lock}} object does not employ its intrinsic lock. Instead, one or more {{Condition}} objects are associated with the {{Lock}} object, in that, these objects directly interact with the locking policy enforced by the {{Lock}} object. Consequently, the methods {{Condition.await()}}, {{Condition.signal()}} and {{Condition.signalAll()}} are used instead of {{Object.wait()}}, {{Object.notify()}} and {{Object.notifyAll()}}. 

The use of {{signal()}} is insecure when several threads are using the same {{Condition}} object unless the following conditions are met:

* The {{Condition}} object is identical for each waiting thread. 
* All threads must perform the same set of operations after waking up. This 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. 

The {{signal()}} method can also be used safely when:

* Each thread uses a unique {{Condition}} object.
* Each condition object is associated with a common {{Lock}} object. 

The {{signal()}} method is preferred over {{signalAll()}} for performance reasons, when the above criteria is met. 


h2. 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 performed is indicated 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 increments {{time}} to transfer control to the next thread. Next, the thread notifies the thread that is responsible for the next step and then exits.

{code:bgColor=#FFcccc}
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 reaches 
                          // 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++;
        lock.notify();
      }
    } 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();
    }
  }
}
{code}

public class ProcessStep implements Runnable= step;
  }

  @Override public void run() {
    lock.lock();
    try {
  private static final Lock while (timelock != step) { new ReentrantLock();
  private static final Condition condition = conditionlock.awaitnewCondition();
  
private static int time =  }
0;
  private final int step; // Perform operations
 when field time 
      time++;
      condition.signal();
    } catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status// reaches this value
  public  } finallyProcessStep(int step) {
    this.step = lock.unlock()step;
    }

  }

 @Override public static void mainrun(String[] args) {
    for (int i = 4; i >= 0; i--lock.lock();
    try {
      while (time != step) {
      new Thread(new ProcessStep(i)).start condition.await();
    }
  }
}
{code}
      // Perform operations

As with {{Object.notify()}}, the {{signal()}} method maytime++;
 awaken an arbitrary thread.  condition.signal();
    } catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
      lock.unlock();
    }
  }

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

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


h2. 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 06|AA. Java References#API 06]\] {mc} what is meant by "the thread returns?". I think it should be "when the thread wakes up/resumes" {mc}. 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:

{code:bgColor=#ccccff}
  @Override public void run() {
    lock.lock();
    try {
      while (time != step) { 
        condition.await();  
      }

      // Perform operations

      time++;
      condition.signalAll();
    } catch (InterruptedException ie// reaches this value
  public ProcessStep(int step) {
    this.step  Thread.currentThread().interrupt= step;
  }

  @Override public void run() {
    lock.lock();
  // Reset interruptedtry status{
      while (time }!= finallystep) {
        lockcondition.unlockawait();
      }
  }
{code}


h2. Compliant Solution   (Unique Condition// PerPerform Thread)operations

This     compliant solutiontime++;
 assigns each thread its own condition.signalAll();
  All the {{Condition}} objects are accessible to all the threads. 

{code:bgColor=#ccccff}
// Declare class as final because its constructor throws an exception 
public final class ProcessStep implements Runnable { 
  private static final Lock lock = new ReentrantLock} catch (InterruptedException ie) {
      Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
      lock.unlock();
  private static int}
  }

}

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

  private publicfinal ProcessStep(int step); {
// Perform operations when if (step <= MAX_STEPS) {
field time 
           this.step = step;
      conditions[step] = lock.newCondition();
    } else// {
reaches this value
  private static throwfinal new IllegalArgumentException("Too many threads")int MAX_STEPS = 5;
  private  }
  }

  @Override public void run(static final Condition[] conditions = new Condition[MAX_STEPS];

  public ProcessStep(int step) {
    if lock.lock();
    try(step <= MAX_STEPS) {
      while (time !this.step = step) { 
  ;
      conditions[step] = lock.awaitnewCondition();  
    } else }
{
      //throw Perform operations

  new IllegalArgumentException("Too many threads");
    time++;}
  }

  @Override public ifvoid run(step) {
 + 1 < conditionslock.length)lock();
    try {
      while (time != step) {
        conditions[step + 1].signalawait();
      }

    } catch (InterruptedException ie) {// Perform operations

      Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
time++;
      if (step + 1 < conditions.length) {
        conditions[step + lock1].unlocksignal();
    }
  }

   public static} voidcatch main(String[]InterruptedException argsie) {
     for (int i = MAX_STEPS - 1; i >= 0; i--)Thread.currentThread().interrupt(); // Reset interrupted status
    } finally {
      ProcessStep ps = new ProcessStep(i);lock.unlock();
    }
  }

  public static newvoid Thread(ps).start();main(String[] args) {
    }
for  }
}
{code}

Even though {{signal()}} is used, only the thread whose condition predicate corresponds to the unique {{Condition}} variable will awaken. All threads perform the same set of operations upon waking up. 

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


h2. Risk Assessment

Notifying a single thread instead of all waiting threads can pose a threat to the liveness property of the system.

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| CON19- J | low | unlikely | medium | {color:green}{*}P2{*}{color} | {color:green}{*}L3{*}{color} |



h3. Automated Detection

TODO



h3. Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the [CERT website|https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON32-J].

h2. References

\[[API 06|AA. Java References#API 06]\] {{java.util.concurrent.locks.Condition}} interface
\[[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

----
[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!|CON18-J. Always invoke wait() and await() methods inside a loop]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!|11. Concurrency (CON)]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!|CON20-J. Do not perform operations that may block while holding a lock]

(int i = MAX_STEPS - 1; i >= 0; i--) {
      ProcessStep ps = new ProcessStep(i);
      new Thread(ps).start();
    }
  }
}