blob: 083d9c931b8ded8927e80d3a01a4babcd7501b9c [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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050014Completions are a code synchronization mechanism which are preferable to any
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010015misuse 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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050018advantage of using completions is clear intent of the code, but also more
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010019efficient 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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050027As completions are scheduling related, the code is found in
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010028kernel/sched/completion.c - for details on completion design and
29implementation see completions-design.txt
30
31
32Usage:
33------
34
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050035There are three parts to using completions, the initialization of the
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010036struct completion, the waiting part through a call to one of the variants of
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050037wait_for_completion() and the signaling side through a call to complete()
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010038or 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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050053Completions should be named to convey the intent of the waiter. A good
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010054example 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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050076wait queue. Calling init_completion() on the same completion object is
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010077most 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
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050090happy. Note also that one needs to make *sure* the completion passed to
Nicholas Mc Guire202799b2015-01-30 08:01:52 +010091work threads remains in-scope, and no references remain to on-stack data
92when the initiating function returns.
93
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -050094Using on-stack completions for code that calls any of the _timeout or
95_interruptible/_killable variants is not advisable as they will require
96additional synchronization to prevent the on-stack completion object in
97the timeout/signal cases from going out of scope. Consider using dynamically
98allocated completions when intending to use the _interruptible/_killable
99or _timeout variants of wait_for_completion().
100
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100101
102Waiting for completions:
103------------------------
104
105For a thread of execution to wait for some concurrent work to finish, it
106calls wait_for_completion() on the initialized completion structure.
107A typical usage scenario is:
108
109 structure completion setup_done;
110 init_completion(&setup_done);
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500111 initialize_work(...,&setup_done,...)
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100112
113 /* run non-dependent code */ /* do setup */
114
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500115 wait_for_completion(&setup_done); complete(setup_done)
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100116
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500117This is not implying any temporal order on wait_for_completion() and the
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100118call to complete() - if the call to complete() happened before the call
119to wait_for_completion() then the waiting side simply will continue
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500120immediately as all dependencies are satisfied if not it will block until
121completion is signaled by complete().
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100122
123Note that wait_for_completion() is calling spin_lock_irq/spin_unlock_irq
124so it can only be called safely when you know that interrupts are enabled.
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500125Calling it from hard-irq or irqs-off atomic contexts will result in hard
126to detect spurious enabling of interrupts.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100127
128wait_for_completion():
129
130 void wait_for_completion(struct completion *done):
131
132The default behavior is to wait without a timeout and mark the task as
133uninterruptible. wait_for_completion() and its variants are only safe
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500134in process context (as they can sleep) but not in atomic context,
135interrupt context, with disabled irqs. or preemption is disabled - see also
136try_wait_for_completion() below for handling completion in atomic/interrupt
137context.
138
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100139As all variants of wait_for_completion() can (obviously) block for a long
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500140time, you probably don't want to call this with held mutexes.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100141
142
143Variants available:
144-------------------
145
146The below variants all return status and this status should be checked in
147most(/all) cases - in cases where the status is deliberately not checked you
148probably want to make a note explaining this (e.g. see
149arch/arm/kernel/smp.c:__cpu_up()).
150
151A common problem that occurs is to have unclean assignment of return types,
152so care should be taken with assigning return-values to variables of proper
153type. Checking for the specific meaning of return values also has been found
154to be quite inaccurate e.g. constructs like
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500155if (!wait_for_completion_interruptible_timeout(...)) would execute the same
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100156code path for successful completion and for the interrupted case - which is
157probably not what you want.
158
159 int wait_for_completion_interruptible(struct completion *done)
160
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500161This function marks the task TASK_INTERRUPTIBLE. If a signal was received
162while waiting it will return -ERESTARTSYS and 0 otherwise.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100163
164 unsigned long wait_for_completion_timeout(struct completion *done,
165 unsigned long timeout)
166
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500167The task is marked as TASK_UNINTERRUPTIBLE and will wait at most 'timeout'
168(in jiffies). If timeout occurs it returns 0 else the remaining time in
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100169jiffies (but at least 1). Timeouts are preferably passed by msecs_to_jiffies()
170or usecs_to_jiffies(). If the returned timeout value is deliberately ignored
171a comment should probably explain why (e.g. see drivers/mfd/wm8350-core.c
172wm8350_read_auxadc())
173
174 long wait_for_completion_interruptible_timeout(
175 struct completion *done, unsigned long timeout)
176
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500177This function passes a timeout in jiffies and marking the task as
178TASK_INTERRUPTIBLE. If a signal was received it will return -ERESTARTSYS, 0 if
179completion timed out and the remaining time in jiffies if completion occurred.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100180
181Further variants include _killable which passes TASK_KILLABLE as the
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500182designated tasks state and will return -ERESTARTSYS if interrupted or
183else 0 if completion was achieved as well as a _timeout variant.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100184
185 long wait_for_completion_killable(struct completion *done)
186 long wait_for_completion_killable_timeout(struct completion *done,
187 unsigned long timeout)
188
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500189The _io variants wait_for_completion_io() behave the same as the non-_io
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100190variants, except for accounting waiting time as waiting on IO, which has
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500191an impact on how the task is accounted in scheduling stats.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100192
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
198Signaling completions:
199----------------------
200
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500201A thread that wants to signal that the conditions for continuation have been
202achieved calls complete() to signal exactly one of the waiters that it can
203continue.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100204
205 void complete(struct completion *done)
206
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500207or calls complete_all() to signal all current and future waiters.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100208
209 void complete_all(struct completion *done)
210
211The signaling will work as expected even if completions are signaled before
212a thread starts waiting. This is achieved by the waiter "consuming"
213(decrementing) the done element of struct completion. Waiting threads
214wakeup order is the same in which they were enqueued (FIFO order).
215
216If complete() is called multiple times then this will allow for that number
217of waiters to continue - each call to complete() will simply increment the
218done element. Calling complete_all() multiple times is a bug though. Both
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500219complete() and complete_all() can be called in hard-irq/atomic context safely.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100220
221There only can be one thread calling complete() or complete_all() on a
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500222particular struct completion at any time - serialized through the wait
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100223queue spinlock. Any such concurrent calls to complete() or complete_all()
224probably are a design bug.
225
226Signaling completion from hard-irq context is fine as it will appropriately
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500227lock with spin_lock_irqsave/spin_unlock_irqrestore and it will never sleep.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100228
229
230try_wait_for_completion()/completion_done():
231--------------------------------------------
232
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500233The try_wait_for_completion() function will not put the thread on the wait
234queue but rather returns false if it would need to enqueue (block) the thread,
235else it consumes any posted completions and returns true.
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100236
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500237 bool try_wait_for_completion(struct completion *done)
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100238
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500239Finally to check state of a completion without changing it in any way is
240provided by completion_done() returning false if there is any posted
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100241completion that was not yet consumed by waiters implying that there are
242waiters and true otherwise;
243
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500244 bool completion_done(struct completion *done)
Nicholas Mc Guire202799b2015-01-30 08:01:52 +0100245
246Both try_wait_for_completion() and completion_done() are safe to be called in
Nicholas Mc Guire4988aaa2015-02-20 12:28:48 -0500247hard-irq or atomic context.