LXR linux/include/linux/sched/wake

   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 * NOTE that there is no guarantee the wakeup will happen any later than the
  32 * wake_q_add() location. Therefore task must be ready to be woken at the
  33 * location of the wake_q_add().
  34 */
  35
  36#include <linux/sched.h>
  37
  38struct wake_q_head {
  39        struct wake_q_node *first;
  40        struct wake_q_node **lastp;
  41};
  42
  43#define WAKE_Q_TAIL ((struct wake_q_node *) 0x01)
  44
  45#define DEFINE_WAKE_Q(name)                             \
  46        struct wake_q_head name = { WAKE_Q_TAIL, &name.first }
  47
  48static inline void wake_q_init(struct wake_q_head *head)
  49{
  50        head->first = WAKE_Q_TAIL;
  51        head->lastp = &head->first;
  52}
  53
  54static inline bool wake_q_empty(struct wake_q_head *head)
  55{
  56        return head->first == WAKE_Q_TAIL;
  57}
  58
  59extern void wake_q_add(struct wake_q_head *head, struct task_struct *task);
  60extern void wake_q_add_safe(struct wake_q_head *head, struct task_struct *task);
  61extern void wake_up_q(struct wake_q_head *head);
  62
  63#endif /* _LINUX_SCHED_WAKE_Q_H */
  64