Branch data     Line data    Source code

       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                 :            : 
      38                 :            : struct 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                 :            : 
      48                 :            : static inline void wake_q_init(struct wake_q_head *head)
      49                 :            : {
      50                 :          3 :         head->first = WAKE_Q_TAIL;
      51                 :          3 :         head->lastp = &head->first;
      52                 :            : }
      53                 :            : 
      54                 :            : static inline bool wake_q_empty(struct wake_q_head *head)
      55                 :            : {
      56                 :          3 :         return head->first == WAKE_Q_TAIL;
      57                 :            : }
      58                 :            : 
      59                 :            : extern void wake_q_add(struct wake_q_head *head, struct task_struct *task);
      60                 :            : extern void wake_q_add_safe(struct wake_q_head *head, struct task_struct *task);
      61                 :            : extern void wake_up_q(struct wake_q_head *head);
      62                 :            : 
      63                 :            : #endif /* _LINUX_SCHED_WAKE_Q_H */