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()
171 	struct list_head *head = &wq_head->head;  in __add_wait_queue()
174 	list_for_each_entry(wq, &wq_head->head, entry) {  in __add_wait_queue()
175 		if (!(wq->flags & WQ_FLAG_PRIORITY))  in __add_wait_queue()
177 		head = &wq->entry;  in __add_wait_queue()
179 	list_add(&wq_entry->entry, head);  in __add_wait_queue()
183  * Used for wake-one threads:
188 	wq_entry->flags |= WQ_FLAG_EXCLUSIVE;  in __add_wait_queue_exclusive()
194 	list_add_tail(&wq_entry->entry, &wq_head->head);  in __add_wait_queue_entry_tail()
200 	wq_entry->flags |= WQ_FLAG_EXCLUSIVE;  in __add_wait_queue_entry_tail_exclusive()
207 	list_del(&wq_entry->entry);  in __remove_wait_queue()
250  * wake_up_pollfree - signal that a polled waitqueue is going away
251  * @wq_head: the wait queue head
253  * In the very rare cases where a ->poll() implementation uses a waitqueue whose
256  * non-blocking polls (e.g. epoll) are notified that the queue is going away.
258  * The caller must also RCU-delay the freeing of the wait_queue_head, e.g. via
268 	 * can safely proceed with an RCU-delayed free.  in wake_up_pollfree()
282 #define ___wait_is_interruptible(state)						\  argument
283 	(!__builtin_constant_p(state) ||					\
284 	 (state & (TASK_INTERRUPTIBLE | TASK_WAKEKILL)))
300 #define ___wait_event(wq_head, condition, state, exclusive, ret, cmd)		\  argument
308 		long __int = prepare_to_wait_event(&wq_head, &__wq_entry, state);\
313 		if (___wait_is_interruptible(state) && __int) {			\
332  * wait_event - sleep until a condition gets true
333  * @wq_head: the waitqueue to wait on
334  * @condition: a C expression for the event to wait for
341  * change the result of the wait condition.
356  * io_wait_event() -- like wait_event() but with io_schedule()
371  * wait_event_freezable - sleep (or freeze) until a condition gets true
372  * @wq_head: the waitqueue to wait on
373  * @condition: a C expression for the event to wait for
375  * The process is put to sleep (TASK_INTERRUPTIBLE -- so as not to contribute
380  * change the result of the wait condition.
397  * wait_event_timeout - sleep until a condition gets true or a timeout elapses
398  * @wq_head: the waitqueue to wait on
399  * @condition: a C expression for the event to wait for
407  * change the result of the wait condition.
430  * like wait_event_timeout() -- except it uses TASK_INTERRUPTIBLE to avoid
460  * wait_event_cmd - sleep until a condition gets true
461  * @wq_head: the waitqueue to wait on
462  * @condition: a C expression for the event to wait for
471  * change the result of the wait condition.
485  * wait_event_interruptible - sleep until a condition gets true
486  * @wq_head: the waitqueue to wait on
487  * @condition: a C expression for the event to wait for
494  * change the result of the wait condition.
496  * The function will return -ERESTARTSYS if it was interrupted by a
514  * wait_event_interruptible_timeout - sleep until a condition gets true or a timeout elapses
515  * @wq_head: the waitqueue to wait on
516  * @condition: a C expression for the event to wait for
524  * change the result of the wait condition.
530  * to %true before the @timeout elapsed, or -%ERESTARTSYS if it was
543 #define __wait_event_hrtimeout(wq_head, condition, timeout, state)		\  argument
552 					current->timer_slack_ns);		\
556 	__ret = ___wait_event(wq_head, condition, state, 0, 0,			\
558 			__ret = -ETIME;						\
569  * wait_event_hrtimeout - sleep until a condition gets true or a timeout elapses
570  * @wq_head: the waitqueue to wait on
571  * @condition: a C expression for the event to wait for
579  * change the result of the wait condition.
581  * The function returns 0 if @condition became true, or -ETIME if the timeout
595  * wait_event_interruptible_hrtimeout - sleep until a condition gets true or a timeout elapses
596  * @wq: the waitqueue to wait on
597  * @condition: a C expression for the event to wait for
605  * change the result of the wait condition.
607  * The function returns 0 if @condition became true, -ERESTARTSYS if it was
608  * interrupted by a signal, or -ETIME if the timeout elapsed.
661  * wait_event_idle - wait for a condition without contributing to system load
662  * @wq_head: the waitqueue to wait on
663  * @condition: a C expression for the event to wait for
670  * change the result of the wait condition.
681  * wait_event_idle_exclusive - wait for a condition with contributing to system load
682  * @wq_head: the waitqueue to wait on
683  * @condition: a C expression for the event to wait for
689  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
690  * set thus if other processes wait on the same list, when this
694  * change the result of the wait condition.
710  * wait_event_idle_timeout - sleep without load until a condition becomes true or a timeout elapses
711  * @wq_head: the waitqueue to wait on
712  * @condition: a C expression for the event to wait for
720  * change the result of the wait condition.
743 …* wait_event_idle_exclusive_timeout - sleep without load until a condition becomes true or a timeo…
744  * @wq_head: the waitqueue to wait on
745  * @condition: a C expression for the event to wait for
752  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
753  * set thus if other processes wait on the same list, when this
757  * change the result of the wait condition.
795  * wait_event_interruptible_locked - sleep until a condition gets true
796  * @wq: the waitqueue to wait on
797  * @condition: a C expression for the event to wait for
812  * change the result of the wait condition.
814  * The function will return -ERESTARTSYS if it was interrupted by a
822  * wait_event_interruptible_locked_irq - sleep until a condition gets true
823  * @wq: the waitqueue to wait on
824  * @condition: a C expression for the event to wait for
839  * change the result of the wait condition.
841  * The function will return -ERESTARTSYS if it was interrupted by a
849  * wait_event_interruptible_exclusive_locked - sleep exclusively until a condition gets true
850  * @wq: the waitqueue to wait on
851  * @condition: a C expression for the event to wait for
865  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
870  * change the result of the wait condition.
872  * The function will return -ERESTARTSYS if it was interrupted by a
880  * wait_event_interruptible_exclusive_locked_irq - sleep until a condition gets true
881  * @wq: the waitqueue to wait on
882  * @condition: a C expression for the event to wait for
896  * The process is put on the wait queue with an WQ_FLAG_EXCLUSIVE flag
901  * change the result of the wait condition.
903  * The function will return -ERESTARTSYS if it was interrupted by a
915  * wait_event_killable - sleep until a condition gets true
916  * @wq_head: the waitqueue to wait on
917  * @condition: a C expression for the event to wait for
924  * change the result of the wait condition.
926  * The function will return -ERESTARTSYS if it was interrupted by a
938 #define __wait_event_state(wq, condition, state)				\  argument
939 	___wait_event(wq, condition, state, 0, 0, schedule())
942  * wait_event_state - sleep until a condition gets true
943  * @wq_head: the waitqueue to wait on
944  * @condition: a C expression for the event to wait for
945  * @state: state to sleep in
947  * The process is put to sleep (@state) until the @condition evaluates to true
948  * or a signal is received (when allowed by @state).  The @condition is checked
952  * change the result of the wait condition.
954  * The function will return -ERESTARTSYS if it was interrupted by a signal
955  * (when allowed by @state) and 0 if @condition evaluated to true.
957 #define wait_event_state(wq_head, condition, state)				\  argument
962 		__ret = __wait_event_state(wq_head, condition, state);		\
972  * wait_event_killable_timeout - sleep until a condition gets true or a timeout elapses
973  * @wq_head: the waitqueue to wait on
974  * @condition: a C expression for the event to wait for
982  * change the result of the wait condition.
988  * to %true before the @timeout elapsed, or -%ERESTARTSYS if it was
1012  * wait_event_lock_irq_cmd - sleep until a condition gets true. The
1016  * @wq_head: the waitqueue to wait on
1017  * @condition: a C expression for the event to wait for
1028  * change the result of the wait condition.
1042  * wait_event_lock_irq - sleep until a condition gets true. The
1046  * @wq_head: the waitqueue to wait on
1047  * @condition: a C expression for the event to wait for
1056  * change the result of the wait condition.
1077  * wait_event_interruptible_lock_irq_cmd - sleep until a condition gets true.
1080  * @wq_head: the waitqueue to wait on
1081  * @condition: a C expression for the event to wait for
1092  * change the result of the wait condition.
1098  * The macro will return -ERESTARTSYS if it was interrupted by a signal
1111  * wait_event_interruptible_lock_irq - sleep until a condition gets true.
1114  * @wq_head: the waitqueue to wait on
1115  * @condition: a C expression for the event to wait for
1124  * change the result of the wait condition.
1129  * The macro will return -ERESTARTSYS if it was interrupted by a signal
1141 #define __wait_event_lock_irq_timeout(wq_head, condition, lock, timeout, state)	\  argument
1143 		      state, 0, timeout,					\
1149  * wait_event_interruptible_lock_irq_timeout - sleep until a condition gets
1152  * @wq_head: the waitqueue to wait on
1153  * @condition: a C expression for the event to wait for
1163  * change the result of the wait condition.
1168  * The function returns 0 if the @timeout elapsed, -ERESTARTSYS if it
1196 void prepare_to_wait(struct wait_queue_head *wq_head, struct wait_queue_entry *wq_entry, int state);
1197 …e_to_wait_exclusive(struct wait_queue_head *wq_head, struct wait_queue_entry *wq_entry, int state);
1198 …epare_to_wait_event(struct wait_queue_head *wq_head, struct wait_queue_entry *wq_entry, int state);
1213 #define init_wait_func(wait, function)						\  argument
1215 		(wait)->private = current;					\
1216 		(wait)->func = function;					\
1217 		INIT_LIST_HEAD(&(wait)->entry);					\
1218 		(wait)->flags = 0;						\
1221 #define init_wait(wait)	init_wait_func(wait, autoremove_wake_function)  argument