Wait Queues¶

Purpose¶

Wait queues allow a driver to put a process to sleep until a condition becomes true.

Common APIs¶

init_waitqueue_head(&dev->wq);
wait_event_interruptible(dev->wq, condition);
wake_up_interruptible(&dev->wq);

Internal Flow¶

The driver-facing APIs:

wait_event_interruptible(...)
wake_up_interruptible(...)

are built on top of the kernel wait queue infrastructure.

The waiting path is conceptually:

wait_event_interruptible()
        ↓
prepare_to_wait()
        ↓
TASK_INTERRUPTIBLE
        ↓
schedule()
        ↓
Sleep

When an event occurs, the wakeup path becomes:

wake_up_interruptible()
        ↓
TASK_RUNNING
        ↓
Scheduler

finish_wait()
        ↓
Remove from Wait Queue

Wait queues are shared by several kernel mechanisms.

For example, the poll subsystem registers a driver's wait queue through poll_wait(). When the driver later calls wake_up_interruptible(), the poll framework wakes and invokes the driver's .poll callback again to determine the latest readiness state.

Most drivers use the high-level wait queue APIs directly and do not call:

prepare_to_wait(...)
finish_wait(...)

themselves.

Typical Read Path¶

ret = wait_event_interruptible(dev->wq, !queue_empty(dev));
if (ret)
    return ret;

Return Behavior¶

Situation	Typical Result
Condition becomes true	Continue read path
Interrupted by signal	Return error, often `-ERESTARTSYS`
Non-blocking mode	Do not wait; return `-EAGAIN`

Common Pitfalls¶

Warning

The wakeup function only wakes sleeping tasks. The waiting condition must still become true.

Warning

Always check the condition after wakeup.