1 /* SPDX-License-Identifier: GPL-2.0 */
5  * Linux wait queue related types and methods
26  * A single wait-queue entry structure:
82 	wq_entry->flags		= 0;  in init_waitqueue_entry()
83 	wq_entry->private	= p;  in init_waitqueue_entry()
84 	wq_entry->func		= default_wake_function;  in init_waitqueue_entry()
90 	wq_entry->flags		= 0;  in init_waitqueue_func_entry()
91 	wq_entry->private	= NULL;  in init_waitqueue_func_entry()
92 	wq_entry->func		= func;  in init_waitqueue_func_entry()
96  * waitqueue_active -- locklessly test for waiters on the queue
99  * returns true if the wait list is not empty
102  * lead to sporadic and non-obvious failure.
107  *      CPU0 - waker                    CPU1 - waiter
110  *      @cond = true;                     prepare_to_wait(&wq_head, &wait, state);
116  *                                      finish_wait(&wq_head, &wait);
120  * observe an empty wait list while the waiter might not observe @cond.
127 	return !list_empty(&wq_head->head);  in waitqueue_active()
131  * wq_has_single_sleeper - check if there is only one sleeper
132  * @wq_head: wait queue head
140 	return list_is_singular(&wq_head->head);  in wq_has_single_sleeper()
144  * wq_has_sleeper - check if there are any waiting processes
145  * @wq_head: wait queue head
155 	 * add_wait_queue modifications to the wait queue.  in wq_has_sleeper()
173 	struct list_head *head = &wq_head->head;  in __add_wait_queue()
176 	list_for_each_entry(wq, &wq_head->head, entry) {  in __add_wait_queue()
177 		if (!(wq->flags & WQ_FLAG_PRIORITY))  in __add_wait_queue()
179 		head = &wq->entry;  in __add_wait_queue()
181 	list_add(&wq_entry->entry, head);  in __add_wait_queue()
185  * Used for wake-one threads:
190 	wq_entry->flags |= WQ_FLAG_EXCLUSIVE;  in __add_wait_queue_exclusive()
196 	list_add_tail(&wq_entry->entry, &wq_head->head);  in __add_wait_queue_entry_tail()
202 	wq_entry->flags |= WQ_FLAG_EXCLUSIVE;  in __add_wait_queue_entry_tail_exclusive()
209 	list_del(&wq_entry->entry);  in __remove_wait_queue()
252  * wake_up_pollfree - signal that a polled waitqueue is going away
253  * @wq_head: the wait queue head
255  * In the very rare cases where a ->poll() implementation uses a waitqueue whose
258  * non-blocking polls (e.g. epoll) are notified that the queue is going away.
260  * The caller must also RCU-delay the freeing of the wait_queue_head, e.g. via
266 	 * For performance reasons, we don't always take the queue lock here.  in wake_up_pollfree()
268 	 * the queue, and proceed while they still hold the queue lock.  in wake_up_pollfree()
270 	 * can safely proceed with an RCU-delayed free.  in wake_up_pollfree()
334  * wait_event - sleep until a condition gets true
335  * @wq_head: the waitqueue to wait on
336  * @condition: a C expression for the event to wait for
343  * change the result of the wait condition.
358  * io_wait_event() -- like wait_event() but with io_schedule()
373  * wait_event_freezable - sleep (or freeze) until a condition gets true
374  * @wq_head: the waitqueue to wait on
375  * @condition: a C expression for the event to wait for
377  * The process is put to sleep (TASK_INTERRUPTIBLE -- so as not to contribute
382  * change the result of the wait condition.
399  * wait_event_timeout - sleep until a condition gets true or a timeout elapses
400  * @wq_head: the waitqueue to wait on
401  * @condition: a C expression for the event to wait for
409  * change the result of the wait condition.
432  * like wait_event_timeout() -- except it uses TASK_INTERRUPTIBLE to avoid
462  * wait_event_cmd - sleep until a condition gets true
463  * @wq_head: the waitqueue to wait on
464  * @condition: a C expression for the event to wait for
473  * change the result of the wait condition.
487  * wait_event_interruptible - sleep until a condition gets true
488  * @wq_head: the waitqueue to wait on
489  * @condition: a C expression for the event to wait for
496  * change the result of the wait condition.
498  * The function will return -ERESTARTSYS if it was interrupted by a
516  * wait_event_interruptible_timeout - sleep until a condition gets true or a timeout elapses
517  * @wq_head: the waitqueue to wait on
518  * @condition: a C expression for the event to wait for
526  * change the result of the wait condition.
532  * to %true before the @timeout elapsed, or -%ERESTARTSYS if it was
554 					current->timer_slack_ns);		\
560 			__ret = -ETIME;						\
571  * wait_event_hrtimeout - sleep until a condition gets true or a timeout elapses
572  * @wq_head: the waitqueue to wait on
573  * @condition: a C expression for the event to wait for
581  * change the result of the wait condition.
583  * The function returns 0 if @condition became true, or -ETIME if the timeout
597  * wait_event_interruptible_hrtimeout - sleep until a condition gets true or a timeout elapses
598  * @wq: the waitqueue to wait on
599  * @condition: a C expression for the event to wait for
607  * change the result of the wait condition.
609  * The function returns 0 if @condition became true, -ERESTARTSYS if it was
610  * interrupted by a signal, or -ETIME if the timeout elapsed.
663  * wait_event_idle - wait for a condition without contributing to system load
664  * @wq_head: the waitqueue to wait on
665  * @condition: a C expression for the event to wait for
672  * change the result of the wait condition.
683  * wait_event_idle_exclusive - wait for a condition with contributing to system load
684  * @wq_head: the waitqueue to wait on
685  * @condition: a C expression for the event to wait for
691  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
692  * set thus if other processes wait on the same list, when this
696  * change the result of the wait condition.
712  * wait_event_idle_timeout - sleep without load until a condition becomes true or a timeout elapses
713  * @wq_head: the waitqueue to wait on
714  * @condition: a C expression for the event to wait for
722  * change the result of the wait condition.
745 …* wait_event_idle_exclusive_timeout - sleep without load until a condition becomes true or a timeo…
746  * @wq_head: the waitqueue to wait on
747  * @condition: a C expression for the event to wait for
754  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
755  * set thus if other processes wait on the same list, when this
759  * change the result of the wait condition.
797  * wait_event_interruptible_locked - sleep until a condition gets true
798  * @wq: the waitqueue to wait on
799  * @condition: a C expression for the event to wait for
814  * change the result of the wait condition.
816  * The function will return -ERESTARTSYS if it was interrupted by a
824  * wait_event_interruptible_locked_irq - sleep until a condition gets true
825  * @wq: the waitqueue to wait on
826  * @condition: a C expression for the event to wait for
841  * change the result of the wait condition.
843  * The function will return -ERESTARTSYS if it was interrupted by a
851  * wait_event_interruptible_exclusive_locked - sleep exclusively until a condition gets true
852  * @wq: the waitqueue to wait on
853  * @condition: a C expression for the event to wait for
867  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
872  * change the result of the wait condition.
874  * The function will return -ERESTARTSYS if it was interrupted by a
882  * wait_event_interruptible_exclusive_locked_irq - sleep until a condition gets true
883  * @wq: the waitqueue to wait on
884  * @condition: a C expression for the event to wait for
898  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
903  * change the result of the wait condition.
905  * The function will return -ERESTARTSYS if it was interrupted by a
917  * wait_event_killable - sleep until a condition gets true
918  * @wq_head: the waitqueue to wait on
919  * @condition: a C expression for the event to wait for
926  * change the result of the wait condition.
928  * The function will return -ERESTARTSYS if it was interrupted by a
944  * wait_event_state - sleep until a condition gets true
945  * @wq_head: the waitqueue to wait on
946  * @condition: a C expression for the event to wait for
954  * change the result of the wait condition.
956  * The function will return -ERESTARTSYS if it was interrupted by a signal
986  * wait_event_killable_timeout - sleep until a condition gets true or a timeout elapses
987  * @wq_head: the waitqueue to wait on
988  * @condition: a C expression for the event to wait for
996  * change the result of the wait condition.
1002  * to %true before the @timeout elapsed, or -%ERESTARTSYS if it was
1026  * wait_event_lock_irq_cmd - sleep until a condition gets true. The
1030  * @wq_head: the waitqueue to wait on
1031  * @condition: a C expression for the event to wait for
1042  * change the result of the wait condition.
1056  * wait_event_lock_irq - sleep until a condition gets true. The
1060  * @wq_head: the waitqueue to wait on
1061  * @condition: a C expression for the event to wait for
1070  * change the result of the wait condition.
1091  * wait_event_interruptible_lock_irq_cmd - sleep until a condition gets true.
1094  * @wq_head: the waitqueue to wait on
1095  * @condition: a C expression for the event to wait for
1106  * change the result of the wait condition.
1112  * The macro will return -ERESTARTSYS if it was interrupted by a signal
1125  * wait_event_interruptible_lock_irq - sleep until a condition gets true.
1128  * @wq_head: the waitqueue to wait on
1129  * @condition: a C expression for the event to wait for
1138  * change the result of the wait condition.
1143  * The macro will return -ERESTARTSYS if it was interrupted by a signal
1163  * wait_event_interruptible_lock_irq_timeout - sleep until a condition gets
1166  * @wq_head: the waitqueue to wait on
1167  * @condition: a C expression for the event to wait for
1177  * change the result of the wait condition.
1182  * The function returns 0 if the @timeout elapsed, -ERESTARTSYS if it
1227 #define init_wait_func(wait, function)						\  argument
1229 		(wait)->private = current;					\
1230 		(wait)->func = function;					\
1231 		INIT_LIST_HEAD(&(wait)->entry);					\
1232 		(wait)->flags = 0;						\
1235 #define init_wait(wait)	init_wait_func(wait, autoremove_wake_function)  argument