1 ==============================================
2 Completions - "wait for completion" barrier AP
3 ==============================================
4
5 Introduction:
6 -------------
7
8 If you have one or more threads that must wait
9 to have reached a point or a specific state, c
10 race-free solution to this problem. Semantical
11 pthread_barrier() and have similar use-cases.
12
13 Completions are a code synchronization mechani
14 misuse of locks/semaphores and busy-loops. Any
15 yield() or some quirky msleep(1) loop to allow
16 you probably want to look into using one of th
17 calls and complete() instead.
18
19 The advantage of using completions is that the
20 purpose which makes it very easy to see the in
21 also result in more efficient code as all thre
22 until the result is actually needed, and both
23 is highly efficient using low level scheduler
24
25 Completions are built on top of the waitqueue
26 the Linux scheduler. The event the threads on
27 is reduced to a simple flag in 'struct complet
28
29 As completions are scheduling related, the cod
30 kernel/sched/completion.c.
31
32
33 Usage:
34 ------
35
36 There are three main parts to using completion
37
38 - the initialization of the 'struct completio
39 - the waiting part through a call to one of t
40 - the signaling side through a call to comple
41
42 There are also some helper functions for check
43 Note that while initialization must happen fir
44 part can happen in any order. I.e. it's entire
45 to have marked a completion as 'done' before a
46 it has to wait for it.
47
48 To use completions you need to #include <linux
49 create a static or dynamic variable of type 's
50 which has only two fields::
51
52 struct completion {
53 unsigned int done;
54 wait_queue_head_t wait;
55 };
56
57 This provides the ->wait waitqueue to place ta
58 the ->done completion flag for indicating whet
59
60 Completions should be named to refer to the ev
61 A good example is::
62
63 wait_for_completion(&early_console_add
64
65 complete(&early_console_added);
66
67 Good, intuitive naming (as always) helps code
68 'complete' is not helpful unless the purpose i
69
70
71 Initializing completions:
72 -------------------------
73
74 Dynamically allocated completion objects shoul
75 structures that are assured to be alive for th
76 to prevent races with asynchronous complete()
77
78 Particular care should be taken when using the
79 variants of wait_for_completion(), as it must
80 does not happen until all related activities (
81 have taken place, even if these wait functions
82 or a signal triggering.
83
84 Initializing of dynamically allocated completi
85 init_completion()::
86
87 init_completion(&dynamic_object->done)
88
89 In this call we initialize the waitqueue and s
90 or "not done".
91
92 The re-initialization function, reinit_complet
93 ->done field to 0 ("not done"), without touchi
94 Callers of this function must make sure that t
95 wait_for_completion() calls going on in parall
96
97 Calling init_completion() on the same completi
98 most likely a bug as it re-initializes the que
99 enqueued tasks could get "lost" - use reinit_c
100 but be aware of other races.
101
102 For static declaration and initialization, mac
103
104 For static (or global) declarations in file sc
105 DECLARE_COMPLETION()::
106
107 static DECLARE_COMPLETION(setup_done);
108 DECLARE_COMPLETION(setup_done);
109
110 Note that in this case the completion is boot
111 initialized to 'not done' and doesn't require
112
113 When a completion is declared as a local varia
114 then the initialization should always use DECL
115 explicitly, not just to make lockdep happy, bu
116 that limited scope had been considered and is
117
118 DECLARE_COMPLETION_ONSTACK(setup_done)
119
120 Note that when using completion objects as loc
121 acutely aware of the short life time of the fu
122 must not return to a calling context until all
123 threads) have ceased and the completion object
124
125 To emphasise this again: in particular when us
126 with more complex outcomes, such as the timeou
127 _killable() and _interruptible()) variants, th
128 prematurely while the object might still be in
129 from the wait_on_completion*() caller function
130 stack and cause subtle data corruption if a co
131 other thread. Simple testing might not trigger
132
133 If unsure, use dynamically allocated completio
134 in some other long lived object that has a bor
135 exceeds the life time of any helper threads us
136 or has a lock or other synchronization mechani
137 is not called on a freed object.
138
139 A naive DECLARE_COMPLETION() on the stack trig
140
141 Waiting for completions:
142 ------------------------
143
144 For a thread to wait for some concurrent activ
145 calls wait_for_completion() on the initialized
146
147 void wait_for_completion(struct comple
148
149 A typical usage scenario is::
150
151 CPU#1
152
153 struct completion setup_done;
154
155 init_completion(&setup_done);
156 initialize_work(...,&setup_done,...);
157
158 /* run non-dependent code */
159
160 wait_for_completion(&setup_done);
161
162 This is not implying any particular order betw
163 the call to complete() - if the call to comple
164 to wait_for_completion() then the waiting side
165 immediately as all dependencies are satisfied;
166 completion is signaled by complete().
167
168 Note that wait_for_completion() is calling spi
169 so it can only be called safely when you know
170 Calling it from IRQs-off atomic contexts will
171 spurious enabling of interrupts.
172
173 The default behavior is to wait without a time
174 uninterruptible. wait_for_completion() and its
175 in process context (as they can sleep) but not
176 interrupt context, with disabled IRQs, or pree
177 try_wait_for_completion() below for handling c
178 context.
179
180 As all variants of wait_for_completion() can (
181 time depending on the nature of the activity t
182 most cases you probably don't want to call thi
183
184
185 wait_for_completion*() variants available:
186 ------------------------------------------
187
188 The below variants all return status and this
189 most(/all) cases - in cases where the status i
190 probably want to make a note explaining this (
191 arch/arm/kernel/smp.c:__cpu_up()).
192
193 A common problem that occurs is to have unclea
194 so take care to assign return-values to variab
195
196 Checking for the specific meaning of return va
197 to be quite inaccurate, e.g. constructs like::
198
199 if (!wait_for_completion_interruptible
200
201 ... would execute the same code path for succe
202 interrupted case - which is probably not what
203
204 int wait_for_completion_interruptible(
205
206 This function marks the task TASK_INTERRUPTIBL
207 If a signal was received while waiting it will
208
209 unsigned long wait_for_completion_time
210
211 The task is marked as TASK_UNINTERRUPTIBLE and
212 jiffies. If a timeout occurs it returns 0, els
213 jiffies (but at least 1).
214
215 Timeouts are preferably calculated with msecs_
216 to make the code largely HZ-invariant.
217
218 If the returned timeout value is deliberately
219 why (e.g. see drivers/mfd/wm8350-core.c wm8350
220
221 long wait_for_completion_interruptible
222
223 This function passes a timeout in jiffies and
224 TASK_INTERRUPTIBLE. If a signal was received i
225 otherwise it returns 0 if the completion timed
226 jiffies if completion occurred.
227
228 Further variants include _killable which uses
229 designated tasks state and will return -ERESTA
230 or 0 if completion was achieved. There is a _
231
232 long wait_for_completion_killable(stru
233 long wait_for_completion_killable_time
234
235 The _io variants wait_for_completion_io() beha
236 variants, except for accounting waiting time a
237 an impact on how the task is accounted in sche
238
239 void wait_for_completion_io(struct com
240 unsigned long wait_for_completion_io_t
241
242
243 Signaling completions:
244 ----------------------
245
246 A thread that wants to signal that the conditi
247 achieved calls complete() to signal exactly on
248 continue::
249
250 void complete(struct completion *done)
251
252 ... or calls complete_all() to signal all curr
253
254 void complete_all(struct completion *d
255
256 The signaling will work as expected even if co
257 a thread starts waiting. This is achieved by t
258 (decrementing) the done field of 'struct compl
259 wakeup order is the same in which they were en
260
261 If complete() is called multiple times then th
262 of waiters to continue - each call to complete
263 done field. Calling complete_all() multiple ti
264 complete() and complete_all() can be called in
265
266 There can only be one thread calling complete(
267 particular 'struct completion' at any time - s
268 queue spinlock. Any such concurrent calls to c
269 probably are a design bug.
270
271 Signaling completion from IRQ context is fine
272 lock with spin_lock_irqsave()/spin_unlock_irqr
273 sleep.
274
275
276 try_wait_for_completion()/completion_done():
277 --------------------------------------------
278
279 The try_wait_for_completion() function will no
280 queue but rather returns false if it would nee
281 else it consumes one posted completion and ret
282
283 bool try_wait_for_completion(struct co
284
285 Finally, to check the state of a completion wi
286 call completion_done(), which returns false if
287 completions that were not yet consumed by wait
288 waiters) and true otherwise::
289
290 bool completion_done(struct completion
291
292 Both try_wait_for_completion() and completion_
293 IRQ or atomic context.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.