Documentation/scheduler/completion.txt

   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.