Page History

Functions that can fail spuriously should be wrapped in a loop.  For example:

atomic_compare_exchange_weak() and atomic_compare_exchange_weak_explicit()

The atomic_compare_exchange_weak() and atomic_compare_exchange_weak_explicit() functions both attempt to set an atomic variable to a new value but only if it currently possesses a known old value. Unlike the related functions atomic_compare_exchange_strong() and atomic_compare_exchange_strong_explicit(), these functions are permitted to "fail spuriously," which makes them faster on some platforms. The C Standard describes this behavior in subclause 7.17.7.4, paragraph 4:

A weak compare-and-exchange operation may fail spuriously. That is, even when the contents of memory referred to by expected and object are equal, it may return zero and store back to expected the same memory contents that were originally there.

And provides an example in paragraph 6 of the same subclause:

EXAMPLE  A consequence of spurious failure is that nearly all uses of weak compare-and-exchange will be in a loop.

exp = atomic_load(&cur);
do {
      des = function(exp);
} while (!atomic_compare_exchange_weak(&cur, &exp, des));

When a compare-and-exchange is in a loop, the weak version will yield better performance on some platforms. When a weak compare-and-exchange would require a loop and a strong one would not, the strong one is preferable.

cnd_wait() and cnd_timedwait()

The cnd_wait() and cnd_timedwait() functions temporarily cede possession of a mutex so that other threads that may be requesting the mutex can proceed. These functions must always be called from code that is protected by a lock. The waiting thread resumes execution only after it has been notified, generally as the result of the invocation of the cnd_signal() or cnd_broadcast() function invoked by another thread. The cnd_wait() function must be invoked from a loop that checks whether a condition predicate holds. A condition predicate is an expression constructed from the variables of a function that must be true for a thread to be allowed to continue execution. The thread pauses execution, via cnd_wait(), cnd_timedwait(), or some other mechanism, and is resumed later, presumably when the condition predicate is true and the thread is notified.

#include <threads.h>
#include <stdbool.h>
 
extern bool until_finish(void);
extern mtx_t lock;
extern cnd_t condition;
 
if (thrd_success != mtx_lock(&lock)) {
  /* Handle error */
}

while (until_finish()) {  /* Predicate does not hold */
  if (thrd_success != cnd_wait(&condition, &lock)) {
    /* Handle error */
  }
}
 
/* Resume when condition holds */

if (thrd_success != mtx_unlock(&lock)) {
  /* Handle error */
}

Both safety and liveness are concerns when using conditions. The safety property requires that all objects maintain consistent states in a multithreaded environment [Lea 2000]. The liveness property requires that every operation or function invocation execute to completion without interruption.

To guarantee liveness, programs must test the while loop condition before invoking the cnd_wait() function. This early test checks whether another thread has already satisfied the condition predicate and sent a notification. Invoking the cnd_wait() function after the notification has been sent results in indefinite blocking.

To guarantee safety, programs must test the while loop condition after returning from the cnd_wait() function. Although cnd_wait() is intended to block indefinitely until a notification is received, it must still be encased within a loop to prevent the following vulnerabilities [Bloch 2001]:

• Thread in the middle: A third thread can acquire the lock on the shared object during the interval between a notification being sent and the receiving thread resuming execution. This third thread can change the state of the object, leaving it inconsistent. This is a TOCTOU race condition.
• Malicious notification: A random or malicious notification can be received when the condition predicate is false. Such a notification would cancel the cnd_wait().
• Misdelivered notification: The order in which threads execute after receipt of a cnd_broadcast() signal is unspecified. Consequently, an unrelated thread could start executing and discover that its condition predicate is satisfied. Consequently, it could resume execution, although it was required to remain dormant.

For these reasons, programs must check the condition predicate after the cnd_wait() function returns. A while loop is the best choice for checking the condition predicate both before and after invoking cnd_aitwait().

Noncompliant Code Example

This noncompliant code example monitors a linked list and assigns one thread to consume list elements when the list is nonempty. 

This thread pauses execution using cnd_wait() and resumes when notified, presumably when the list has elements to be consumed. It is possible for the thread to be notified even if the list is still empty, perhaps because the notifying thread used cnd_broadcast(), which notifies all threads. This is usually preferred; see CON38-C. Notify all threads waiting on a condition variable for more information.

Note that a condition predicate is typically the negation of the condition expression in the loop. In this noncompliant code example, the condition predicate for removing an element from a linked list is (list->next != NULL), whereas the condition expression for the while loop condition is (list->next == NULL).

Unfortunately, this noncompliant code example nests the cnd_wait() function inside a traditional if block and thus fails to check the condition predicate after the notification is received. If the notification was spurious or malicious, the thread would wake up prematurely.

#include <threads.h>
 
struct node_t {
 void* node;
 struct node_t* next;
};
 
struct node_t list;
static mtx_t lock;
static cnd_t condition;
 
void consume_list_element(void) {
  if (thrd_success != mtx_lock(&lock)) {
    /* Handle error */
  }
 
  if (list.next == NULL) {
    if (thrd_success != cnd_wait(&condition, &lock)) {
      /* Handle error */
    }
  }

 /* Proceed when condition holds */

  if (thrd_success != mtx_unlock(&lock)) {
    /* Handle error */
  }
}

Compliant Solution

This compliant solution calls the cnd_wait() function from within a while loop to check the condition both before and after the call to cnd_wait().

#include <threads.h>
 
struct node_t {
 void* node;
 struct node_t* next;
};
 
struct node_t list;
static mtx_t lock;
static cnd_t condition;
 
void consume_list_element(void) {
  if (thrd_success != mtx_lock(&lock)) {
    /* Handle error */
  }
 
  while (list.next == NULL) {
    if (thrd_success != cnd_wait(&condition, &lock)) {
      /* Handle error */
    }
  }

 /* Proceed when condition holds */

  if (thrd_success != mtx_unlock(&lock)) {
    /* Handle error */
  }
}

Failure to encase the cnd_wait() or cnd_timedwait() functions inside a while loop can lead to indefinite blocking and denial of service (DoS).

Related Guidelines

Bibliography