]> git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blame - Documentation/scheduler/completion.txt
Merge branch 'irq-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel...
[mirror_ubuntu-bionic-kernel.git] / Documentation / scheduler / completion.txt
CommitLineData
202799be
NMG
1completions - wait for completion handling
2==========================================
3
4This document was originally written based on 3.18.0 (linux-next)
5
6Introduction:
7-------------
8
9If you have one or more threads of execution that must wait for some process
7085f6c3
JC
10to have reached a point or a specific state, completions can provide a
11race-free solution to this problem. Semantically they are somewhat like a
12pthread_barrier and have similar use-cases.
202799be 13
7085f6c3 14Completions are a code synchronization mechanism which is preferable to any
202799be 15misuse of locks. Any time you think of using yield() or some quirky
7085f6c3 16msleep(1) loop to allow something else to proceed, you probably want to
202799be 17look into using one of the wait_for_completion*() calls instead. The
4988aaa6 18advantage of using completions is clear intent of the code, but also more
202799be
NMG
19efficient code as both threads can continue until the result is actually
20needed.
21
22Completions are built on top of the generic event infrastructure in Linux,
7085f6c3
JC
23with the event reduced to a simple flag (appropriately called "done") in
24struct completion that tells the waiting threads of execution if they
202799be
NMG
25can continue safely.
26
4988aaa6 27As completions are scheduling related, the code is found in
dc92726e 28kernel/sched/completion.c.
202799be
NMG
29
30
31Usage:
32------
33
4988aaa6 34There are three parts to using completions, the initialization of the
202799be 35struct completion, the waiting part through a call to one of the variants of
4988aaa6 36wait_for_completion() and the signaling side through a call to complete()
202799be
NMG
37or complete_all(). Further there are some helper functions for checking the
38state of completions.
39
40To use completions one needs to include <linux/completion.h> and
41create a variable of type struct completion. The structure used for
42handling of completions is:
43
44 struct completion {
45 unsigned int done;
46 wait_queue_head_t wait;
47 };
48
49providing the wait queue to place tasks on for waiting and the flag for
50indicating the state of affairs.
51
4988aaa6 52Completions should be named to convey the intent of the waiter. A good
202799be
NMG
53example is:
54
55 wait_for_completion(&early_console_added);
56
57 complete(&early_console_added);
58
59Good naming (as always) helps code readability.
60
61
62Initializing completions:
63-------------------------
64
65Initialization of dynamically allocated completions, often embedded in
66other structures, is done with:
67
68 void init_completion(&done);
69
70Initialization is accomplished by initializing the wait queue and setting
71the default state to "not available", that is, "done" is set to 0.
72
73The re-initialization function, reinit_completion(), simply resets the
74done element to "not available", thus again to 0, without touching the
7085f6c3 75wait queue. Calling init_completion() twice on the same completion object is
202799be
NMG
76most likely a bug as it re-initializes the queue to an empty queue and
77enqueued tasks could get "lost" - use reinit_completion() in that case.
78
79For static declaration and initialization, macros are available. These are:
80
81 static DECLARE_COMPLETION(setup_done)
82
83used for static declarations in file scope. Within functions the static
84initialization should always use:
85
86 DECLARE_COMPLETION_ONSTACK(setup_done)
87
88suitable for automatic/local variables on the stack and will make lockdep
4988aaa6 89happy. Note also that one needs to make *sure* the completion passed to
202799be
NMG
90work threads remains in-scope, and no references remain to on-stack data
91when the initiating function returns.
92
4988aaa6
NMG
93Using on-stack completions for code that calls any of the _timeout or
94_interruptible/_killable variants is not advisable as they will require
95additional synchronization to prevent the on-stack completion object in
96the timeout/signal cases from going out of scope. Consider using dynamically
97allocated completions when intending to use the _interruptible/_killable
98or _timeout variants of wait_for_completion().
99
202799be
NMG
100
101Waiting for completions:
102------------------------
103
104For a thread of execution to wait for some concurrent work to finish, it
105calls wait_for_completion() on the initialized completion structure.
106A typical usage scenario is:
107
7085f6c3 108 struct completion setup_done;
202799be 109 init_completion(&setup_done);
4988aaa6 110 initialize_work(...,&setup_done,...)
202799be
NMG
111
112 /* run non-dependent code */ /* do setup */
113
4988aaa6 114 wait_for_completion(&setup_done); complete(setup_done)
202799be 115
4988aaa6 116This is not implying any temporal order on wait_for_completion() and the
202799be
NMG
117call to complete() - if the call to complete() happened before the call
118to wait_for_completion() then the waiting side simply will continue
4988aaa6
NMG
119immediately as all dependencies are satisfied if not it will block until
120completion is signaled by complete().
202799be 121
7085f6c3 122Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(),
202799be 123so it can only be called safely when you know that interrupts are enabled.
7085f6c3
JC
124Calling it from hard-irq or irqs-off atomic contexts will result in
125hard-to-detect spurious enabling of interrupts.
202799be
NMG
126
127wait_for_completion():
128
129 void wait_for_completion(struct completion *done):
130
7085f6c3 131The default behavior is to wait without a timeout and to mark the task as
202799be 132uninterruptible. wait_for_completion() and its variants are only safe
4988aaa6
NMG
133in process context (as they can sleep) but not in atomic context,
134interrupt context, with disabled irqs. or preemption is disabled - see also
135try_wait_for_completion() below for handling completion in atomic/interrupt
136context.
137
202799be 138As all variants of wait_for_completion() can (obviously) block for a long
4988aaa6 139time, you probably don't want to call this with held mutexes.
202799be
NMG
140
141
142Variants available:
143-------------------
144
145The below variants all return status and this status should be checked in
146most(/all) cases - in cases where the status is deliberately not checked you
147probably want to make a note explaining this (e.g. see
148arch/arm/kernel/smp.c:__cpu_up()).
149
150A common problem that occurs is to have unclean assignment of return types,
151so care should be taken with assigning return-values to variables of proper
152type. Checking for the specific meaning of return values also has been found
153to be quite inaccurate e.g. constructs like
4988aaa6 154if (!wait_for_completion_interruptible_timeout(...)) would execute the same
202799be
NMG
155code path for successful completion and for the interrupted case - which is
156probably not what you want.
157
158 int wait_for_completion_interruptible(struct completion *done)
159
4988aaa6 160This function marks the task TASK_INTERRUPTIBLE. If a signal was received
7085f6c3 161while waiting it will return -ERESTARTSYS; 0 otherwise.
202799be
NMG
162
163 unsigned long wait_for_completion_timeout(struct completion *done,
164 unsigned long timeout)
165
4988aaa6
NMG
166The task is marked as TASK_UNINTERRUPTIBLE and will wait at most 'timeout'
167(in jiffies). If timeout occurs it returns 0 else the remaining time in
7085f6c3
JC
168jiffies (but at least 1). Timeouts are preferably calculated with
169msecs_to_jiffies() or usecs_to_jiffies(). If the returned timeout value is
170deliberately ignored a comment should probably explain why (e.g. see
171drivers/mfd/wm8350-core.c wm8350_read_auxadc())
202799be
NMG
172
173 long wait_for_completion_interruptible_timeout(
174 struct completion *done, unsigned long timeout)
175
7085f6c3
JC
176This function passes a timeout in jiffies and marks the task as
177TASK_INTERRUPTIBLE. If a signal was received it will return -ERESTARTSYS;
178otherwise it returns 0 if the completion timed out or the remaining time in
179jiffies if completion occurred.
202799be 180
7085f6c3
JC
181Further variants include _killable which uses TASK_KILLABLE as the
182designated tasks state and will return -ERESTARTSYS if it is interrupted or
183else 0 if completion was achieved. There is a _timeout variant as well:
202799be
NMG
184
185 long wait_for_completion_killable(struct completion *done)
186 long wait_for_completion_killable_timeout(struct completion *done,
187 unsigned long timeout)
188
4988aaa6 189The _io variants wait_for_completion_io() behave the same as the non-_io
202799be 190variants, except for accounting waiting time as waiting on IO, which has
4988aaa6 191an impact on how the task is accounted in scheduling stats.
202799be
NMG
192
193 void wait_for_completion_io(struct completion *done)
194 unsigned long wait_for_completion_io_timeout(struct completion *done
195 unsigned long timeout)
196
197
198Signaling completions:
199----------------------
200
4988aaa6
NMG
201A thread that wants to signal that the conditions for continuation have been
202achieved calls complete() to signal exactly one of the waiters that it can
203continue.
202799be
NMG
204
205 void complete(struct completion *done)
206
4988aaa6 207or calls complete_all() to signal all current and future waiters.
202799be
NMG
208
209 void complete_all(struct completion *done)
210
211The signaling will work as expected even if completions are signaled before
212a thread starts waiting. This is achieved by the waiter "consuming"
213(decrementing) the done element of struct completion. Waiting threads
214wakeup order is the same in which they were enqueued (FIFO order).
215
216If complete() is called multiple times then this will allow for that number
217of waiters to continue - each call to complete() will simply increment the
218done element. Calling complete_all() multiple times is a bug though. Both
4988aaa6 219complete() and complete_all() can be called in hard-irq/atomic context safely.
202799be
NMG
220
221There only can be one thread calling complete() or complete_all() on a
4988aaa6 222particular struct completion at any time - serialized through the wait
202799be
NMG
223queue spinlock. Any such concurrent calls to complete() or complete_all()
224probably are a design bug.
225
226Signaling completion from hard-irq context is fine as it will appropriately
4988aaa6 227lock with spin_lock_irqsave/spin_unlock_irqrestore and it will never sleep.
202799be
NMG
228
229
230try_wait_for_completion()/completion_done():
231--------------------------------------------
232
4988aaa6
NMG
233The try_wait_for_completion() function will not put the thread on the wait
234queue but rather returns false if it would need to enqueue (block) the thread,
7085f6c3 235else it consumes one posted completion and returns true.
202799be 236
4988aaa6 237 bool try_wait_for_completion(struct completion *done)
202799be 238
7085f6c3
JC
239Finally, to check the state of a completion without changing it in any way,
240call completion_done(), which returns false if there are no posted
241completions that were not yet consumed by waiters (implying that there are
242waiters) and true otherwise;
202799be 243
4988aaa6 244 bool completion_done(struct completion *done)
202799be
NMG
245
246Both try_wait_for_completion() and completion_done() are safe to be called in
4988aaa6 247hard-irq or atomic context.