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