Contribution description

Note: This PR builds on top of #21254

From core/include/wait_queue.h:

This API is a thin wrapper around thread flags group and requires
"core_thread_flags_group" to be enabled in USEMODULE.

Wait queues enable lock-free, IRQ-safe condition signaling. This API is
inspired from the Linux Kernel.

Wait queues have similar semantics to condition variables, but don't require
setting the condition + signaling to be atomic, hence no mutex is needed to
function properly. In turn, one may safely call queue_wake() from an ISR.
Note, while cond_signal() and cond_broadcast() are safe to call from an ISR
context too, doing so will probably cause a race condition elsewhere.
Consider the following scenario using condition variables:

static uint64_t measurement;
mutex_t cond_lock = MUTEX_INIT;
cond_t cond = COND_INIT;

void measurement_irq(void)
{
    measurement = measure();
    cond_broadcast(&cond);
}

void wait_for_critical_value(void)
{
    mutex_lock(&cond_lock);
    while (atomic_load_u64(&measurement) < THRESHOLD) {
        cond_wait(&cond, cond_lock);
    }
    mutex_unlock(&cond_lock);
}

Note, the mutex is there only for the cond_wait() API call, as we're not
allowed to call mutex_lock() inside the ISR. This alone is a hint that
something isn't right and indeed, the following sequence of events is
possible:

1. thread sees measurement < THRESHOLD, and is about to call cond_wait()
2. ISR fires, sets measurement = THRESHOLD and signals the condition
3. thread calls cond_wait() and goes to sleep, possibly forever

Using a wait queue, we can do this:

static uint64_t measurement;
wq_t wq = WAIT_QUEUE_INIT;

void measurement_irq(void)
{
    measurement = measure();
    queue_wake_all(&wq);
}

void wait_for_critical_value(void)
{
   wait_queue_join(&wq);
   while (atomic_load_u64(&measurement) < THRESHOLD) {
       queue_wait(&wq);
   }
   wait_queue_leave(&wq);
}

This is free of the race condition above because if the ISR fires between
the condition check and the queue_wait() call, queue_wait() will return
because the THREAD_FLAG_WAIT_QUEUE thread flag used in the
implementation must also have been set. In other words, if the condition is
true, then the thread flag is also set.

If you have a simple condition check expression, the waiter boiler plate
code can be eliminated by using the QUEUE_WAIT() macro, which combines
the join, wait, and leave operations:

void wait_for_critical_value(void)
{
    QUEUE_WAIT(&wq, atomic_load_u64(&measurement) >= THRESHOLD);
}

If you don't want to wait indefinitely, you can do it with a timeout:

void wait_for_critical_value(void)
{
    if (QUEUE_WAIT_ZTIMER(ZTIMER_MSEC, 10, &wq, atomic_load_u64(&measurement) >= THRESHOLD)) {
        puts("condition met!");
    }
    else {
        puts("timeout!");
    }
}

Limitations

Be aware that the condition checking is fenced but not atomic w.r. to
signaling, so you have to ensure that by other means. E.g. in the example
code above this is enforced by atomic_load_u64().

When to use?

If you know for sure you're synchronizing between threads only (no ISR),
then the condition variable has the advantage of implicit condition
setting/checking atomicity through the mutex. Otherwise go for the wait
queue, as it's more flexible by allowing the waker to be in ISR context.

Testing procedure

Run the test application on:

• native
• samd20-xpro

Issues/PRs references

• depends on core/thread_flags: add thread flags group #21254
• this is an alternative implementation for core/sync: add wait queues #21123 based on thread flags group