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