linux/sched/wake_q.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_SCHED_WAKE_Q_H
0003 #define _LINUX_SCHED_WAKE_Q_H
0004
0005 /*
0006  * Wake-queues are lists of tasks with a pending wakeup, whose
0007  * callers have already marked the task as woken internally,
0008  * and can thus carry on. A common use case is being able to
0009  * do the wakeups once the corresponding user lock as been
0010  * released.
0011  *
0012  * We hold reference to each task in the list across the wakeup,
0013  * thus guaranteeing that the memory is still valid by the time
0014  * the actual wakeups are performed in wake_up_q().
0015  *
0016  * One per task suffices, because there's never a need for a task to be
0017  * in two wake queues simultaneously; it is forbidden to abandon a task
0018  * in a wake queue (a call to wake_up_q() _must_ follow), so if a task is
0019  * already in a wake queue, the wakeup will happen soon and the second
0020  * waker can just skip it.
0021  *
0022  * The DEFINE_WAKE_Q macro declares and initializes the list head.
0023  * wake_up_q() does NOT reinitialize the list; it's expected to be
0024  * called near the end of a function. Otherwise, the list can be
0025  * re-initialized for later re-use by wake_q_init().
0026  *
0027  * NOTE that this can cause spurious wakeups. schedule() callers
0028  * must ensure the call is done inside a loop, confirming that the
0029  * wakeup condition has in fact occurred.
0030  *
0031  * NOTE that there is no guarantee the wakeup will happen any later than the
0032  * wake_q_add() location. Therefore task must be ready to be woken at the
0033  * location of the wake_q_add().
0034  */
0035
0036 #include <linux/sched.h>
0037
0038 struct wake_q_head {
0039     struct wake_q_node *first;
0040     struct wake_q_node **lastp;
0041 };
0042
0043 #define WAKE_Q_TAIL ((struct wake_q_node *) 0x01)
0044
0045 #define WAKE_Q_HEAD_INITIALIZER(name)               \
0046     { WAKE_Q_TAIL, &name.first }
0047
0048 #define DEFINE_WAKE_Q(name)                 \
0049     struct wake_q_head name = WAKE_Q_HEAD_INITIALIZER(name)
0050
0051 static inline void wake_q_init(struct wake_q_head *head)
0052 {
0053     head->first = WAKE_Q_TAIL;
0054     head->lastp = &head->first;
0055 }
0056
0057 static inline bool wake_q_empty(struct wake_q_head *head)
0058 {
0059     return head->first == WAKE_Q_TAIL;
0060 }
0061
0062 extern void wake_q_add(struct wake_q_head *head, struct task_struct *task);
0063 extern void wake_q_add_safe(struct wake_q_head *head, struct task_struct *task);
0064 extern void wake_up_q(struct wake_q_head *head);
0065
0066 #endif /* _LINUX_SCHED_WAKE_Q_H */