include/linux/sched/wake_q.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_SCHED_WAKE_Q_H
   3 #define _LINUX_SCHED_WAKE_Q_H
   4
   5 /*
   6  * Wake-queues are lists of tasks with a pending wakeup, whose
   7  * callers have already marked the task as woken internally,
   8  * and can thus carry on. A common use case is being able to
   9  * do the wakeups once the corresponding user lock as been
  10  * released.
  11  *
  12  * We hold reference to each task in the list across the wakeup,
  13  * thus guaranteeing that the memory is still valid by the time
  14  * the actual wakeups are performed in wake_up_q().
  15  *
  16  * One per task suffices, because there's never a need for a task to be
  17  * in two wake queues simultaneously; it is forbidden to abandon a task
  18  * in a wake queue (a call to wake_up_q() _must_ follow), so if a task is
  19  * already in a wake queue, the wakeup will happen soon and the second
  20  * waker can just skip it.
  21  *
  22  * The DEFINE_WAKE_Q macro declares and initializes the list head.
  23  * wake_up_q() does NOT reinitialize the list; it's expected to be
  24  * called near the end of a function. Otherwise, the list can be
  25  * re-initialized for later re-use by wake_q_init().
  26  *
  27  * Note that this can cause spurious wakeups. schedule() callers
  28  * must ensure the call is done inside a loop, confirming that the
  29  * wakeup condition has in fact occurred.
  30  */
  31
  32 #include <linux/sched.h>
  33
  34 struct wake_q_head {
  35         struct wake_q_node *first;
  36         struct wake_q_node **lastp;
  37 };
  38
  39 #define WAKE_Q_TAIL ((struct wake_q_node *) 0x01)
  40
  41 #define DEFINE_WAKE_Q(name)                             \
  42         struct wake_q_head name = { WAKE_Q_TAIL, &name.first }
  43
  44 static inline void wake_q_init(struct wake_q_head *head)
  45 {
  46         head->first = WAKE_Q_TAIL;
  47         head->lastp = &head->first;
  48 }
  49
  50 extern void wake_q_add(struct wake_q_head *head,
  51                        struct task_struct *task);
  52 extern void wake_up_q(struct wake_q_head *head);
  53
  54 #endif /* _LINUX_SCHED_WAKE_Q_H */