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