The difference between wait_queue_head and wait_queue in linux kernel

Question

I can find many examples regarding wait_queue_head. It works as a signal, create a wait_queue_head, someone can sleep using it until someother kicks it up.

But I can not find a good example of using wait_queue itself, supposedly very related to it.

Could someone gives example, or under the hood of them?

Answer 1

Wait queue is simply a list of processes and a lock.

wait_queue_head_t represents the queue as a whole. It is the head of the waiting queue.

wait_queue_t represents the item of the list - a single process waiting in the queue.

Answer 2

From Linux Device Drivers:

The wait_queue_head_t type is a fairly simple structure, defined in <linux/wait.h>. It contains only a lock variable and a linked list of sleeping processes. The individual data items in the list are of type wait_queue_t, and the list is the generic list defined in <linux/list.h>.

Normally the wait_queue_t structures are allocated on the stack by functions like interruptible_sleep_on; the structures end up in the stack because they are simply declared as automatic variables in the relevant functions. In general, the programmer need not deal with them.

Take a look at A Deeper Look at Wait Queues part.

Some advanced applications, however, can require dealing with wait_queue_t variables directly. For these, it's worth a quick look at what actually goes on inside a function like interruptible_sleep_on. The following is a simplified version of the implementation of interruptible_sleep_on to put a process to sleep:

 void simplified_sleep_on(wait_queue_head_t *queue)
 {
   wait_queue_t wait;

   init_waitqueue_entry(&wait, current);
   current->state = TASK_INTERRUPTIBLE;

   add_wait_queue(queue, &wait);
   schedule();
   remove_wait_queue (queue, &wait);
  }

The code here creates a new wait_queue_t variable (wait, which gets allocated on the stack) and initializes it. The state of the task is set to TASK_INTERRUPTIBLE, meaning that it is in an interruptible sleep. The wait queue entry is then added to the queue (the wait_queue_head_t * argument). Then schedule is called, which relinquishes the processor to somebody else. schedule returns only when somebody else has woken up the process and set its state to TASK_RUNNING. At that point, the wait queue entry is removed from the queue, and the sleep is done

The internals of the data structures involved in wait queues:

Update: for the users who think the image is my own - here is one more time the link to the Linux Device Drivers where the image is taken from