2 * Generic wait-for-completion handler;
4 * It differs from semaphores in that their default case is the opposite,
5 * wait_for_completion default blocks whereas semaphore default non-block. The
6 * interface also makes it easy to 'complete' multiple waiting threads,
7 * something which isn't entirely natural for semaphores.
9 * But more importantly, the primitive documents the usage. Semaphores would
10 * typically be used for exclusion which gives rise to priority inversion.
11 * Waiting for completion is a typically sync point, but not an exclusion point.
14 #include <linux/sched/signal.h>
15 #include <linux/sched/debug.h>
16 #include <linux/completion.h>
19 * complete: - signals a single thread waiting on this completion
20 * @x: holds the state of this particular completion
22 * This will wake up a single thread waiting on this completion. Threads will be
23 * awakened in the same order in which they were queued.
25 * See also complete_all(), wait_for_completion() and related routines.
27 * It may be assumed that this function implies a write memory barrier before
28 * changing the task state if and only if any tasks are woken up.
30 void complete(struct completion
*x
)
34 spin_lock_irqsave(&x
->wait
.lock
, flags
);
35 if (x
->done
!= UINT_MAX
)
37 __wake_up_locked(&x
->wait
, TASK_NORMAL
, 1);
38 spin_unlock_irqrestore(&x
->wait
.lock
, flags
);
40 EXPORT_SYMBOL(complete
);
43 * complete_all: - signals all threads waiting on this completion
44 * @x: holds the state of this particular completion
46 * This will wake up all threads waiting on this particular completion event.
48 * It may be assumed that this function implies a write memory barrier before
49 * changing the task state if and only if any tasks are woken up.
51 void complete_all(struct completion
*x
)
55 spin_lock_irqsave(&x
->wait
.lock
, flags
);
57 __wake_up_locked(&x
->wait
, TASK_NORMAL
, 0);
58 spin_unlock_irqrestore(&x
->wait
.lock
, flags
);
60 EXPORT_SYMBOL(complete_all
);
62 static inline long __sched
63 do_wait_for_common(struct completion
*x
,
64 long (*action
)(long), long timeout
, int state
)
67 DECLARE_WAITQUEUE(wait
, current
);
69 __add_wait_queue_tail_exclusive(&x
->wait
, &wait
);
71 if (signal_pending_state(state
, current
)) {
72 timeout
= -ERESTARTSYS
;
75 __set_current_state(state
);
76 spin_unlock_irq(&x
->wait
.lock
);
77 timeout
= action(timeout
);
78 spin_lock_irq(&x
->wait
.lock
);
79 } while (!x
->done
&& timeout
);
80 __remove_wait_queue(&x
->wait
, &wait
);
84 if (x
->done
!= UINT_MAX
)
89 static inline long __sched
90 __wait_for_common(struct completion
*x
,
91 long (*action
)(long), long timeout
, int state
)
95 spin_lock_irq(&x
->wait
.lock
);
96 timeout
= do_wait_for_common(x
, action
, timeout
, state
);
97 spin_unlock_irq(&x
->wait
.lock
);
102 wait_for_common(struct completion
*x
, long timeout
, int state
)
104 return __wait_for_common(x
, schedule_timeout
, timeout
, state
);
108 wait_for_common_io(struct completion
*x
, long timeout
, int state
)
110 return __wait_for_common(x
, io_schedule_timeout
, timeout
, state
);
114 * wait_for_completion: - waits for completion of a task
115 * @x: holds the state of this particular completion
117 * This waits to be signaled for completion of a specific task. It is NOT
118 * interruptible and there is no timeout.
120 * See also similar routines (i.e. wait_for_completion_timeout()) with timeout
121 * and interrupt capability. Also see complete().
123 void __sched
wait_for_completion(struct completion
*x
)
125 wait_for_common(x
, MAX_SCHEDULE_TIMEOUT
, TASK_UNINTERRUPTIBLE
);
127 EXPORT_SYMBOL(wait_for_completion
);
130 * wait_for_completion_timeout: - waits for completion of a task (w/timeout)
131 * @x: holds the state of this particular completion
132 * @timeout: timeout value in jiffies
134 * This waits for either a completion of a specific task to be signaled or for a
135 * specified timeout to expire. The timeout is in jiffies. It is not
138 * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
139 * till timeout) if completed.
141 unsigned long __sched
142 wait_for_completion_timeout(struct completion
*x
, unsigned long timeout
)
144 return wait_for_common(x
, timeout
, TASK_UNINTERRUPTIBLE
);
146 EXPORT_SYMBOL(wait_for_completion_timeout
);
149 * wait_for_completion_io: - waits for completion of a task
150 * @x: holds the state of this particular completion
152 * This waits to be signaled for completion of a specific task. It is NOT
153 * interruptible and there is no timeout. The caller is accounted as waiting
154 * for IO (which traditionally means blkio only).
156 void __sched
wait_for_completion_io(struct completion
*x
)
158 wait_for_common_io(x
, MAX_SCHEDULE_TIMEOUT
, TASK_UNINTERRUPTIBLE
);
160 EXPORT_SYMBOL(wait_for_completion_io
);
163 * wait_for_completion_io_timeout: - waits for completion of a task (w/timeout)
164 * @x: holds the state of this particular completion
165 * @timeout: timeout value in jiffies
167 * This waits for either a completion of a specific task to be signaled or for a
168 * specified timeout to expire. The timeout is in jiffies. It is not
169 * interruptible. The caller is accounted as waiting for IO (which traditionally
172 * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
173 * till timeout) if completed.
175 unsigned long __sched
176 wait_for_completion_io_timeout(struct completion
*x
, unsigned long timeout
)
178 return wait_for_common_io(x
, timeout
, TASK_UNINTERRUPTIBLE
);
180 EXPORT_SYMBOL(wait_for_completion_io_timeout
);
183 * wait_for_completion_interruptible: - waits for completion of a task (w/intr)
184 * @x: holds the state of this particular completion
186 * This waits for completion of a specific task to be signaled. It is
189 * Return: -ERESTARTSYS if interrupted, 0 if completed.
191 int __sched
wait_for_completion_interruptible(struct completion
*x
)
193 long t
= wait_for_common(x
, MAX_SCHEDULE_TIMEOUT
, TASK_INTERRUPTIBLE
);
194 if (t
== -ERESTARTSYS
)
198 EXPORT_SYMBOL(wait_for_completion_interruptible
);
201 * wait_for_completion_interruptible_timeout: - waits for completion (w/(to,intr))
202 * @x: holds the state of this particular completion
203 * @timeout: timeout value in jiffies
205 * This waits for either a completion of a specific task to be signaled or for a
206 * specified timeout to expire. It is interruptible. The timeout is in jiffies.
208 * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
209 * or number of jiffies left till timeout) if completed.
212 wait_for_completion_interruptible_timeout(struct completion
*x
,
213 unsigned long timeout
)
215 return wait_for_common(x
, timeout
, TASK_INTERRUPTIBLE
);
217 EXPORT_SYMBOL(wait_for_completion_interruptible_timeout
);
220 * wait_for_completion_killable: - waits for completion of a task (killable)
221 * @x: holds the state of this particular completion
223 * This waits to be signaled for completion of a specific task. It can be
224 * interrupted by a kill signal.
226 * Return: -ERESTARTSYS if interrupted, 0 if completed.
228 int __sched
wait_for_completion_killable(struct completion
*x
)
230 long t
= wait_for_common(x
, MAX_SCHEDULE_TIMEOUT
, TASK_KILLABLE
);
231 if (t
== -ERESTARTSYS
)
235 EXPORT_SYMBOL(wait_for_completion_killable
);
238 * wait_for_completion_killable_timeout: - waits for completion of a task (w/(to,killable))
239 * @x: holds the state of this particular completion
240 * @timeout: timeout value in jiffies
242 * This waits for either a completion of a specific task to be
243 * signaled or for a specified timeout to expire. It can be
244 * interrupted by a kill signal. The timeout is in jiffies.
246 * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
247 * or number of jiffies left till timeout) if completed.
250 wait_for_completion_killable_timeout(struct completion
*x
,
251 unsigned long timeout
)
253 return wait_for_common(x
, timeout
, TASK_KILLABLE
);
255 EXPORT_SYMBOL(wait_for_completion_killable_timeout
);
258 * try_wait_for_completion - try to decrement a completion without blocking
259 * @x: completion structure
261 * Return: 0 if a decrement cannot be done without blocking
262 * 1 if a decrement succeeded.
264 * If a completion is being used as a counting completion,
265 * attempt to decrement the counter without blocking. This
266 * enables us to avoid waiting if the resource the completion
267 * is protecting is not available.
269 bool try_wait_for_completion(struct completion
*x
)
275 * Since x->done will need to be locked only
276 * in the non-blocking case, we check x->done
277 * first without taking the lock so we can
278 * return early in the blocking case.
280 if (!READ_ONCE(x
->done
))
283 spin_lock_irqsave(&x
->wait
.lock
, flags
);
286 else if (x
->done
!= UINT_MAX
)
288 spin_unlock_irqrestore(&x
->wait
.lock
, flags
);
291 EXPORT_SYMBOL(try_wait_for_completion
);
294 * completion_done - Test to see if a completion has any waiters
295 * @x: completion structure
297 * Return: 0 if there are waiters (wait_for_completion() in progress)
298 * 1 if there are no waiters.
301 bool completion_done(struct completion
*x
)
303 if (!READ_ONCE(x
->done
))
307 * If ->done, we need to wait for complete() to release ->wait.lock
308 * otherwise we can end up freeing the completion before complete()
309 * is done referencing it.
311 * The RMB pairs with complete()'s RELEASE of ->wait.lock and orders
312 * the loads of ->done and ->wait.lock such that we cannot observe
313 * the lock before complete() acquires it while observing the ->done
314 * after it's acquired the lock.
317 spin_unlock_wait(&x
->wait
.lock
);
320 EXPORT_SYMBOL(completion_done
);