Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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 11 race-free solution to this problem. Semantically they are somewhat like a 12 pthread_barrier and have similar use-cases. 13 14 Completions are a code synchronization mechanism which 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. 29 30 31 Usage: 32 ------ 33 34 There are three parts to using completions, the initialization of the 35 struct completion, the waiting part through a call to one of the variants of 36 wait_for_completion() and the signaling side through a call to complete() 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 52 Completions should be named to convey the intent of the waiter. A good 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 75 wait queue. Calling init_completion() twice on the same completion object is 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 89 happy. Note also that one needs to make *sure* the completion passed to 90 work threads remains in-scope, and no references remain to on-stack data 91 when the initiating function returns. 92 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 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 108 struct completion setup_done; 109 init_completion(&setup_done); 110 initialize_work(...,&setup_done,...) 111 112 /* run non-dependent code */ /* do setup */ 113 114 wait_for_completion(&setup_done); complete(setup_done) 115 116 This is not implying any temporal order on wait_for_completion() and the 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 119 immediately as all dependencies are satisfied if not it will block until 120 completion is signaled by complete(). 121 122 Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(), 123 so it can only be called safely when you know that interrupts are enabled. 124 Calling it from hard-irq or irqs-off atomic contexts will result in 125 hard-to-detect spurious enabling of interrupts. 126 127 wait_for_completion(): 128 129 void wait_for_completion(struct completion *done): 130 131 The default behavior is to wait without a timeout and to mark the task as 132 uninterruptible. wait_for_completion() and its variants are only safe 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 138 As all variants of wait_for_completion() can (obviously) block for a long 139 time, you probably don't want to call this with held mutexes. 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 154 if (!wait_for_completion_interruptible_timeout(...)) would execute the same 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 160 This function marks the task TASK_INTERRUPTIBLE. If a signal was received 161 while waiting it will return -ERESTARTSYS; 0 otherwise. 162 163 unsigned long wait_for_completion_timeout(struct completion *done, 164 unsigned long timeout) 165 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 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()) 172 173 long wait_for_completion_interruptible_timeout( 174 struct completion *done, unsigned long timeout) 175 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. 180 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: 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 189 The _io variants wait_for_completion_io() behave the same as the non-_io 190 variants, except for accounting waiting time as waiting on IO, which has 191 an impact on how the task is accounted in scheduling stats. 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 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. 204 205 void complete(struct completion *done) 206 207 or calls complete_all() to signal all current and future waiters. 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 219 complete() and complete_all() can be called in hard-irq/atomic context safely. 220 221 There only can be one thread calling complete() or complete_all() on a 222 particular struct completion at any time - serialized through the wait 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 227 lock with spin_lock_irqsave/spin_unlock_irqrestore and it will never sleep. 228 229 230 try_wait_for_completion()/completion_done(): 231 -------------------------------------------- 232 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, 235 else it consumes one posted completion and returns true. 236 237 bool try_wait_for_completion(struct completion *done) 238 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; 243 244 bool completion_done(struct completion *done) 245 246 Both try_wait_for_completion() and completion_done() are safe to be called in 247 hard-irq or atomic context.